Go HTTP 接口 panic 怎么兜底：recover 中间件与请求 ID 排障清单

Go 的 net/http 服务如果某个 handler 里发生 panic，最怕出现两种结果：用户只看到一个粗糙的 500，日志里却缺少请求 ID；或者 panic 没有被统一兜底，排障时只能在一堆堆栈里猜是哪次请求触发。更稳的做法是在入口层加一组中间件：先生成请求 ID，再用 recover 捕获 panic，记录堆栈和上下文字段，最后返回统一 JSON 错误。

现象：接口返回 500 但找不到是哪次请求

先看一个常见现场。订单详情接口偶发 500，用户反馈“页面打开失败”，网关里只能看到 GET /api/order?id=10086 失败。服务日志里虽然有 panic 堆栈，但没有稳定的 request_id、用户 ID、路由名和响应状态，排查人员很难把用户失败、网关记录、服务堆栈连成一条线。

这类问题不能只靠在每个业务 handler 里手写 recover()。一旦有人漏写，接口行为就不一致。中间件更适合放在入口层，把兜底、日志和响应格式统一起来。

分层检查：先确认 panic 发生在哪一层

修复前先分层检查，避免把所有 500 都当成 panic。

• 网关层：看状态码、耗时、上游是否断开，确认请求确实打到 Go 服务。
• 服务入口：看是否打印 request start/request completed 这类访问日志。
• handler 层：看堆栈是否指向业务函数、空指针、数组越界或类型断言。
• 响应层：看客户端收到的是纯文本 500、空响应，还是统一 JSON。

如果日志只有堆栈，没有请求字段，就算找到出错行，也不容易回答“哪类用户、哪个参数、哪个路由触发”。所以修复的第一步不是直接改业务 bug，而是把请求链路补完整。

证据判断：日志必须带请求 ID 和堆栈

一条合格的 panic 日志至少应包含：

• request_id：贯穿网关、服务日志和客户端错误提示。
• route、method、path：定位接口入口。
• status、duration_ms：判断请求结果和耗时。
• panic_value 和堆栈：定位根因代码。
• 必要时补充用户 ID、租户 ID、客户端 IP，但不要写入敏感原文数据。

有了这些字段，排障路径才完整：用户报错给出请求 ID，日志平台按请求 ID 搜索，找到同一条链路里的访问日志、panic 日志和业务上下文。

修复动作：实现 RequestID 和 Recover 中间件

下面用标准库写一个最小版本。先准备 context key 和请求 ID 中间件：

type contextKey string

const requestIDKey contextKey = "request_id"

func RequestID(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        rid := r.Header.Get("X-Request-ID")
        if rid == "" {
            rid = newRequestID()
        }

        w.Header().Set("X-Request-ID", rid)
        ctx := context.WithValue(r.Context(), requestIDKey, rid)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func RequestIDFrom(ctx context.Context) string {
    rid, _ := ctx.Value(requestIDKey).(string)
    return rid
}

newRequestID() 可以用 UUID、雪花 ID 或团队已有链路追踪 ID。示例里不绑定具体库，重点是：请求进入服务时就应该有 ID，响应头也要带回去，方便客户端或网关记录。

再写 recover 中间件。它必须放在业务 handler 外层，一旦 handler panic，就记录堆栈并返回统一错误：

func Recover(logger *slog.Logger, next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if v := recover(); v != nil {
                rid := RequestIDFrom(r.Context())

                logger.Error("http panic recovered",
                    slog.String("request_id", rid),
                    slog.String("method", r.Method),
                    slog.String("path", r.URL.Path),
                    slog.Any("panic_value", v),
                    slog.String("stack", string(debug.Stack())),
                )

                writeJSONError(w, http.StatusInternalServerError, rid)
            }
        }()

        next.ServeHTTP(w, r)
    })
}

统一错误响应可以保持克制，不要把堆栈返回给客户端：

func writeJSONError(w http.ResponseWriter, status int, requestID string) {
    w.Header().Set("Content-Type", "application/json; charset=utf-8")
    w.WriteHeader(status)

    body := map[string]any{
        "code":       status,
        "message":    "服务器内部错误",
        "request_id": requestID,
    }
    _ = json.NewEncoder(w).Encode(body)
}

最后把中间件按顺序串起来：

func Chain(h http.Handler, logger *slog.Logger) http.Handler {
    h = AccessLog(logger, h)
    h = Recover(logger, h)
    h = RequestID(h)
    return h
}

这里的顺序要按你的包装函数理解：外层先进入 RequestID，再进入 Recover，最后到访问日志和业务 handler。关键原则是：recover 里拿得到请求 ID，访问日志也能记录最终状态。

反向验证：用 curl 和日志确认链路闭合

修复后不要只看“服务没崩”。建议做三类反向验证。

1. 客户端能拿到 request_id

curl -i http://localhost:8080/api/order?id=10086

预期响应类似：

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
X-Request-ID: req-8f21

{"code":500,"message":"服务器内部错误","request_id":"req-8f21"}

2. 服务日志能按请求 ID 搜到堆栈

日志里应该能看到 request_id=req-8f21、path=/api/order、panic_value 和堆栈。这样客服、前端、网关和后端可以围绕同一个 ID 沟通。

3. 正常请求不受影响

再跑一次正常路径，确认中间件没有破坏响应头、状态码和业务响应体。panic 兜底中间件只处理异常分支，不能让正常接口变慢或改变响应格式。

上线清单：哪些边界不能漏

• 不要吞掉所有错误：panic 兜底是最后防线，不应该替代业务错误处理。
• 不要返回堆栈给客户端：堆栈只进日志，客户端只拿请求 ID 和通用提示。
• 注意响应已写出：如果 handler 已经写了一部分响应后才 panic，就不能再可靠地改状态码。关键接口应避免边写边做高风险逻辑。
• 记录字段要统一：请求 ID、路由、状态码、耗时字段名要和团队日志规范一致。
• 告警要去重：同一 panic 短时间大量出现时，告警系统要按路由、堆栈摘要和版本聚合。
• 补单测或集成测试：构造一个必然 panic 的 handler，验证响应和日志字段是否完整。

总结

Go HTTP 接口发生 panic 时，目标不是把错误藏起来，而是让服务有兜底、客户端有清晰提示、日志能快速定位。推荐的入口链路是：先生成请求 ID，再用 recover 中间件捕获 panic，记录堆栈和上下文字段，最后返回统一 JSON 错误。

这套做法适合绝大多数标准库、chi、gin 或自研路由封装。具体框架写法会不同，但检查清单不变：请求 ID 是否贯穿全链路，panic 是否进入结构化日志，客户端是否拿到可反馈的 ID，反向验证是否能从 ID 找回完整堆栈。