Go HTTP Server 怎样给连接注入元数据

Go HTTP Server 可以在 ConnContext 中把连接元数据放进派生上下文，再由 handler 从 r.Context() 读取。使用私有键类型、只读小型快照，并且从回调传入的 ctx 派生，是最小可用方案。

ConnContext 把连接数据带入请求

ConnContext 是已有的标准库连接扩展点，不是近期发布新闻，也不是逐请求回调。它把一次连接接入产生的信息交给该连接后续请求。官方 Server 文档说明，传入 ctx 已从基础上下文派生并含 ServerContextKey，所以应调用 context.WithValue(ctx, key, value)，不要换成 context.Background() 丢掉上游信息；返回值不能为 nil。

哪些字段属于连接

假设日志需要把不同请求归到同一连接，可保存连接编号 ID、对端地址 Peer、本地地址 Local 和回调取样时间 AcceptedAt。地址保存字符串快照，处理器无需持有 net.Conn。这里的时间不是内核接入的精确时刻，编号仅在当前进程中递增，重启后重新开始。

不要把某次请求的追踪号、请求头或认证主体当作连接固有信息。长连接可以承担多个请求；同一连接不能证明同一业务用户。若只需要当前请求对端地址，Request.RemoteAddr 已提供相关信息，不必重复建立模型。

用私有键注入和读取

下面是完整 main.go，原子递增生成连接编号，结构体值注入，读取时检查类型断言。示例用于说明写法和预期行为，未作为本机实测记录。

package main

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

// 私有键类型避免跨包键冲突。
type connectionKey struct{}

// 保存值快照，不存可变容器或原始连接。
type connectionInfo struct {
    ID uint64
    Peer string
    Local string
    AcceptedAt time.Time
}

func main() {
    var sequence uint64
    srv := &http.Server{
        Addr: "127.0.0.1:8080",
        ReadHeaderTimeout: 5 * time.Second,
        ConnContext: func(ctx context.Context, c net.Conn) context.Context {
            // 从传入上下文派生，保留上游信息。
            info := connectionInfo{
                ID: atomic.AddUint64(&sequence, 1),
                Peer: c.RemoteAddr().String(),
                Local: c.LocalAddr().String(),
                AcceptedAt: time.Now(),
            }
            return context.WithValue(ctx, connectionKey{}, info)
        },
        Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // 独立调用处理器时可能没有注入，必须检查断言。
            info, ok := r.Context().Value(connectionKey{}).(connectionInfo)
            if !ok {
                http.Error(w, "缺少连接元数据", http.StatusInternalServerError)
                return
            }
            // 内部地址只进入服务端日志，不回传访问者。
            log.Printf("连接=%d 对端=%s 本地=%s 接入时间=%s",
                info.ID, info.Peer, info.Local,
                info.AcceptedAt.Format(time.RFC3339Nano))
            w.Header().Set("Content-Type", "text/plain; charset=utf-8")
            fmt.Fprintf(w, "连接编号=%d\n", info.ID)
        }),
    }
    // 回环地址演示，非完整生产服务配置。
    log.Fatal(srv.ListenAndServe())
}

在同一连接确实被复用的前提下，后续请求读到相同编号；新连接得到新编号。连续发送两个请求不保证连接复用，不能仅凭编号不同认定注入失败。私有键与访问函数应在同一个包管理；跨包调用可提供安全读取函数，不应在调用方另造同名类型。

与请求中间件怎么选

中间件添加值时继续从 r.Context() 派生。用无关上下文替换它，也可能造成连接元数据读取失败。这里解决的是连接与请求之间的数据传递，不是连接注册表或清理策略。

共享数据的采用边界

Serve 的接受循环调用 ConnContext 后才启动该连接的服务处理，因此回调应只做轻量快照，不做慢速数据库查询、远程调用，也不要主动读连接数据。WithValue 不是资源清理机制。

示例保存结构体值并不修改。若改用指针、map 或 slice，上下文复制不会深复制对象；多个处理器可能共享它，尤其 HTTP/2 多请求并发时不能无锁修改。优先保存不变数据，请求状态放在请求层。

Peer 是直接对端，前置代理下可能是代理地址，而非经过认证的真实客户端身份。不要用地址快照跳过认证，也不要公开内部地址。该方案适合日志关联和连接标签，不是授权依据。

为什么 handler 读取不到连接元数据？

看请求是否经过配置了该回调的 Server，键类型和值类型是否一致，中间件是否替换上下文。单独调用 handler 的测试不会自动触发连接回调，需要显式构造带值请求。

连接编号能代替请求追踪号吗？

不能。多个请求可共享连接编号，逐请求追踪号应另在请求中间件生成。

ConnContext 会为每个请求调用一次吗？

不会按请求重复调用。依赖 URL、请求头或认证状态的逻辑，应放在请求级代码。

官方文档：https://pkg.go.dev/net/http#Server；实现：https://go.dev/src/net/http/server.go。在连接入口保存只读快照，从原 ctx 派生，handler 安全读取，业务身份留在请求层，便能保持清楚的数据边界。