统一错误格式的关键是选择性封装第三方错误并保留原始上下文，区分可恢复业务错误与需透传的底层错误；推荐轻量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
}
// ...
}
