middleware.recover() 不捕获所有 panic,因其仅作用于 http handler 同一 goroutine 内的 panic,无法覆盖启动阶段、子 goroutine、server 生命周期外(如定时任务)等场景。

为什么 middleware.Recover() 不捕获所有 panic
默认启用的 middleware.Recover() 只捕获进入 HTTP handler 后、在同一个 goroutine 中发生的 panic。它不处理以下三类情况:
— 启动阶段(如 echo.New() 后立即 panic)
— 中间件或 handler 内部显式启动的新 goroutine(比如 go func() { ... }())中的 panic
— http.Server 生命周期外的 panic(如定时任务、后台协程、信号处理函数)
这些 panic 会直接终止 goroutine,且无响应、无日志(除非你配了 server.ErrorLog)。
如何让 recover 记录完整堆栈并返回结构化错误
默认 middleware.Recover() 只打一行日志,且返回的是 HTML 错误页,不适合 API 场景。你需要自定义 recovery 行为:
— 用 echo.HTTPErrorHandler 替换默认错误处理器,但注意:它只处理 Echo 自身错误(如 c.JSON() 序列化失败),不接管 panic
— 真正生效的方式是重写 middleware.Recover() 的内部逻辑,或直接手写 defer + recover 中间件
— 关键点:必须调用 debug.Stack() 获取完整堆栈,不能只打印 r.Error()
— 推荐返回 c.AbortWithStatusJSON(500, map[string]string{"code": "INTERNAL_ERROR", "msg": "internal server error"}),避免暴露敏感信息
嵌套路由或中间件链中 recover 失效的常见原因
recover 必须在 panic 发生的**同一 goroutine** 且**紧邻 defer 函数内**调用,否则返回 nil。常见失效场景:
— 在自定义中间件里写了 defer func(){ recover() }(),但该中间件被注册为路由组中间件,而 panic 发生在子路由 handler 中 → 实际上仍属于同一 goroutine,通常有效;但如果中间件用了 next(c) 之后又执行了其他代码,panic 发生在 next(c) 返回后,则 recover 已执行完毕,无效
— 使用了异步日志(如 zap 的 logger.WithOptions(zap.AddCallerSkip(1)).Error())但未等 flush 就返回,导致 panic 日志丢失
— Echo v4 中移除了 c.Set()/c.Get(),若旧代码在 recover 前依赖 c.Get("trace_id"),会 panic 并无法被捕获(形成“recover 套 recover”失败)
— 路由参数解析失败(如 c.Param("id") 返回空字符串后,业务代码直接做 strconv.Atoi(""))→ 这类 panic 是可预防的,应前置校验,而非依赖 recover
Echo框架 5.1.0 版本源码包下载,适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
热更新或 Prometheus 注册时 panic 的特殊处理
某些 panic 根本不该被 recover 捕获,强行兜底反而掩盖问题:
— prometheus.MustRegister() 重复注册触发的 panic,说明指标初始化逻辑有缺陷(比如配置重载时反复调用),应改为用 prometheus.Register() 并检查返回 error
— embed.FS 相关 panic(如 Go 版本低于 1.16 却用了 v4)发生在 main() 函数,不在 HTTP 请求 goroutine 内,middleware.Recover() 完全无效,必须靠构建时检查和 go version 验证
— 自定义中间件中调用 c.Request().Context().Value() 传入字符串字面量(如 "user"),在 Echo v4 下会因 context.Value 类型安全机制 panic,这不是运行时 bug,而是迁移遗漏,应改用自定义 key 类型(type userKey string)
recover 的真正作用不是“让服务不死”,而是给不可预期的崩溃留一条日志出口和响应通道。最危险的情况,是把它当成业务错误的替代品——比如用 panic("invalid id") 代替 return errors.New("invalid id"),这会让 recover 日志泛滥,同时失去错误分类和重试能力。










