Go HTTP服务应统一错误处理：定义AppError封装状态码与消息，用中间件拦截并返回标准化Response JSON响应，确保前后端响应结构一致、状态码明确、前端易处理。
在 Go 中构建 HTTP 服务时，直接 panic 或返回裸错误（如 http.Error）会导致响应结构不一致、状态码混乱、前端难处理。要实现“捕获错误并返回统一响应”，核心是：**统一错误包装 + 中间件拦截 + 标准化 JSON 响应**。
定义统一响应结构
先设计一个前后端约定的响应格式，通常包含状态码、业务码、消息、数据等字段：
示例：
type Response struct {
Code int `json:"code"` // HTTP 状态码（或自定义业务码）
Status string `json:"status"` // "success" / "error"
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
}
建议将 Code 设为 HTTP 状态码（如 200、400、500），便于代理/网关识别；也可额外加 ErrorCode int 字段用于区分业务错误类型（如 1001=用户不存在，1002=参数错误）。
立即学习“go语言免费学习笔记（深入）”；
封装错误类型与中间件拦截
避免用字符串或 errors.New 传递错误，而是定义可携带状态码和消息的错误类型：
type AppError struct {
Code int
Message string
}
func (e *AppError) Error() string { return e.Message }
// 快捷构造函数
func BadRequest(msg string) error { return &AppError{Code: 400, Message: msg} }
func Unauthorized(msg string) error { return &AppError{Code: 401, Message: msg} }
func InternalError(msg string) error { return &AppError{Code: 500, Message: msg} }
然后写一个中间件，在 handler 执行后检查是否返回了 *AppError，并转为标准响应：
func ErrorHandler(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 捕获 panic（可选，兜底）
defer func() {
if err := recover(); err != nil {
writeErrorResponse(w, InternalError("server panic"))
}
}()
// 包装 ResponseWriter，记录状态码
rw := &responseWriter{ResponseWriter: w, statusCode: 200}
next.ServeHTTP(rw, r)
// 如果 handler 写入了非 2xx 状态码，且没手动响应，这里可补救
// 但更推荐：只让 AppError 触发错误响应，正常流程始终返回 200 + success
})
}
func writeErrorResponse(w http.ResponseWriter, err error) {
var appErr *AppError
if errors.As(err, &appErr) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
w.WriteHeader(appErr.Code)
json.NewEncoder(w).Encode(Response{
Code: appErr.Code,
Status: "error",
Message: appErr.Message,
Data: nil,
})
} else {
w.WriteHeader(500)
json.NewEncoder(w).Encode(Response{
Code: 500,
Status: "error",
Message: "internal server error",
Data: nil,
})
}
}
在 Handler 中主动抛出 AppError
业务逻辑中不再用 http.Error，而是返回错误或直接 panic（配合中间件 recover）：
- 使用
return BadRequest("email is required")退出 handler - 在 handler 函数签名中支持返回
error，用辅助函数包装：
func handleUserCreate(w http.ResponseWriter, r *http.Request) {
if r.Method != "POST" {
writeErrorResponse(w, BadRequest("only POST allowed"))
return
}
var req UserCreateReq
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeErrorResponse(w, BadRequest("invalid JSON"))
return
}
if req.Email == "" {
writeErrorResponse(w, BadRequest("email is required"))
return
}
// ... 业务逻辑
writeSuccessResponse(w, "user created", user)
}
注：writeSuccessResponse 封装了 200 响应，保持风格一致
结合 Gin 或 Echo 等框架（可选）
如果使用 Gin，可直接用 c.AbortWithError(code, err) + 自定义 gin.Error 处理；Echo 提供 c.JSON(code, data) 和 c.Error() 钩子。但底层思想不变：把错误语义（什么错、多严重）和传输格式（JSON 结构）解耦，由统一出口控制。
关键不是框架多强大，而是团队约定：所有错误走 AppError，所有响应走 Response 结构，中间件兜底 —— 这样日志、监控、前端联调才真正可控。
