统一错误格式的关键是选择性封装第三方错误并保留原始上下文，区分可恢复业务错误与需透传的底层错误；推荐轻量 AppError 结构体，仅在错误语义转变时封装，HTTP 层通过中间件统一处理。
在 Go 项目中，统一错误格式的核心不是“包装所有错误”，而是 有选择地封装第三方错误，同时保留原始上下文和语义。关键在于区分“可恢复的业务错误”和“需透传的底层错误”，避免过度封装导致调试困难。
明确错误分类边界
Go 的 error 是接口，但不同来源的错误应有不同的处理策略：
- 第三方库返回的 error（如 database/sql、redis、http.Client）：多数是底层异常（连接失败、超时、协议错误），应原样透传或仅加一层上下文，不强行转成业务错误码
- 业务逻辑主动 return 的 error（如用户不存在、参数校验失败）：适合封装为带 code、message、details 的结构体错误
- panic 捕获的 error（如空指针、越界）：不应封装，而应记录 panic 栈 并转为系统级错误（500）
定义内部错误结构体
推荐轻量结构，避免嵌套过深：
type AppError struct {Code int `json:"code"` // HTTP 状态码或自定义业务码，如 4001（用户未登录）Message string `json:"message"` // 用户 / 前端可见提示 Details string `json:"details,omitempty"` // 可选，用于日志追踪（如 SQL、请求 ID、参数快照）} func (e *AppError) Error() string { return e.Message} // 实现 Unwrap 支持 errors.Is/As func (e *AppError) Unwrap() error { return nil}
注意：不要让 AppError 包含原始 error 字段并实现 Unwrap 返回它——这会破坏错误链语义。若需保留原始错误，用 errors.Join 或 errors.WithStack（需搭配第三方库如 github.com/pkg/errors）。
立即学习“go 语言免费学习笔记（深入）”；
封装时机与方式
只在 错误语义发生转变 时封装：
- 数据库查询返回 sql.ErrNoRows → 封装为“用户不存在”（code=404）
- 调用下游 HTTP 接口返回 401 → 封装为“认证失效，请重新登录”（code=401）
- redis.Conn.Do 返回 timeout error → 不封装，直接 return，由上层中间件统一转为 503
示例：
func (s *UserService) GetUser(ctx context.Context, id int) (*User, error) {u, err := s.db.GetUserByID(ctx, id) if err != nil {if errors.Is(err, sql.ErrNoRows) {return nil, &AppError{ Code: 404, Message: " 用户不存在 ", Details: fmt.Sprintf("user_id=%d", id), } } return nil, err // 其他 db 错误（如连接中断）直接透传 } return u, nil }
全局错误处理中间件
HTTP 层统一拦截，将 error 转为标准响应：
func ErrorHandler(next http.Handler) http.Handler {return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {defer func() {if r := recover(); r != nil {log.Printf("panic: %v", r) writeErrorResponse(w, 500, " 系统繁忙，请稍后再试 ") return } }() next.ServeHTTP(w, r) }) } func writeErrorResponse(w http.ResponseWriter, statusCode int, message string) {w.Header().Set("Content-Type", "application/json; charset=utf-8") w.WriteHeader(statusCode) json.NewEncoder(w).Encode(map[string]interface{}{ "code": statusCode, "message": message,}) }
在 handler 中只需：
func (h *UserHandler) Get(w http.ResponseWriter, r *http.Request) {user, err := h.service.GetUser(r.Context(), userID) if err != nil {// 若是 *AppError，取其 Code 和 Message；否则默认 500 code := 500 msg := " 系统繁忙 " if appErr, ok := err.(*AppError); ok {code = appErr.Code msg = appErr.Message} writeErrorResponse(w, code, msg) return } // …… }
