Go中统一错误处理需定义AppError结构体封装状态码、业务码、消息等，业务函数返回*AppError，HTTP层用中间件拦截并序列化为标准JSON响应，兼顾安全与日志可追溯性。
在 Go 中实现统一错误处理并封装函数返回统一格式，核心是定义清晰的错误结构、规范错误创建方式、统一响应体，并在 HTTP 层或业务入口处集中拦截和转换错误。不依赖框架也能做到简洁可控。
定义统一错误类型与错误码
避免直接返回 error 接口导致信息丢失，自定义结构体携带状态码、业务码、消息和可选详情：
type AppError struct {
Code int `json:"code"` // HTTP 状态码（如 400、500）
ErrCode int `json:"err_code"` // 业务错误码（如 1001 表示用户不存在）
Msg string `json:"msg"`
Details []string `json:"details,omitempty"`
}
func (e *AppError) Error() string {
return fmt.Sprintf("[%d]%s", e.ErrCode, e.Msg)
}
// 快捷构造函数
func NewBadRequest(errCode int, msg string, details ...string) *AppError {
return &AppError{Code: 400, ErrCode: errCode, Msg: msg, Details: details}
}
func NewInternalError(errCode int, msg string, details ...string) *AppError {
return &AppError{Code: 500, ErrCode: errCode, Msg: msg, Details: details}
}
业务函数统一返回 (data, error)
所有服务层函数遵循相同签名，错误一律用 *AppError，不混用标准 errors.New 或 fmt.Errorf：
- 成功时返回数据和
nil - 失败时返回零值和具体
*AppError，不 panic，不裸露底层错误（如数据库驱动错误） - 例如：
user, err := userService.GetUserByID(ctx, id)，err类型为error，但实际应为*AppError
HTTP 层统一拦截并序列化响应
在 handler 中用 defer 或中间件捕获错误，转为标准 JSON 响应：
立即学习“go语言免费学习笔记（深入）”；
func jsonHandler(f func() (interface{}, error)) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
data, err := f()
if err != nil {
var appErr *AppError
if errors.As(err, &appErr) {
w.WriteHeader(appErr.Code)
json.NewEncoder(w).Encode(map[string]interface{}{
"success": false,
"data": nil,
"error": appErr,
})
return
}
// 非 AppError，兜底为 500
w.WriteHeader(500)
json.NewEncoder(w).Encode(map[string]interface{}{
"success": false,
"data": nil,
"error": &AppError{Code: 500, ErrCode: 9999, Msg: "Unknown server error"},
})
return
}
w.WriteHeader(200)
json.NewEncoder(w).Encode(map[string]interface{}{
"success": true,
"data": data,
"error": nil,
})
}
}
// 使用示例
http.HandleFunc("/api/user/:id", jsonHandler(func() (interface{}, error) {
id := chi.URLParam(r, "id")
user, err := userService.GetUserByID(r.Context(), id)
if err != nil {
return nil, err // 直接返回 *AppError
}
return user, nil
}))
日志与错误透传的平衡
对外响应要简洁安全，对内日志需保留上下文：
- 返回给前端的
Msg应通用友好（如“用户名已存在”），不暴露技术细节 - 记录日志时，补充 traceID、参数、原始错误栈（可用
fmt.Sprintf("%+v", err)） - 必要时在
*AppError中加字段LogID string关联日志，但不返回给客户端
