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"。
