直接在每个函数写 if err != nil 会重复冗长、淹没业务逻辑，且难以统一加日志、重试或转HTTP状态码；defer+panic不可行，因panic不处理普通error、破坏栈、影响性能，且Go官方反对；可行方案是中间件模式+分层错误封装：定义带Code/Message/Status/Err的AppError类型，并在handler入口统一处理，同时用%w保持错误链、避免context.Value传traceID。
为什么不能直接在每个函数里写 if err != nil 套路？
因为重复写 if err != nil { return err } 不仅冗长，还会让业务逻辑被错误处理淹没。更关键的是：一旦要加日志、重试、错误分类或统一转成 HTTP 状态码，就得改几十个地方——漏一处就可能线上返回 500 却没日志，或者敏感错误信息直接暴露给前端。
用 defer + 自定义 error wrapper 集中捕获？不推荐
有人想在函数入口用 defer 捕获 panic 再转 error，这条路走不通：defer 无法捕获普通 return err，只能兜底 panic；而主动 panic 错误会破坏调用栈、影响性能，且 Go 官方明确反对用 panic 处理可预期错误。
- panic 不是 error 的替代品，
errors.Is(err, io.EOF)对 panic 无效 - HTTP handler 里 recover 后很难还原原始错误上下文（比如哪个 DB 查询失败）
- 单元测试时需额外 mock panic 行为，成本高
真正可行的集中处理：中间件模式 + error 分类包装
核心思路不是“拦截所有 error”，而是让 error 带上类型、上下文、可操作标记，再由顶层（如 HTTP handler 或 CLI 入口）统一决策怎么处理。关键在两层封装：
第一层：定义带语义的错误类型
type AppError struct {
Code string // "user_not_found", "db_timeout"
Message string // 用户友好的提示（非 debug 信息）
Err error // 底层原始 error，用于日志和调试
Status int // 对应 HTTP 状态码，如 404, 500
}
func (e *AppError) Error() string { return e.Message }
func (e *AppError) Unwrap() error { return e.Err }
第二层：在 handler 入口做统一转换
func HandleUserRequest(w http.ResponseWriter, r *http.Request) {
defer func() {
if r := recover(); r != nil {
log.Printf("panic: %v", r)
http.Error(w, "Internal Server Error", http.StatusInternalServerError)
}
}()
err := userService.GetUser(r.Context(), userID)
if err != nil {
var appErr *AppError
if errors.As(err, &appErr) {
http.Error(w, appErr.Message, appErr.Status)
} else {
log.Printf("unhandled error: %+v", err) // 记原始 error
http.Error(w, "Internal Server Error", http.StatusInternalServerError)
}
return
}
// ... 正常响应
}
- 所有业务函数仍按 Go 习惯返回
error，但优先返回*AppError - 数据库层、RPC 层等可封装自己的错误映射，比如
pgx.ErrNoRows → &AppError{Code: "user_not_found", Status: 404} - 避免在中间层（如 service 层）做
log.Printf—— 日志只在顶层或专门 logger 统一打
容易被忽略的细节：error 链与 context 透传
真实场景中，错误往往跨多层调用（HTTP → Service → Repository → Driver），必须保留完整链路。Go 1.13+ 的 errors.Unwrap 和 %+v 格式化能帮你做到这点，但前提是每层都用 fmt.Errorf("xxx: %w", err) 包装，而不是 fmt.Errorf("xxx: %v", err)。
- 错：
return fmt.Errorf("failed to query user: %v", err)→ 断开 error 链 - 对：
return fmt.Errorf("failed to query user: %w", err)→ 可用errors.Is(err, sql.ErrNoRows)判断 - context.Value 里塞 traceID？别这么做。改用
ctx = context.WithValue(ctx, keyTraceID, id)+ 自定义 error 字段更可靠
最麻烦的其实是第三方库返回的 error —— 它们通常不支持 %w。这时要么用 errors.Join（Go 1.20+）合并，要么老老实实写一个适配 wrapper 函数，把原始 error 塞进 AppError.Err 字段里。别省这一步，否则排查时你根本不知道是哪条 SQL 超时。
