当前位置：首页 > 文章列表 > Golang > Go教程 > Go HTTP 接口 panic 怎么兜底：recover 中间件与请求 ID 排障清单

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

来源：17golang原创 2026-07-01 15:58:38 0浏览收藏

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

现象：接口返回 500 但找不到是哪次请求
分层检查：先确认 panic 发生在哪一层
证据判断：日志必须带请求 ID 和堆栈
修复动作：实现 RequestID 和 Recover 中间件
反向验证：用 curl 和日志确认链路闭合
上线清单：哪些边界不能漏
总结

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

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

Go HTTP 接口 panic 现场：接口500、panic堆栈、缺少请求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，访问日志也能记录最终状态。

Go HTTP panic recover 中间件修复链路：请求ID、recover捕获、记录堆栈、统一JSON和反向验证

反向验证：用 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"}