Gin框架Panic处理与Recovery中间件开发

Gin框架默认的Recovery中间件仅简单打印panic到stderr，缺乏请求上下文记录、结构化错误响应、自定义错误码和告警能力，导致线上panic难以定位——你看到的可能只是“nil pointer dereference”，却不知道是哪个请求、什么参数、哪步逻辑触发的；本文手把手教你打造一个高可用的CustomRecovery中间件：捕获panic后自动提取path、method、request_id等关键信息，集成zap/logrus结构化日志，返回含"code": "PANIC"的JSON响应便于前端区分，支持panic后资源清理，并强调必须将其置于中间件链最外层注册才能真正兜住所有异常，同时避开了c.Writer重复写头、context状态混乱等高频踩坑点，让每一次panic都成为可追溯、可告警、可快速止损的明确事件。

为什么 Gin 默认的 Recovery 中间件不够用

默认 Recovery 只打印 panic 到标准错误，不记录日志上下文、不返回结构化错误响应、也不支持自定义错误码或告警。线上服务出 panic 时，你根本不知道是哪个请求、哪个参数、哪个中间件触发的。

常见错误现象：panic: runtime error: invalid memory address or nil pointer dereference 出现在日志里，但没带 request_id、没带 path、没带 method，查问题全靠猜。

• 它不调用你自己的日志库（比如 zap 或 logrus），无法统一日志格式
• 它返回的 HTTP 响应体是固定字符串 "Internal Server Error"，前端无法区分是 panic 还是业务错误
• 它不支持在 panic 后执行清理逻辑（比如关闭数据库事务、释放临时资源）

怎么写一个带上下文记录的 Recovery 替代中间件

核心思路：捕获 panic → 提取 *gin.Context 里的关键字段 → 记录结构化日志 → 返回 JSON 错误响应 → 可选地调用 cleanup 回调。

实操建议：

• 用 recover() 捕获 panic，立刻检查是否为 nil，避免空 recover 导致 panic 继续上抛
• 从 c.Request.URL.Path、c.Request.Method、c.GetString("request_id")（如果已注入）提取上下文
• 把 panic value 转成字符串时，用 fmt.Sprintf("%v", err)，别用 err.Error() —— 否则遇到 nil panic 会 panic
• 响应状态码建议统一用 500，但响应体必须含 code 字段（如 "PANIC"）方便前端识别类型

简短示例：

func CustomRecovery(logger *zap.Logger) gin.HandlerFunc {
	return func(c *gin.Context) {
		defer func() {
			if err := recover(); err != nil {
				path := c.Request.URL.Path
				method := c.Request.Method
				reqID := c.GetString("request_id")
				logger.Error("panic recovered",
					zap.String("path", path),
					zap.String("method", method),
					zap.String("request_id", reqID),
					zap.Any("panic", err),
					zap.String("stack", string(debug.Stack())),
				)
				c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{
					"code": "PANIC",
					"msg":  "Internal server error",
				})
			}
		}()
		c.Next()
	}
}

CustomRecovery 必须放在中间件链最外层吗

必须。Gin 中间件执行顺序是栈式入栈、出栈，Recovery 类中间件必须包裹所有可能 panic 的逻辑，否则 panic 会直接逃逸到 HTTP server 层，绕过你的处理。

容易踩的坑：

• 把它加在 Logger() 之后但 Auth() 之前 → 如果 Auth panic，Logger 已经写了 access log，但 recovery 日志没带 auth 失败细节
• 多个 Recovery 嵌套（比如在某个路由组里又加了一次）→ 只有最外层生效，内层不会触发
• 用 c.Next() 之前就 panic（比如中间件初始化失败）→ 这类 panic 不会被任何 Recovery 捕获，得靠启动时的 defer recover()

正确位置：在 engine.Use() 中第一个注册，例如：r.Use(CustomRecovery(zap.L()))，再接 Logger、Auth 等。

要不要在 CustomRecovery 里重置 gin.Context 状态

不用主动重置，但要注意：panic 发生时，c.Writer 可能已写入部分响应（比如某些中间件提前写了 header），此时 c.AbortWithStatusJSON 会失败并触发 http: multiple response.WriteHeader calls 错误。

解决方案很直接：

• 在 defer 里第一行就调用 c.Abort()，确保后续中间件不再执行
• 不要依赖 c.Writer.Status() 判断是否已写，而是用 c.IsAborted() 或直接信任 AbortWithStatusJSON 的行为
• 如果用了自定义 ResponseWriter（比如带 body 缓存的），panic 时它的内部缓冲可能处于不一致状态，这类 writer 需要额外 Reset() 方法，但 Gin 原生不提供，得自己封装

真正关键的是：panic 是异常路径，响应内容以「可读、可定位、不污染」为优先，别试图在 recovery 里做优雅降级或 fallback 渲染。

到这里，我们也就讲完了《Gin框架Panic处理与Recovery中间件开发》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！