Go 错误处理应使用可断言的自定义 *AppError 类型携带上下文与分类码，HTTP 层统一拦截转响应，避免包装堆叠、panic 替代和 context 传 error。
Go 语言没有异常机制，error 是一等公民，但直接在每处 if err != nil 处理会导致重复、分散、难以追踪错误来源。真正的统一处理不是“抹掉错误”，而是建立可追溯、可分类、可干预的错误流转链路。
用自定义 error 类型携带上下文和分类标识
标准 errors.New 或 fmt.Errorf 生成的 error 不带类型信息，无法做 switch 分支处理。必须让 error 可识别、可断言。
推荐做法是定义带字段的结构体 error，并实现 Error() 方法：
type AppError struct {Code int `json:"code"` Message string `json:"message"` TraceID string `json:"trace_id,omitempty"` Op string `json:"op,omitempty"` // 操作名，如 "user.login"} func (e *AppError) Error() string { return fmt.Sprintf("[%d] %s", e.Code, e.Message) } func NewAppError(code int, msg string, op string) *AppError {return &AppError{ Code: code, Message: msg, Op: op, TraceID: getTraceID(), // 从 context 或全局获取 } }- 避免用
errors.Wrap堆叠多层包装——它只适合调试，不便于下游判断类型 - 所有业务错误都应返回
*AppError，而非error接口，方便if e, ok := err.(*AppError)断言 -
Code建议按域划分：4xx（客户端错）、5xx（服务端错）、1xx（业务逻辑错），例如401表示未授权，1001表示用户不存在
在 HTTP handler 中集中拦截并标准化响应
HTTP 层是错误出口的统一闸口，所有 handler 都应返回 error，由中间件捕获并转为 HTTP 状态码 与 JSON 响应。
立即学习“go 语言免费学习笔记（深入）”；
关键点在于：不要在 handler 内部写 w.WriteHeader() 和 json.Marshal，交给中间件做：
func ErrorHandler(next http.Handler) http.Handler {return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {defer func() {if r := recover(); r != nil {http.Error(w, "Internal Server Error", http.StatusInternalServerError) log.Printf("panic: %v", r) } }() next.ServeHTTP(w, r) }) } // 更实用的是基于 error 返回值的 wrapper（配合 handler 函数签名变更）type HandlerFunc func(http.ResponseWriter, *http.Request) error func Handle(h HandlerFunc) http.HandlerFunc {return func(w http.ResponseWriter, r *http.Request) {err := h(w, r) if err == nil {return} var appErr *AppError if errors.As(err, &appErr) {w.Header().Set("Content-Type", "application/json; charset=utf-8") w.WriteHeader(appErr.HTTPStatus()) json.NewEncoder(w).Encode(appErr) return } // 非 AppError，当作 500 处理 w.WriteHeader(http.StatusInternalServerError) json.NewEncoder(w).Encode(&AppError{ Code: 50000, Message: "Unknown server error", Op: "unknown",}) } }- 不要依赖
http.Error—— 它只能写字符串，无法控制 status code 细粒度或加 trace_id - 务必检查
errors.As而非==或errors.Is，因为业务 error 往往是包装过的 - panic 捕获仅用于兜底，不能替代 error 处理；真实错误应显式返回，而非 panic
用 context.Value 透传错误上下文（谨慎使用）
有些场景需要跨多层函数传递错误元信息，比如重试次数、上游服务名、是否允许重试。此时可将轻量级结构体塞进 context.Context，但绝不能用来“代替 error 返回”。
正确用法示例：
type ErrorContextKey string const ErrCtxKey ErrorContextKey = "error_ctx" type ErrorMeta struct {RetryCount int Upstream string CanRetry bool} func WithErrorMeta(ctx context.Context, meta ErrorMeta) context.Context {return context.WithValue(ctx, ErrCtxKey, meta) } func GetErrorMeta(ctx context.Context) (ErrorMeta, bool) {v, ok := ctx.Value(ErrCtxKey).(ErrorMeta) return v, ok }- 仅存元数据，不存 error 实例本身——避免 context 泄露或生命周期混乱
- 不要在 middleware 中覆盖已有
ErrorMeta，应 merge 而非 replace - 若 error 已含足够字段（如
TraceID、Op），优先复用 error 结构，而非额外塞 context
最易被忽略的一点：统一错误处理 ≠ 统一掩盖错误。每个 *AppError 的 Op 字段必须真实反映出错位置（如 "order.create_payment"），否则日志聚合和链路追踪就失去意义。宁愿多写一行 return NewAppError(1002, "payment timeout", "order.create_payment")，也不要图省事返回一个泛化的 "operation failed"。
