Gin默认Recovery中间件仅捕获panic并打印日志，不返回JSON响应；需自定义中间件调用c.AbortWithStatusJSON()返回结构化错误，并统一处理业务错误与panic。
默认的 gin.Recovery() 中间件只 recover panic 并打印日志，**不会返回 JSON 响应**，也不会修改响应体格式。你看到的 500 页面是浏览器原生 HTML，前端无法解析——这不是 bug，是 Gin 的设计：捕获和渲染解耦，留给你自定义空间。
为什么默认 Recovery 不返回 JSON
Gin 的 gin.Recovery() 是个“裸 recovery”，它只做三件事：defer 捕获 panic、调用 log.Printf 打印堆栈、调用 c.Abort() 终止流程。它压根不碰 c.JSON() 或 c.AbortWithStatusJSON()，所以响应体仍是空的，最终走 Gin 底层 fallback，返回纯文本或 HTML（取决于 Accept 头）。
- 别在
r.Use(gin.Recovery())后就以为错误能被前端消费——那只是日志有了，响应还是裸的 - 生产环境必须禁用默认 Recovery，否则会泄露 panic 详情（如文件路径、变量名）
- HTTP 状态码（如
http.StatusInternalServerError）和业务错误码（如5000）要分开：前者控制客户端重试/跳转行为，后者供前端 UI 分支处理
怎么写一个真正返回 JSON 的 Recovery 中间件
核心就两步：recover 后构造结构化错误，再用 c.AbortWithStatusJSON() 写响应并终止流程。注意必须 return，否则后续 c.Next() 可能二次写 header 导致 panic。
- 不要用
http.Error()或手动w.WriteHeader()——c.AbortWithStatusJSON()已自动设置Content-Type: application/json - 错误结构建议含
code（int）、message（string）、timestamp（time.Now().UnixMilli()），避免嵌套过深或暴露敏感字段 - panic 错误体必须脱敏：禁止透传
db.QueryRow failed: no rows in result set这类原始信息，统一转成"资源不存在"
func CustomRecovery() gin.HandlerFunc {
return func(c *gin.Context) {
defer func() {
if err := recover(); err != nil {
log.Printf("PANIC: %+v", err)
c.AbortWithStatusJSON(http.StatusInternalServerError, map[string]interface{}{
"code": 5000,
"message": "服务器内部错误",
"timestamp": time.Now().UnixMilli(),
})
return // ⚠️ 必须加！
}
}()
c.Next()
}
}
如何让业务错误（非 panic）也走同一套返回格式
Gin 的 c.Error(err) 是个信号机制：它把错误存进 c.Errors 队列，但**不会自动渲染**。你要在中间件末尾主动检查并格式化输出，否则这些错误就静默丢失了。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 在 handler 里别直接
c.JSON(400, ...)，改用c.Error(ErrInvalidParam)（其中ErrInvalidParam是预定义的*AppError） - 全局中间件中加判断：
if len(c.Errors) > 0 { c.AbortWithStatusJSON(...); return } - 用
errors.Is()或类型断言区分错误类型（如*biz.ValidationError），别依赖err.Error()包含关键词来判断 -
c.AbortWithError(statusCode, err)更适合需要立刻终止流程的场景（如参数校验失败），但第二个参数必须是error类型，传字符串会 panic
统一错误结构体该定义成什么样
别用接口或嵌套 struct，用导出字段的 plain struct，确保 JSON 序列化稳定、字段可扩展、前端易解析。
-
code用int，约定 0 表示成功，非 0 表示错误；避免用字符串码（如"invalid_param"），前端 switch 不友好 - 必须包含
StatusCode字段（如http.StatusBadRequest），和业务code分开管理——401/403 要带提示，500 必须脱敏，不能混用同一套 message - 推荐预定义错误变量：
var ErrNotFound = NewAppError(1004, "资源未找到", http.StatusNotFound)，便于类型断言和日志归类 - 所有响应函数末尾必须加
return，防止c.Next()后续逻辑继续执行导致重复写 response
type AppError struct {
Code int `json:"code"`
Message string `json:"message"`
StatusCode int `json:"status_code"`
RequestID string `json:"request_id,omitempty"`
}
func (e *AppError) Error() string {
return fmt.Sprintf("code=%d message=%s", e.Code, e.Message)
}
最难的不是写中间件，而是让所有 handler 都习惯用 c.Error() 而不是裸 return err，也不在业务层直接调 c.JSON()。一旦漏掉一两个地方，统一格式就破了——得靠代码审查和单元测试卡住。
