Go HTTP 请求超时后服务端仍在处理怎么定位责任边界

Go HTTP 请求在浏览器、网关或客户端显示超时，不等于服务端已经停止。真正要查的是三个时间边界：调用方何时放弃、r.Context() 何时被取消、服务端给下游设置的 deadline 何时到期。如果 Handler 返回后仍有 goroutine 使用旧请求继续查库或调 RPC，日志还会继续出现；如果下游没有接收这个 ctx，服务端也可能一直等到自己的连接超时。

先看请求上下文和下游调用是否共享同一个取消信号，再用 ctx.Err() 与 context.Cause(ctx) 区分“客户端断开”“服务端预算耗尽”和“业务错误”。只看到一条 timeout 日志，不能直接判定责任在服务端。

先判断是谁先结束了等待

net/http 的服务端请求上下文会在客户端连接关闭、HTTP/2 请求被取消，或 ServeHTTP 返回时取消。这个规则说明了一个常见误区：客户端的本地超时不会像远程杀进程一样强制终止服务端代码；只有取消信号沿着请求连接传回来，Handler 和下游才有机会停下。

排查时先把日志拆成四个时间点：收到请求、创建下游 deadline、下游返回、Handler 返回。若客户端在第二个时间点前已报超时，但服务端直到第三个时间点才结束，先检查代理是否仍保持上游连接，再看下游请求是否使用了同一个上下文。

把同一个请求上下文传进下游

服务端通常需要比客户端更早结束下游等待，给编码、日志和响应留出余量。可以从 r.Context() 派生一个短预算，并把它继续传入 HTTP、数据库或 RPC 方法。不要因为“下游是内部服务”就改用 context.Background()，那会切断客户端取消和上游 deadline。

var errHandlerBudget = errors.New("handler downstream budget exhausted")

func handleOrder(w http.ResponseWriter, r *http.Request) {
	// 从请求上下文派生预算，客户端取消仍会沿父上下文传下来。
	ctx, cancel := context.WithTimeoutCause(r.Context(), 900*time.Millisecond, errHandlerBudget)
	defer cancel() // 释放定时器以及派生上下文持有的资源。

	order, err := loadOrder(ctx, r.PathValue("id"))
	if err != nil {
		// 先看请求是否已经结束，再决定响应和日志级别。
		if errors.Is(ctx.Err(), context.Canceled) || errors.Is(ctx.Err(), context.DeadlineExceeded) {
			logRequestEnd(r, ctx, err)
			return
		}
		http.Error(w, "load order failed", http.StatusBadGateway)
		return
	}
	writeOrder(w, order)
}

func loadOrder(ctx context.Context, id string) (Order, error) {
	// 下游函数继续接收同一个 ctx，不能在这里重新使用 Background。
	return orderClient.Fetch(ctx, id)
}

这里的关键不是 900ms 这个数字，而是预算的所有权清晰：Handler 创建并释放派生上下文，loadOrder 只负责传递。数据库查询应使用 QueryContext，HTTP 客户端请求应使用 NewRequestWithContext 或 req.WithContext；否则上游取消只会让日志变化，无法停止实际等待。

用 Err 和 Cause 分开记录责任

ctx.Err() 给出标准类别，常见值是 context.Canceled 和 context.DeadlineExceeded。从 Go 1.20 起可以用 context.Cause 记录更具体的取消原因；WithTimeoutCause 和 WithDeadlineCause 用于在预算到期时保存原因，前者的标准错误仍然是 deadline exceeded。

func logRequestEnd(r *http.Request, ctx context.Context, downstreamErr error) {
	// Err 记录可聚合的标准类别，Cause 记录本服务设置的具体预算原因。
	entry := map[string]any{
		"path":            r.URL.Path,
		"context_err":     errorText(ctx.Err()),
		"context_cause":   errorText(context.Cause(ctx)),
		"downstream_error": errorText(downstreamErr),
	}
	logger.Warn("request ended before downstream completed", "fields", entry)
}

func errorText(err error) string {
	if err == nil {
		return ""
	}
	return err.Error()
}

判断顺序也很重要：先用 errors.Is 比较，不要只比较错误字符串。若 ctx.Err() 为空，但下游返回业务错误，责任更可能在下游逻辑或网络层；若 ctx.Err() 已是 deadline exceeded，同时 context.Cause(ctx) 是自定义预算错误，就把它记录为本服务预算到期，而不是泛化成“服务器故障”。

Handler 返回后还在处理，问题通常出在生命周期

如果代码启动 goroutine 后直接返回，goroutine 是否结束就不再由 HTTP 响应生命周期保证。它可能继续读缓存、等待连接或写一条迟到日志。这个工作若属于请求本身，应在 goroutine 内监听 ctx.Done()，并在退出前关闭资源；若确实需要在请求结束后继续执行，应使用队列或带独立超时的后台任务，并在日志中显式写出“已脱离请求”。

还有一个容易忽略的边界：请求结束后不要再向 ResponseWriter 写结果。超时错误只能影响本次请求的状态，不能靠后台 goroutine 补发一个已经错过的响应。把“返回给客户端的状态”和“后台任务的最终状态”分成两条记录，才能避免监控把两次结果合并成一条矛盾日志。

• 请求内工作：传递 r.Context()，监听 Done()，使用 defer cancel() 和资源关闭。
• 独立后台工作：进入队列，生成独立任务 ID，设置自己的 deadline，并记录脱离请求的原因。
• 错误归因：保留 context_err、context_cause、downstream_error 和 elapsed time 四个字段。

常见问题

客户端超时后服务端一定会停止吗？

不一定。只有取消信号传到服务端请求上下文，并且下游真正使用这个上下文时，服务端工作才有机会提前结束。

为什么 ctx.Err 是 deadline exceeded，但 Cause 看起来不同？

标准错误负责稳定分类，自定义 cause 负责描述是哪一个内部预算或策略触发了 deadline，两者可以同时保留。

可以用 context.Background 让关键任务继续吗？

可以表达“这不是请求生命周期内的工作”，但更稳妥的做法是进入后台队列并设置独立生命周期，而不是在 Handler 里悄悄启动无法追踪的 goroutine。

发布前的超时责任检查清单

复盘一条“请求超时但服务端还在处理”的记录时，至少核对：客户端和网关的超时值、r.Context() 的结束原因、派生 deadline、下游 API 是否接收 ctx、Handler 返回后是否仍有请求内 goroutine。五项都能从日志或代码路径对应上，才能判断下一步该改客户端预算、服务端 deadline，还是修复下游取消传播。