统一错误处理需拦截业务错误、标准化响应结构、防止信息泄露并正确映射http状态码；通过ErrorResponse结构定义业务码与消息，用中间件捕获panic和error，handler返回(Interface{}, error)，由ResultHandler统一渲染，并按appError.Code映射合理HTTP状态码。
在 golang Web 开发中，统一错误处理的核心是拦截业务错误、标准化响应结构、避免敏感信息泄露，并保持 HTTP 状态码语义正确。不推荐直接在每个 handler 里写 if err != nil + json.NewEncoder(w).Encode(...)，那样重复且易出错。
定义统一错误响应结构
先设计一个前端友好的 json 错误格式，包含状态码、错误码、消息和可选的详情：
type ErrorResponse struct { Code int `json:"code"` // 业务错误码，如 1001 Message string `json:"message"` // 用户可见提示 TraceID string `json:"trace_id,omitempty` // 用于日志追踪（可选） }
注意：HTTP 状态码（如 400、500）由 w.WriteHeader() 控制，不要和 Code 字段混淆。前者告诉客户端“请求是否成功”，后者告诉前端“具体哪类业务失败”。
封装中间件统一捕获 panic 和错误
用中间件包裹 handler，集中处理两类异常：
立即学习“go语言免费学习笔记（深入）”；
- 显式返回的
error（例如校验失败、DB 查询为空） - 未捕获的 panic（如空指针、数组越界）
func ErrorHandler(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { defer func() { if err := recover(); err != nil { http.Error(w, "internal Server Error", http.StatusInternalServerError) log.Printf("PANIC: %v, trace: %s", err, debug.Stack()) } }() // 包装 ResponseWriter，捕获 WriteHeader 调用（可选：用于日志或重写状态码） rw := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK} next.ServeHTTP(rw, r) // 如果 handler 显式返回了 error（需配合自定义 context 或返回值约定），此处可扩展处理 // 更推荐：handler 返回 (interface{}, error)，由中间件判断并渲染 }) }
让 handler 返回 error 并交由中间件渲染
修改 handler 签名，使其返回 (interface{}, error)，再用中间件做最终响应：
type Result struct { Data interface{} `json:"data,omitempty"` Error *ErrorResponse `json:"error,omitempty"` } func UserHandler(w http.ResponseWriter, r *http.Request) (interface{}, error) { id := chi.URLParam(r, "id") if id == "" { return nil, &AppError{Code: 1001, Message: "用户 ID 不能为空"} } user, err := db.GetUser(id) if err != nil { return nil, &AppError{Code: 1002, Message: "用户不存在"} } return user, nil } // 中间件解析 result 并写入响应 func ResultHandler(handler func(http.ResponseWriter, *http.Request) (interface{}, error)) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { data, err := handler(w, r) if err != nil { // 假设 AppError 实现了 error 接口，并携带 Code/Message appErr, ok := err.(*AppError) if !ok { appErr = &AppError{Code: 5000, Message: "未知错误"} } w.Header().Set("Content-Type", "application/json; charset=utf-8") w.WriteHeader(appErr.HTTPStatus()) // 如 400 → 400，500 → 500 json.NewEncoder(w).Encode(Result{Error: &ErrorResponse{ Code: appErr.Code, Message: appErr.Message, TraceID: getTraceID(r), }}) return } w.Header().Set("Content-Type", "application/json; charset=utf-8") w.WriteHeader(http.StatusOK) json.NewEncoder(w).Encode(Result{Data: data}) }) }
区分错误类型，合理设置 HTTP 状态码
不同错误应映射到不同 HTTP 状态码，帮助前端做差异化处理：
- 客户端错误（参数缺失、格式错误、权限不足）→
400 Bad Request/401 Unauthorized/403 Forbidden - 资源未找到 →
404 Not Found - 服务端内部错误（DB 挂了、第三方超时）→
500 Internal Server Error或503 Service Unavailable
建议封装一个 AppError 类型，内置 HTTPStatus() 方法，避免硬编码状态码：
type AppError struct { Code int Message string status int // 对应 HTTP 状态码 } func (e *AppError) HTTPStatus() int { switch e.Code { case 1001, 1002: return http.StatusbadRequest case 1003: return http.StatusForbidden case 1004: return http.StatusNotFound default: return http.StatusInternalServerError } }