Go 怎样把连接级信息传给请求处理器

在 Go 的 HTTP 服务里，如果一条连接建立后会承载多次请求，可以用 http.Server.ConnContext 把连接级信息放进基础上下文，再由处理器通过 r.Context() 读取。最适合放进去的是连接标识、接入分组或已经确定且会随连接保持不变的元数据；请求参数、鉴权结果和请求级超时仍然应该在请求上下文中单独处理。

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

关键关系只有一条：ConnContext 修改的是“新连接的上下文”，Request.Context() 返回的是“当前请求的上下文”。标准库会把前者作为后者的基础，因此 handler 能读到连接级值，但不能把两者当成同一个生命周期。

先看清 ConnContext 到 Request.Context 的传递关系

ConnContext 是 Server 的回调字段。服务器接受到一条新连接时调用它，并使用返回的上下文作为这条连接的基础。之后这条连接上的请求会获得自己的请求上下文，handler 里通过 Request.Context() 访问。

这意味着回调不是“每个请求执行一次”的中间件。如果客户端复用连接发送多个请求，连接级值可以被多个请求看到；但每个请求仍然拥有自己的取消边界。

最小配方：在 ConnContext 中注入连接标识

下面的例子只放入一个连接标识。自定义 key 类型可以避免不同包之间发生字符串 key 冲突，读取时也用一个小函数集中处理类型断言。

package main

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

type connIDKey struct{}

var nextConnID atomic.Uint64

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/profile", func(w http.ResponseWriter, r *http.Request) {
        // handler 读取的是当前请求上下文，但值来自新连接时的 ConnContext。
        id, _ := r.Context().Value(connIDKey{}).(uint64)
        fmt.Fprintf(w, "connection=%d\\n", id)
    })

    server := &http.Server{
        Addr:    ":8080",
        Handler: mux,
        ConnContext: func(ctx context.Context, c net.Conn) context.Context {
            // 每接受一条新连接只分配一次 ID；不要在这里保存请求参数。
            id := nextConnID.Add(1)
            return context.WithValue(ctx, connIDKey{}, id)
        },
    }

    // ListenAndServe 返回的错误通常需要记录，避免服务异常退出时没有线索。
    log.Fatal(server.ListenAndServe())
}

这里的关键不是把值写入 context，而是选对写入位置：连接 ID 在接受连接时就确定，不需要等到某个 URL 或请求体出现。若希望传递的是请求级 trace ID、用户身份或一次请求的限流信息，应在 handler 或专用中间件里基于当前请求创建派生上下文。

在业务函数中读取时保持参数边界

context 的值适合传递会穿过 API 边界的请求范围信息，不适合替代普通函数参数。业务函数可以把上下文作为第一个参数，把真正决定业务行为的数据显式列出来。

type service struct{}

func (s *service) handleProfile(w http.ResponseWriter, r *http.Request) {
    // 读取失败时使用明确的降级分支，避免把缺失值格式化成误导性的零值。
    connID, ok := r.Context().Value(connIDKey{}).(uint64)
    if !ok {
        http.Error(w, "missing connection context", http.StatusInternalServerError)
        return
    }

    // 业务参数仍然显式传入，context 只承载跨层的请求范围元数据。
    if err := s.loadProfile(r.Context(), connID, r.URL.Query().Get("id")); err != nil {
        http.Error(w, "load profile failed", http.StatusInternalServerError)
        return
    }
    w.WriteHeader(http.StatusNoContent)
}

func (s *service) loadProfile(ctx context.Context, connID uint64, profileID string) error {
    // 下游 I/O 应该继续使用 ctx，以便客户端断开时尽快停止等待。
    _ = ctx
    _ = connID
    _ = profileID
    return nil
}

这种写法同时保留了两种信息：connID 是连接级元数据，profileID 是业务输入。不要为了少写一个参数，把数据库主键、分页大小或开关配置统统塞进 context。

连接复用时，哪些值可以共享

HTTP/1.1 keep-alive 或 HTTP/2 都可能让同一连接承载多个请求。连接级信息可以共享，但它必须满足“对这条连接稳定”的条件，例如连接编号、接入节点标记或已完成握手后得到的协议属性。

不能共享的典型内容包括当前请求的 URL、请求头里的用户身份、一次请求的 trace ID 和请求体解析结果。把这些值放进 ConnContext 会让后续请求继承前一个请求的信息，排查起来尤其困难。

请求取消和清理要跟着 Request.Context

服务端请求的上下文会在客户端连接关闭、HTTP/2 请求被取消，或 ServeHTTP 返回时结束。下游查询、远程调用和后台等待应把这个上下文继续传下去，并监听 ctx.Done()。

func waitForBackend(ctx context.Context) error {
    select {
    case 

不要把 r.Context() 保存到长生命周期对象、全局变量或连接池中。请求结束后它就不再代表新的请求；如果需要在请求之后继续做与请求无关的工作，应明确选择新的生命周期和取消策略，而不是偷偷复用原上下文。

一张表记住选择位置

常见问题

ConnContext 会为每个请求执行吗？

不会。它针对新连接调用；请求处理器每次拿到的是该请求自己的 Request.Context()。

同一条连接上的请求会拿到同一个 context 吗？

不能把它们当作同一个对象或同一个生命周期。它们可以继承连接级值，但请求取消和结束时间分别由各个请求决定。

为什么不用字符串作为 context key？

字符串容易与其他包撞名。定义一个未导出的 key 类型，或者在包内提供类型安全的 getter，更容易控制读写边界。