Go http.Server.ConnContext 怎么为每条连接附加自定义元数据

我第一次给 Go HTTP 服务加连接追踪时，直觉是把标识写进每个请求的 handler。这样当然能工作，但连接建立、请求进入和业务处理之间的边界很快变得模糊：同一条 keep-alive 连接上的多个请求会重复生成标识，HTTP/2 的并发请求也无法共享真正的连接级信息。

http.Server.ConnContext 适合解决这个问题。它在新连接建立时接收基础上下文和 net.Conn，返回一个连接级上下文；后续请求可以从 r.Context() 继承其中的只读元数据。

要给每条 HTTP 连接附加自定义元数据，就在 Server.ConnContext 中基于传入上下文返回 context.WithValue；只把连接生命周期内稳定、只读的值放进去，请求自己的参数仍然放在 handler 或请求级 context 中。

官方文档：https://pkg.go.dev/net/http#Server.ConnContext

先把三个上下文层级分开

官方定义里，BaseContext 为监听器提供基础上下文，ConnContext 修改新连接使用的上下文，而 handler 收到的 *http.Request 又会带着请求处理所需的上下文。它们的生命周期并不相同，混用时最容易出现“本来只想记录连接信息，却把每次请求的数据也粘在连接上”的问题。

我在实际改造中先画出这三层，再决定数据放在哪里。只要值会随着每个请求变化，就不要因为“读取方便”而上移到 ConnContext。

在 ConnContext 中生成连接级元数据

下面的例子为每条连接生成一个追踪标识，并把它放进上下文。自定义 key 使用私有类型，避免和其他包的字符串 key 冲突；回调必须返回非 nil context，否则服务处理连接时就失去上下文保证。

package main

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

// connTraceKey 使用私有类型，避免不同包之间的 context key 冲突。
type connTraceKey struct{}

var nextConnID atomic.Uint64

func main() {
    server := &http.Server{
        Addr: ":8080",
        ConnContext: func(ctx context.Context, c net.Conn) context.Context {
            // 连接建立时只生成一次 ID，同一连接的请求可以继承它。
            id := nextConnID.Add(1)
            traceID := fmt.Sprintf("conn-%d", id)

            // 保留 Server 提供的基础 context，只在其上附加只读值。
            return context.WithValue(ctx, connTraceKey{}, traceID)
        },
    }

    // 监听器关闭或服务退出时，把错误交给进程级日志处理。
    log.Fatal(server.ListenAndServe())
}

这里的 net.Conn 参数可以继续用于读取连接地址、协议包装类型等连接信息，但不要把连接对象本身塞进 context 供业务长期保存。上下文更适合传递请求路径上需要的轻量只读值，连接资源仍由服务器生命周期负责管理。

在 handler 中读取并使用连接元数据

连接上下文的价值要到 handler 才体现出来。读取时使用私有 key 的类型断言，并给缺失值安排明确的降级行为。这样即使某个测试请求没有经过真实服务器，也不会因为强制断言而 panic。

func traceHandler(w http.ResponseWriter, r *http.Request) {
    // 只读取连接级只读标识，不修改上下文中的值。
    traceID, ok := r.Context().Value(connTraceKey{}).(string)
    if !ok || traceID == "" {
        // 缺少元数据时返回可识别的错误，避免静默写入错误日志。
        http.Error(w, "connection trace is missing", http.StatusInternalServerError)
        return
    }

    // 业务日志、指标标签或响应头都可以复用同一个连接标识。
    log.Printf("trace=%s method=%s path=%s", traceID, r.Method, r.URL.Path)
    w.Header().Set("X-Connection-Trace", traceID)
    w.WriteHeader(http.StatusOK)
}

func newHandler() http.Handler {
    // 路由只负责连接上下文已经存在时的读取，不负责生成连接 ID。
    mux := http.NewServeMux()
    mux.HandleFunc("/health", traceHandler)
    return mux
}

测试 handler 时，可以手工构造一个带同样 key 的请求 context；测试的是读取和缺失分支，而不是伪造一次真实的 TCP 连接。上线代码则由 Server.ConnContext 负责在连接入口统一注入。

ConnContext 和请求级 WithContext 怎样配合

连接级标识和请求级标识可以同时存在。常见做法是让 ConnContext 提供连接追踪 ID，在 handler 或中间件中再为当前请求添加请求 ID。请求级值应该覆盖“当前这一次请求”，而不是回写连接级上下文。

type requestIDKey struct{}

func requestTrace(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 请求 ID 每次请求独立生成，不能放进 ConnContext 复用。
        requestID := newRequestID()
        ctx := context.WithValue(r.Context(), requestIDKey{}, requestID)

        // WithContext 返回带新 context 的请求，不修改原请求对象的 context。
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func newRequestID() string {
    // 示例只强调生命周期；生产环境应使用项目统一的 ID 生成器。
    return fmt.Sprintf("req-%d", nextConnID.Add(1))
}

此时日志可以同时打印连接 ID 和请求 ID：连接 ID 用于观察连接复用，请求 ID 用于定位单次业务调用。若把请求 ID 在 ConnContext 里生成，同一条 keep-alive 连接的后续请求就会错误地共享它。

HTTP/2 并发下要特别小心可变数据

HTTP/1.1 的 keep-alive 已经会让一条连接承载多个请求，HTTP/2 则可能让多个请求流并发出现在同一条连接上。因此连接上下文中的值必须是不可变或并发安全的只读数据。不要把当前用户、当前请求体、可复用的临时缓冲区或单次事务对象放进去。

• 适合：连接编号、连接建立时计算出的协议标签、只读采样标记。
• 需要谨慎：指向共享对象的指针；除非对象本身有明确的并发保护。
• 不适合：当前请求的用户 ID、请求参数、响应状态、请求级缓存和事务。

如果数据需要在请求结束时清理，应把它放在请求级中间件的 defer 中；如果数据跟连接关闭有关，优先考虑 Server.ConnState 或专门的连接管理结构，而不是期待 context 自动调用清理函数。

几个实际使用中的取舍

为什么不直接在 handler 里读取 RemoteAddr？可以读取，但每个业务 handler 都重复做会让日志格式不一致。ConnContext 适合在统一入口把连接级标签准备好，handler 只消费它。

为什么不用字符串作为 key？公共字符串容易和其他包碰撞。私有空结构体类型占用小，而且能让 key 的读写范围留在本包内。

ConnContext 能替代中间件吗？不能。它解决的是连接建立时的上下文初始化；鉴权、请求参数校验、请求 ID、响应包装等仍然属于请求级中间件。

连接关闭后 context 会自动帮我关闭资源吗？不要这样设计。context 表达取消和截止时间，不是通用资源析构器。需要清理连接关联资源时，显式监听连接状态或在请求生命周期中释放。

我最后保留的落地清单

1. 先判断数据属于服务、连接还是请求，再选择 BaseContext、ConnContext 或请求级 context。
2. 在 ConnContext 中保留传入的基础 context，只附加轻量、只读、连接生命周期内稳定的数据。
3. 使用私有 key 类型，并为读取失败准备明确的降级或错误响应。
4. 为 keep-alive 和 HTTP/2 的连接复用、并发请求分别考虑生命周期，不要共享可变请求状态。
5. 连接级资源清理交给连接状态回调或显式管理，请求级资源清理放进请求中间件的 defer。

ConnContext 的 API 很小，但它把“连接刚建立”这个时刻变成了可扩展的上下文入口。只要把连接级和请求级数据分开，日志、追踪和协议标签就能统一注入，同时不会让业务 handler 承担重复的连接识别逻辑。

相关问题

ConnContext 和 BaseContext 的主要区别是什么？BaseContext 面向监听器和服务级基础上下文，ConnContext 面向每条新连接；前者通常是更上层的共同起点，后者可以根据具体连接附加元数据。

同一连接上的请求一定共享 ConnContext 中的值吗？连接级上下文作为请求上下文的起点会被后续请求继承，但请求仍可通过 WithContext 创建自己的派生 context。不要利用共享值承载请求可变状态。

测试 ConnContext 一定要启动真实服务器吗？若要验证连接建立和复用行为，应该使用测试服务器或自定义 listener；若只测试 handler 对上下文值的读取，可以直接构造带值的 context，避免把单元测试扩大成传输测试。