Go HTTP Server 怎样为连接设置 BaseContext

如果一个 Go HTTP 服务需要让所有新连接共享同一个服务级取消信号、发布代次或只读配置，可以给 http.Server.BaseContext 赋值。它接收即将开始接收请求的 net.Listener，返回新连接和请求继续派生所使用的根上下文；如果不设置，net/http 使用 context.Background()。关键边界是：BaseContext 负责服务范围，不负责承载每个请求的用户参数或连接独有数据。

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

最稳妥的做法是先创建可取消的服务根上下文，在 BaseContext 中返回它；服务关闭时调用取消函数。连接级信息交给 ConnContext，请求级信息继续使用 r.Context()。

先分清 BaseContext 管的是哪一层

BaseContext 的位置在 http.Server 上，因此它描述的是这个服务实例的共同上游。官方定义中，回调会收到即将开始接收请求的具体监听器；如果字段为 nil，默认根是 context.Background()，非空回调则必须返回非空上下文。

这意味着它适合放置“整个服务都要看到”的取消关系，例如发布切换、服务停止或统一的只读依赖。它不适合放置用户 ID、请求参数、鉴权结果等值，因为这些值要等到连接或请求出现后才知道，而且放在公共根上容易形成跨请求共享的错误状态。

先创建可取消的服务根上下文

服务级上下文通常由 context.WithCancel 或 context.WithCancelCause 创建。创建点要在启动服务器之前，这样 BaseContext 只负责返回已经存在的根，不在每次回调中重复创建一棵彼此无关的上下文树。

package main

import (
	"context"
	"fmt"
	"log"
	"net"
	"net/http"
	"os"
	"os/signal"
	"syscall"
)

func newServer() (*http.Server, context.CancelFunc) {
	// 一个 Server 实例只创建一棵服务级上下文树，供新连接继续派生。
	serviceCtx, cancel := context.WithCancel(context.Background())

	mux := http.NewServeMux()
	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
		// 请求上下文仍然来自 r.Context()，不要从全局变量读取请求状态。
		select {
		case 

上面的示例把服务根和 HTTP Server 绑定在一起。BaseContext 的参数类型是 net.Listener，因此示例显式导入了 net。这里特意把服务级取消函数返回给启动方，关闭路径可以显式调用，而不是把取消动作藏在回调里。

把 BaseContext 接到 Server 时要保证回调稳定

真正接入已有服务时，最小配置只需要给 BaseContext 一个函数。回调可能由 Server 在开始接收连接时调用，因此不要在里面做耗时初始化、读取易变的请求数据或返回临时的 nil。若服务有多条监听器，回调参数可以帮助记录监听边界，但共享的服务根仍应保持明确。

func buildServer(serviceCtx context.Context, handler http.Handler) *http.Server {
	return &http.Server{
		Addr:    ":8080",
		Handler: handler,
		BaseContext: func(listener net.Listener) context.Context {
			// 不把 listener 转成请求字段；这里只返回服务范围的根上下文。
			if listener == nil {
				// 正常的 Server 启动路径会提供监听器，这里只保留安全兜底。
				return serviceCtx
			}
			return serviceCtx
		},
	}
}

官方实现会先准备一个默认的 context.Background()，在 BaseContext 非空时调用它，并在返回值为 nil 时直接终止启动流程。因此，回调的第一条契约就是始终返回有效上下文；不要把“暂时没有配置”表达成 nil。

连接级信息不要硬塞进 BaseContext

如果需求是给每条 TCP 连接附加连接编号、来源地址或连接限流器，应优先看 Server.ConnContext。它接收从 BaseContext 派生出的上下文和具体 net.Conn，更适合把连接身份加入上下文；请求处理函数再通过 r.Context() 读取连接级信息。

如果需求只属于某一个请求，例如认证后的主体、请求 ID 或解析后的参数，则在中间件中基于 r.Context() 派生，不要修改服务根。Context 中的值应服务于请求范围的元数据传递，不应替代普通函数参数、配置对象或业务输入。

关闭时怎样判断 BaseContext 是否真的接上

排查时可以按三层证据推进。第一层看回调是否被目标 http.Server 使用：如果代码实际启动的是另一个 Server，设置字段的对象自然不会生效。第二层确认回调返回值非空，且服务根取消函数确实在关闭路径执行。第三层在 Handler 中观察 r.Context().Done() 是否会随服务根取消而结束。

func observeServiceStop(w http.ResponseWriter, r *http.Request) {
	// 只观察请求上下文的取消，不把取消原因写入响应中的敏感字段。
	select {
	case 

这段代码是排查思路示例，不代表任何线上请求已经执行。实际服务中还要结合自己的超时策略和优雅关闭顺序：Shutdown 负责停止接收新连接并等待处理中的请求，服务根取消则负责通知依赖该根的工作。

常见问题

BaseContext 不设置会影响请求吗？

不会。net/http 会使用 context.Background() 作为默认根；只有需要统一的服务级生命周期或共享元数据时才需要显式设置。

BaseContext 能返回每次新建的 WithCancel 吗？

技术上可以返回非空上下文，但这样会让不同调用之间的取消关系难以管理。若目标是服务级控制，通常应在启动前创建一棵可取消根树；若目标是连接级隔离，应考虑 ConnContext。

为什么把请求 ID 放进 BaseContext 不合适？

BaseContext 位于服务级，不知道当前请求是谁；把请求 ID 放在那里会造成跨请求复用或覆盖。请求 ID 应在中间件中基于 r.Context() 派生。

BaseContext 和 ConnContext 有什么区别？

BaseContext 提供服务接收请求时使用的共同根；ConnContext 在这个根之上接收具体连接并进一步修改连接上下文。需要读取 net.Conn 属性时，优先使用 ConnContext。