Go net/http Server ConnContext 如何把连接级信息传给请求：建立时机与生命周期

给每个 HTTP 请求附加租户、接入点或连接追踪信息时，很多人会把 Server.ConnContext 当成“每次请求都会执行的钩子”。实际情况是：它只在新连接建立时调用一次；同一条 keep-alive 连接后续承载的请求，会继续沿用这个连接上下文。

把连接级数据放进 ConnContext，把请求级数据放进 Handler 或中间件；需要请求结束清理的资源，不要因为连接还活着就一直挂在上下文里。

先看一个容易误判的现场：请求数增加，ConnContext 却没有同步增加

假设服务开启 keep-alive，客户端连续发送三次请求。日志里可能有三个 Handler 入口，但 ConnContext 只打印一次。这个现象不是丢回调，而是它的边界本来就位于“连接创建”而不是“请求到达”。

官方 net/http 文档把它描述为修改新连接所使用上下文的函数；源码中连接被接受后才会调用它，再把得到的上下文交给连接服务流程。理解这个顺序，后面设计连接追踪字段才不会误把请求 ID 做成连接 ID。

把连接级值放在正确的入口

下面的示例给每条连接生成一个稳定的 connID，Handler 再从 r.Context() 读取它。这里没有把请求计数器或请求 ID 放进连接上下文，因为它们的生命周期不同。

package main

import (
    "context"
    "fmt"
    "log"
    "net"
    "net/http"
    "sync/atomic"
)

type connIDKey struct{}

var nextConnID atomic.Uint64

func main() {
    srv := &http.Server{
        BaseContext: func(net.Listener) context.Context {
            return context.Background()
        },
        ConnContext: func(ctx context.Context, c net.Conn) context.Context {
            id := nextConnID.Add(1)
            log.Printf("new connection id=%d remote=%s", id, c.RemoteAddr())
            return context.WithValue(ctx, connIDKey{}, id)
        },
        Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            id, _ := r.Context().Value(connIDKey{}).(uint64)
            fmt.Fprintf(w, "connection=%d\\n", id)
        }),
    }

    log.Fatal(srv.ListenAndServe())
}

调用链是 BaseContext → Server.ConnContext → conn.serve → Handler。如果同一个客户端连接连续请求，响应里的 connection 值会保持不变；新建 TCP 连接后才会递增。

生产代码还应把服务关闭、错误处理和测试补齐。示例的重点不是用上下文替代日志系统，而是让连接边界有一个可验证的承载位置。

连接复用与请求取消是两条不同的时间线

Request.Context 会在 Handler 返回、客户端连接关闭，或 HTTP/2 请求被取消等情况下结束；这不等于 ConnContext 中放入的值会在每个请求结束时被重新创建。连接还活着时，下一次请求仍可能看到同一个连接级值。

因此，数据库事务、请求体解析结果、单次请求的超时和请求 ID，不应塞进 ConnContext。它们应当在 Handler 或中间件中通过 context.WithTimeout、请求属性或局部变量建立，并随请求结束释放。

HTTP/2 下不要把连接标识误当成请求标识

HTTP/2 允许同一条连接并发承载多个请求。ConnContext 仍然适合放连接所属的入口、证书摘要或网络对端信息，但每个请求的 trace ID、权限判断和超时必须在请求层创建。否则并发请求会共享本来应该独立的数据。

一个实用的判断方法是问自己：“如果同一条连接同时有两个 Handler，这个值是否必须相同？”必须相同的才考虑连接上下文；必须不同的交给请求上下文或局部变量。这个问题比记住某个回调名字更可靠。

上线前用日志验证三个边界

不要只验证 Handler 能读到值。压测或集成测试至少记录 ConnContext 调用次数、connection 值和请求结束日志，分别观察 keep-alive 复用、新连接建立、客户端中途断开三种情况。

• 同一连接多次请求：ConnContext 次数不随请求数增长，连接 ID 保持一致。
• 主动关闭并重新拨号：出现新的连接 ID，Handler 能读到新值。
• 请求超时或客户端断开：请求级工作收到 r.Context().Done()，不会把清理责任推迟到连接关闭。

相关问题

ConnContext 会为每个 HTTP 请求执行吗？

不会。它针对新连接执行；同一连接上的请求会继承连接上下文。

请求 ID 能不能放进 ConnContext？

不建议。HTTP/1 keep-alive 和 HTTP/2 多路复用都会让一个连接对应多个请求，请求 ID 应在请求层生成。

BaseContext 和 ConnContext 怎么分工？

BaseContext 给监听器提供基础上下文，ConnContext 再按新连接附加连接级信息；两者都不替代请求级超时和取消。

小结

Server.ConnContext 的价值在于明确连接边界，而不是提供一个更早执行的请求中间件。把 BaseContext、ConnContext、conn.serve 和 Handler 的顺序画清楚，再分别验证连接复用、请求取消和 HTTP/2 并发，连接级元数据就不会意外变成跨请求状态。