Go context 超时控制实战：让 HTTP 调用按时取消

后端接口调用外部服务时，最怕“对方慢了，我们也跟着一直等”。一个订单接口里调用库存、支付、优惠服务，如果某个下游没有按时返回，上游请求就会被拖住，连接池和协程也会被占着。

Go 的 context 很适合解决这类问题。它可以在请求链路中传递取消信号和截止时间，让 HTTP 调用、数据库查询和后台任务知道“该停了”。本文用一个 HTTP 调用案例，把 context.WithTimeout 的日常写法讲清楚。

摘要

本文会从一个没有超时控制的 HTTP 调用开始，逐步加入 context.WithTimeout、defer cancel()、http.NewRequestWithContext 和错误判断。读完后，你可以把同样的结构用到第三方接口调用、微服务调用和需要按时返回的后台任务中。

适合人群

适合已经会写 Go 基础 HTTP 请求、正在做后端接口、微服务调用或任务处理的开发者。你需要了解 net/http、函数返回错误和基础结构体定义。

目录

1. 没有超时控制的问题
2. 用 context.WithTimeout 设置时间边界
3. 把 context 传给 HTTP 请求
4. 如何判断超时和取消
5. 接口聚合场景怎么组织
6. 常见坑和生产建议
7. 完整示例

一、没有超时控制的问题

先看一个简化版调用。它可以正常请求接口，但没有明确的业务时间边界：

package main

import (
	"fmt"
	"io"
	"net/http"
)

func fetchProfile(url string) (string, error) {
	resp, err := http.Get(url)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return "", err
	}
	return string(body), nil
}

func main() {
	body, err := fetchProfile("https://example.com/profile")
	if err != nil {
		fmt.Println("request failed:", err)
		return
	}
	fmt.Println(body)
}

真实项目里，下游慢、网络抖动、连接半开都可能让请求等待过久。即使底层客户端有默认行为，业务层也应该说清楚：这个步骤最多等多久。

二、用 context.WithTimeout 设置时间边界

context.WithTimeout 会基于父上下文创建一个带超时时间的子上下文。到时间后，这个上下文会发出取消信号。

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

这里的 defer cancel() 很重要。即使请求提前完成，也应该调用 cancel 释放和这个上下文相关的资源。它不是只在超时时才需要。

三、把 context 传给 HTTP 请求

要让 HTTP 调用感知上下文，需要用 http.NewRequestWithContext 创建请求：

func fetchProfileWithTimeout(parent context.Context, url string) (string, error) {
	ctx, cancel := context.WithTimeout(parent, 2*time.Second)
	defer cancel()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return "", err
	}

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()

	if resp.StatusCode = 300 {
		return "", fmt.Errorf("bad status: %s", resp.Status)
	}

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return "", err
	}
	return string(body), nil
}

这段代码表达了一个清楚的业务规则：本次资料读取最多等待 2 秒。超过时间后，请求会被取消，调用方可以走降级、重试或返回错误。

四、如何判断超时和取消

当上下文超时或被取消时，错误可能来自 HTTP 客户端，也可能来自上下文本身。实际项目里建议同时判断 ctx.Err()：

body, err := fetchProfileWithTimeout(ctx, url)
if err != nil {
	if errors.Is(ctx.Err(), context.DeadlineExceeded) {
		return "", fmt.Errorf("profile request timeout: %w", err)
	}
	if errors.Is(ctx.Err(), context.Canceled) {
		return "", fmt.Errorf("profile request canceled: %w", err)
	}
	return "", err
}
return body, nil

如果这是接口入口，通常不建议把底层错误原样返回给用户。可以记录详细日志，对外返回更稳定的错误码或提示。

五、接口聚合场景怎么组织

假设一个订单接口需要调用资料服务和优惠服务，可以给整个请求一个总时间，再给每个下游设置自己的时间边界：

func buildOrderPage(parent context.Context, orderID string) error {
	ctx, cancel := context.WithTimeout(parent, 3*time.Second)
	defer cancel()

	if _, err := fetchProfileWithTimeout(ctx, "https://example.com/profile"); err != nil {
		return err
	}

	if _, err := fetchProfileWithTimeout(ctx, "https://example.com/coupon"); err != nil {
		return err
	}

	fmt.Println("order page ready:", orderID)
	return nil
}

外层 ctx 是整体时间边界，内层函数再设置单次 HTTP 调用的时间边界。这样可以避免一个下游把整个接口拖到不可控。

六、常见坑和生产建议

1. 创建了 timeout，却没有传下去

只写 context.WithTimeout 不够。你必须把返回的 ctx 传给真正会等待的操作，例如 HTTP 请求、数据库查询或子函数。

2. 忘记调用 cancel

即使没有超时，也要调用 cancel。推荐创建上下文后立刻写 defer cancel()，让代码路径更稳。

3. 到处使用 context.Background

服务内部函数不应该随手新建根上下文。更好的方式是从入口拿到父上下文，然后一路传下去。这样客户端断开、网关超时或上层取消时，底层工作也能尽快停止。

4. 超时时间只靠经验拍脑袋

建议结合接口目标耗时、下游稳定性、重试策略和用户体验来设置。核心链路可以稍长，非核心链路可以更短并做降级。

5. 日志缺少请求标识

超时问题排查时，日志里最好带上请求 ID、下游名称、耗时和超时时间。否则你只知道失败了，却很难判断是哪一个服务慢。

七、完整示例

下面是一个可以直接放进本地文件运行的版本。为了演示结构，URL 可以换成你自己的测试服务。

package main

import (
	"context"
	"errors"
	"fmt"
	"io"
	"net/http"
	"time"
)

func fetchWithLimit(parent context.Context, url string, limit time.Duration) (string, error) {
	ctx, cancel := context.WithTimeout(parent, limit)
	defer cancel()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return "", err
	}

	start := time.Now()
	resp, err := http.DefaultClient.Do(req)
	cost := time.Since(start)
	if err != nil {
		if errors.Is(ctx.Err(), context.DeadlineExceeded) {
			return "", fmt.Errorf("timeout after %s: %w", cost, err)
		}
		if errors.Is(ctx.Err(), context.Canceled) {
			return "", fmt.Errorf("canceled after %s: %w", cost, err)
		}
		return "", err
	}
	defer resp.Body.Close()

	if resp.StatusCode = 300 {
		return "", fmt.Errorf("bad status: %s", resp.Status)
	}

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return "", err
	}
	return string(body), nil
}

func main() {
	ctx := context.Background()
	body, err := fetchWithLimit(ctx, "https://example.com", 2*time.Second)
	if err != nil {
		fmt.Println("failed:", err)
		return
	}
	fmt.Println("body bytes:", len(body))
}

总结

Go 里的 context 不只是传值工具，更重要的是传递取消信号和时间边界。HTTP 调用要想按时停止，需要创建带超时的上下文、及时 cancel、用 NewRequestWithContext 把上下文传给请求，并在错误处理中区分超时、取消和普通失败。把这些写成固定模板，接口稳定性会好很多。

参考资料

本文参考 Go 官方 context 包文档和 net/http 请求上下文说明，示例为后端 HTTP 调用场景原创整理。