把请求截止时间完整传递到数据库与下游 HTTP 调用

一个请求的超时不能只写在 Handler 里：如果数据库仍使用 Query，下游仍用没有上下文的请求，接口虽然已经返回，后台工作却可能继续占用连接和 goroutine。更稳妥的做法是把请求上下文当成一条边界契约，沿函数参数传到每一个会阻塞的依赖。

先把截止时间放在请求边界

Go 的 context.Context 用来携带 deadline 和取消信号。服务器收到请求后，r.Context() 会随着客户端断开或服务端处理结束而取消；如果当前接口还需要更短的预算，可以在它的基础上派生子上下文。派生后要立即保留 cancel，让定时器和子节点在提前完成时释放。

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	// 从请求上下文继续收紧预算，不要从 Background 重新开一条链。
	ctx, cancel := context.WithTimeout(r.Context(), 800*time.Millisecond)
	defer cancel() // 提前返回时也释放派生上下文的资源

	result, err := h.service.Load(ctx, r.PathValue("id"))
	if err != nil {
		// 先判断取消原因，再决定返回超时还是内部错误。
		if errors.Is(ctx.Err(), context.DeadlineExceeded) {
			http.Error(w, "request timeout", http.StatusGatewayTimeout)
			return
		}
		http.Error(w, "load failed", http.StatusInternalServerError)
		return
	}
	_ = json.NewEncoder(w).Encode(result)
}

这里的关键不是把超时时间写成固定的 800 毫秒，而是保留父子关系：父请求更早取消时，子上下文也会取消；子上下文的截止时间则不会晚于父上下文。服务层、仓储层的函数签名都接收 ctx context.Context，这样丢失传播链会在代码评审时直接暴露。

数据库查询必须使用 QueryContext

database/sql 的无上下文方法无法表达当前请求的取消边界。查询、单行查询和写入分别使用 QueryContext、QueryRowContext 和 ExecContext。驱动能否立刻中断数据库端工作取决于驱动与数据库，但调用方至少不会再把一个已经失效的请求当成无限等待。

func (r *Repo) FindUser(ctx context.Context, id int64) (User, error) {
	const query = `SELECT id, name FROM users WHERE id = ?`
	rows, err := r.db.QueryContext(ctx, query, id)
	if err != nil {
		// QueryContext 返回的错误仍要结合 ctx.Err 判断来源。
		return User{}, classifyContextError(ctx, err)
	}
	defer rows.Close() // 无论 Scan 是否成功，都释放结果集

	if !rows.Next() {
		if err := rows.Err(); err != nil {
			return User{}, classifyContextError(ctx, err)
		}
		return User{}, sql.ErrNoRows
	}
	var user User
	if err := rows.Scan(&user.ID, &user.Name); err != nil {
		return User{}, err
	}
	return user, nil
}

不要在仓储层为了“方便”写 context.Background()，也不要把 ctx 存进结构体后跨请求复用。上下文是一次调用的边界；数据库连接池、事务和结果集则是需要显式释放或提交的资源。

下游 HTTP 请求要绑定同一个 ctx

下游调用应把同一个上下文交给 http.NewRequestWithContext。官方文档定义的范围包括获取连接、发送请求以及读取响应头和响应体，因此只给客户端设置一个固定总超时，不能替代请求级取消。成功拿到响应后仍要关闭 Body，否则连接复用会受到影响。

func (s *Service) FetchProfile(ctx context.Context, id string) ([]byte, error) {
	url := "https://api.example.test/profiles/" + url.PathEscape(id)
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return nil, err
	}
	resp, err := s.client.Do(req)
	if err != nil {
		// ctx.Err 能帮助上层区分请求预算耗尽和网络错误。
		return nil, classifyContextError(ctx, err)
	}
	defer resp.Body.Close() // 读取完成后归还连接资源
	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("profile status: %s", resp.Status)
	}
	return io.ReadAll(resp.Body)
}

按三个边界定位截止时间丢失

还要注意一个边界：取消函数只发出停止信号，并不等待 goroutine、驱动或远端服务瞬间结束。日志应记录请求 ID、deadline、ctx.Err 和依赖调用耗时，复查时才能知道是上游预算不足，还是某个实现没有响应取消。

相关问题

所有函数都应该创建新的 WithTimeout 吗

不应该。入口或明确拥有预算的业务层创建派生上下文即可，普通函数只接收并传递 ctx。每层重复收紧会让剩余时间难以推断，只有确实存在独立子任务预算时才再派生。

ctx.Err 返回什么才表示截止时间到了

截止时间到期通常对应 context.DeadlineExceeded，主动取消对应 context.Canceled。实际调用还要保留原始错误，使用 errors.Is 判断，不要依赖错误文本。