统一错误处理需拦截业务错误、标准化响应结构、防止信息泄露并正确映射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
}
}
