golang

Go 超时和重试入门：context、退避和幂等性一起看

写后端服务时，外部调用失败是常态。网络会抖，依赖会慢，网关会返回 502，数据库也可能短暂不可用。初学者最容易写出两种极端代码：一种完全不重试，偶发错误直接暴露给用户；另一种无脑重试很多次，把一个小抖动放大成更大的压力。正确做法不是“永远重试”或“永不重试”，而是把超时、退避和幂等性一起考虑。

PlumePHP 9 分钟阅读 4140 字

写后端服务时，外部调用失败是常态。网络会抖，依赖会慢，网关会返回 502，数据库也可能短暂不可用。初学者最容易写出两种极端代码：一种完全不重试，偶发错误直接暴露给用户；另一种无脑重试很多次，把一个小抖动放大成更大的压力。正确做法不是“永远重试”或“永不重试”，而是把超时、退避和幂等性一起考虑。

本文用一个调用用户资料服务的例子，讲 Go 中如何用 context 控制总耗时，如何写简单退避重试，以及哪些请求不应该随便重试。

先有总超时

没有总超时的重试很危险。比如每次请求最多 3 秒，重试 5 次，最坏就可能拖到 15 秒以上。用户早就离开了，服务还在忙。更稳的方式是给整个操作设置一个总 deadline：

func LoadProfile(ctx context.Context, userID string) (Profile, error) {
	ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
	defer cancel()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet,
		"https://profile.example.com/users/"+url.PathEscape(userID), nil)
	if err != nil {
		return Profile{}, err
	}

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

	if resp.StatusCode != http.StatusOK {
		return Profile{}, fmt.Errorf("profile status: %d", resp.StatusCode)
	}

	var profile Profile
	if err := json.NewDecoder(resp.Body).Decode(&profile); err != nil {
		return Profile{}, err
	}
	return profile, nil
}

NewRequestWithContext 很重要。它让 context 取消可以中断 HTTP 请求。只在函数外面创建 context，但请求没有使用它，取消就传不下去。

哪些错误值得重试

不是所有错误都值得重试。一般来说，可以考虑重试：

  • 网络临时错误
  • 502、503、504
  • 连接被重置
  • 依赖明确返回“稍后再试”

不应该重试：

  • 400、401、403 这类请求本身错误
  • 参数校验失败
  • 没有幂等保障的写操作
  • 已经超过总超时的请求

一个判断函数可以这样写：

func retryableStatus(code int) bool {
	return code == http.StatusBadGateway ||
		code == http.StatusServiceUnavailable ||
		code == http.StatusGatewayTimeout
}

实际项目里可以再处理 429 Too Many Requests，并尊重响应头里的 Retry-After。入门阶段先把最常见的 5xx 抖动处理好。

简单退避重试

重试不要立刻连续打过去。依赖已经慢了，你还快速补几拳，只会加重压力。可以用递增等待：

func doWithRetry(ctx context.Context, client *http.Client, req *http.Request) (*http.Response, error) {
	delays := []time.Duration{
		100 * time.Millisecond,
		300 * time.Millisecond,
		700 * time.Millisecond,
	}

	var lastErr error
	for attempt := 0; attempt <= len(delays); attempt++ {
		resp, err := client.Do(req.Clone(ctx))
		if err == nil && !retryableStatus(resp.StatusCode) {
			return resp, nil
		}
		if resp != nil {
			resp.Body.Close()
			lastErr = fmt.Errorf("temporary status: %d", resp.StatusCode)
		} else {
			lastErr = err
		}

		if attempt == len(delays) {
			break
		}

		select {
		case <-time.After(delays[attempt]):
		case <-ctx.Done():
			return nil, ctx.Err()
		}
	}
	return nil, lastErr
}

这里每次用 req.Clone(ctx)，确保请求使用当前 context。等待时也监听 ctx.Done()，否则总超时到了，函数还会傻等下一次重试。

这个例子只适合没有请求体或请求体可重复读取的请求。POST JSON body 如果已经被读掉，重试时不能直接复用同一个 body。要么提前把 body 放在 []byte 里，每次重新创建 reader；要么确认调用不需要重试。

幂等性比重试次数更重要

GET 通常可以重试，因为它应该只读取数据。创建订单、扣款、发送短信这类操作不能随便重试。第一次请求可能已经成功，只是响应在网络上丢了；第二次重试可能造成重复订单或重复扣款。

如果写操作必须重试，通常要设计幂等键：

req.Header.Set("Idempotency-Key", operationID)

服务端用这个 key 识别同一次业务操作。相同 key 的重复请求应该返回同一个结果，而不是重复执行。幂等性是业务协议，不是客户端重试库能单方面解决的东西。

入门阶段可以记住一句话：没有幂等保障的写操作，宁可少重试，也不要偷偷重试。

不要把超时藏太深

一个常见坏味道是每个底层函数都自己 context.WithTimeout(context.Background(), time.Second)。这样上层请求取消传不下来，链路里的 deadline 也被切断。更好的方式是从 handler 开始传 r.Context()：

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
	profile, err := h.profileClient.Load(r.Context(), userID)
	if err != nil {
		http.Error(w, "load profile failed", http.StatusBadGateway)
		return
	}
	writeJSON(w, profile)
}

底层可以在传入 context 的基础上设置更短超时：

func (c *ProfileClient) Load(ctx context.Context, userID string) (Profile, error) {
	ctx, cancel := context.WithTimeout(ctx, c.timeout)
	defer cancel()
	// 发请求
}

这样上层取消和底层超时都能生效。不要在业务函数里凭空创建 context.Background()，除非它真的是脱离请求生命周期的后台任务。

记录重试信息

重试失败时，日志里最好包含 attempt、耗时和最后错误：

log.Printf("call profile failed attempt=%d cost=%s err=%v", attempt, time.Since(start), err)

如果没有日志，线上只会看到接口慢或失败，却不知道背后重试了几次。重试会增加延迟，成功率提高的同时也可能掩盖依赖不稳定。指标上最好能区分“首次成功”和“重试后成功”，这样你才能知道系统是否正在变脆。

小结

Go 里写可靠外部调用，要先设置总超时，再决定哪些错误可重试，并用退避避免放大依赖压力。重试必须尊重 context 取消，写操作要先考虑幂等性。

重试不是让错误消失的魔法。它只是处理短暂故障的一种手段。真正可靠的系统，会把超时、幂等、日志、指标和错误边界一起设计，而不是在失败后简单多试几次。

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

  • 函数是否处理了所有 error 返回值
  • 并发代码是否有明确的退出路径和 WaitGroup
  • 用户输入是否经过校验和清洗
  • 敏感配置是否通过环境变量或加密存储注入
  • 测试是否覆盖了正常路径和至少一个错误路径
  • 日志是否包含足够的上下文信息但不泄露敏感数据
  • 接口设计是否符合最小接口原则

CI/CD 集成建议

  • 每次提交前运行 go fmt ./...
  • CI 中运行 go vet ./... 和 golangci-lint run
  • 单元测试使用 go test -race ./... 检测数据竞争
  • 关键路径的 benchmark 加入回归测试
  • 使用 go mod verify 确保依赖完整性

性能调优检查点

  • 使用 pprof 分析 CPU 和内存使用
  • 关注 benchmark 的 allocs/op，减少高频路径的堆分配
  • 检查数据库查询是否使用索引
  • 确认外部 HTTP 调用有合理的超时设置
  • 缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

  1. goroutine 和线程的区别
  2. channel 的缓冲和非缓冲用法
  3. defer 的执行顺序和与返回值的关系
  4. map 的并发不安全性和解决方案
  5. interface 的隐式实现和类型断言
  6. slice 的底层数组和 append 机制
  7. GC 的基本原理和调优参数
  8. context 的使用场景和超时控制
  9. error 的包装和 errors.Is/errors.As
  10. sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

  1. 不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
  2. 资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
  3. 不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
  4. 不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
  5. 不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
  6. 不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

  1. 把文中所有示例代码在自己的机器上跑一遍
  2. 给示例代码补充错误分支的测试用例
  3. 尝试基于本文内容构建一个小型完整项目
  4. 在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
  5. 订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

  • Go 官方网站：https://go.dev/
  • Go 标准库文档：https://pkg.go.dev/std
  • Go by Example：https://gobyexample.com/
  • Effective Go：https://go.dev/doc/effective_go
  • Go 常见问题：https://go.dev/doc/faq
  • Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

指数退避和抖动

简单的固定退避可用，但在高并发场景下，所有客户端可能在同一时刻重试，形成"惊群效应"。指数退避配合随机抖动能更好地分散压力：

func backoffWithJitter(attempt int, base, max time.Duration) time.Duration {
	if attempt < 0 {
		attempt = 0
	}
	// 指数增长：base * 2^attempt
	d := base * time.Duration(1<<attempt)
	if d > max {
		d = max
	}
	// 添加随机抖动，范围 [d/2, d]
	jitter := time.Duration(rand.Int63n(int64(d/2))) + d/2
	return jitter
}

用法：

delays := []time.Duration{
	backoffWithJitter(0, 100*time.Millisecond, 5*time.Second),
	backoffWithJitter(1, 100*time.Millisecond, 5*time.Second),
	backoffWithJitter(2, 100*time.Millisecond, 5*time.Second),
}

抖动让重试时间分散开，降低对下游的瞬间冲击。很多云服务的 SDK 都内置了这种策略。

带熔断的重试

如果下游服务已经宕机，持续重试只会徒增压力。可以结合熔断器（Circuit Breaker）模式：

type CircuitBreaker struct {
	failures    int
	threshold   int
	resetAfter  time.Duration
	lastFailure time.Time
	state       State // Closed, Open, HalfOpen
	mu          sync.RWMutex
}

func (cb *CircuitBreaker) Call(fn func() error) error {
	cb.mu.Lock()
	if cb.state == Open && time.Since(cb.lastFailure) < cb.resetAfter {
		cb.mu.Unlock()
		return errors.New("circuit breaker open")
	}
	cb.mu.Unlock()

	err := fn()

	cb.mu.Lock()
	defer cb.mu.Unlock()
	if err != nil {
		cb.failures++
		cb.lastFailure = time.Now()
		if cb.failures >= cb.threshold {
			cb.state = Open
		}
		return err
	}
	cb.failures = 0
	cb.state = Closed
	return nil
}

熔断器记录了失败次数，超过阈值后直接进入快速失败，不再尝试请求。一段冷却时间后才允许试探性请求。

重试的观测和指标

重试行为应该被监控。建议记录以下指标：

  • 请求总数
  • 首次成功数
  • 重试后成功数
  • 最终失败数
  • 每次重试的延迟分布
func callWithMetrics(ctx context.Context, client *http.Client, req *http.Request) (*http.Response, error) {
	start := time.Now()
	resp, err := doWithRetry(ctx, client, req)
	if err != nil {
		metricsCounter.Inc("request_failed")
		return nil, err
	}

	attempts := getAttemptsFromContext(ctx)
	if attempts > 1 {
		metricsCounter.Inc("request_retry_success")
	} else {
		metricsCounter.Inc("request_first_success")
	}
	metricsHistogram.Observe("request_duration", time.Since(start).Seconds())
	return resp, nil
}

如果"重试后成功"的比例持续升高，说明依赖服务正在变脆，需要整体排查。

请求体的重试问题

POST/PUT 请求带 body 时，重试需要特别注意：

func retryablePost(ctx context.Context, url string, body []byte) (*http.Response, error) {
	var lastErr error
	for attempt := 0; attempt < 3; attempt++ {
		req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
		if err != nil {
			return nil, err
		}
		req.Header.Set("Content-Type", "application/json")

		resp, err := http.DefaultClient.Do(req)
		if err == nil && !retryableStatus(resp.StatusCode) {
			return resp, nil
		}
		if resp != nil {
			resp.Body.Close()
		}
		lastErr = err

		select {
		case <-time.After(time.Duration(attempt+1) * 100 * time.Millisecond):
		case <-ctx.Done():
			return nil, ctx.Err()
		}
	}
	return nil, lastErr
}

关键点是每次重试都要用 bytes.NewReader(body) 创建新的 reader，因为 io.Reader 通常只能读取一次。

常见坑与避坑指南

  1. 重试次数不设上限：无限重试会让小病变成大病。总是设置最大重试次数。
  2. 退避时间过短：立刻重试会给已经过载的服务雪上加霜。至少等待几十毫秒。
  3. 不区分错误类型：4xx 错误重试没用，5xx 和连接错误才值得重试。
  4. 忽略 context 取消：重试循环里必须有 ctx.Done() 分支。
  5. 写操作盲目重试：没有幂等保障的写操作宁可失败也不重试。
  6. 不记录重试历史：线上出问题不知道是第一次就失败还是重试了 N 次才失败。

小结

Go 里写可靠外部调用，要先设置总超时，再决定哪些错误可重试，并用退避避免放大依赖压力。重试必须尊重 context 取消，写操作要先考虑幂等性。

重试不是让错误消失的魔法。它只是处理短暂故障的一种手段。真正可靠的系统，会把超时、幂等、日志、指标、熔断和错误边界一起设计，而不是在失败后简单多试几次。

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「golang」更多文章

  1. 熔断、降级与限流：Go 微服务韧性设计完全指南
  2. 事件溯源与 CQRS 在 Go 中的实践：复杂业务系统的架构升级
  3. TinyGo 嵌入式开发与物联网实战：微控制器编程完全指南