正确做法是用 context.WithTimeout 包裹 c.Request.Context() 并传给 http.Client，复用全局配置的 client，对读多写少数据加 sync.Map 缓存，降级逻辑写在 handler 内而非依赖中间件。
用 context.WithTimeout 控制第三方调用超时
不加超时的 http.Client 调用，一旦下游响应慢或卡死，会拖垮整个 Gin 请求协程，导致连接堆积、goroutine 泄漏。Gin 本身不干预你的 HTTP 调用逻辑，但 gin.Context 可以天然传递 context.Context。
正确做法是把 c.Request.Context() 包一层超时，再传给下游 client：
func callExternalAPI(c *gin.Context) {
// 3 秒内必须返回，否则 cancel
ctx, cancel := context.WithTimeout(c.Request.Context(), 3*time.Second)
defer cancel()
<pre class="brush:php;toolbar:false;">req, _ := http.NewRequestWithContext(ctx, "GET", "https://api.example.com/data", nil)
resp, err := http.DefaultClient.Do(req)
if err != nil {
if errors.Is(err, context.DeadlineExceeded) {
c.JSON(504, gin.H{"error": "upstream timeout"})
return
}
c.JSON(502, gin.H{"error": "upstream failed"})
return
}
defer resp.Body.Close()
// ...}
- 别直接用
time.Sleep或无上下文的http.Get—— 它们无法被父请求中断 - 超时值要按第三方 SLA 设定，一般 1–5s；不要统一设成 30s
- 注意：
context.WithTimeout的 timer 是 goroutine 级的，不会阻塞当前 handler
复用 http.Client 连接池
每次 new 一个 http.Client 会导致 TCP 连接无法复用，频繁建连 + TLS 握手，QPS 上不去还耗 CPU。Gin 路由 handler 是短生命周期的，但 client 必须是全局复用的。
声明一次，用 everywhere：
var externalClient = &http.Client{
Timeout: 5 * time.Second,
Transport: &http.Transport{
MaxIdleConns: 100,
MaxIdleConnsPerHost: 100,
IdleConnTimeout: 30 * time.Second,
TLSHandshakeTimeout: 5 * time.Second,
},
}- 别在 handler 里写
http.Client{}—— 每次都新建 transport，连接池失效 -
MaxIdleConnsPerHost建议 ≥ 你调用的第三方域名数 × 并发期望值 - 如果调用多个不同第三方（如支付 + 短信 + 地图），可为每个 domain 单独配 transport，避免争抢连接
加本地缓存减少重复请求
对读多写少、时效性要求不高的第三方数据（如地区列表、配置项、汇率快照），重复请求纯属浪费。Gin 不带缓存层，得自己加轻量方案。
高频小数据优先用 sync.Map，比 Redis 更快且无网络开销：
var configCache = sync.Map{} // key: string, value: struct{Data []byte; ExpiresAt time.Time}
<p>func getCachedConfig(c *gin.Context) {
key := "thirdparty:regions"
if data, ok := configCache.Load(key); ok {
item := data.(struct{ Data []byte; ExpiresAt time.Time })
if time.Now().Before(item.ExpiresAt) {
c.Data(200, "application/json", item.Data)
return
}
}</p><pre class="brush:php;toolbar:false;">// 缓存失效，重新请求
resp, _ := externalClient.Get("https://api.example.com/regions")
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
configCache.Store(key, struct{ Data []byte; ExpiresAt time.Time }{
Data: body,
ExpiresAt: time.Now().Add(5 * time.Minute),
})
c.Data(200, "application/json", body)}
- 别用
map+mutex手写 ——sync.Map对读多写少场景更高效 - 缓存 key 要包含版本或签名，避免脏数据（比如第三方改了 schema 但没改 URL）
- 注意：缓存内容是
[]byte，不是反序列化后的 struct —— 避免每次解码开销
错误降级与熔断要写进 handler，不能只靠中间件
第三方服务不可用时，中间件能统一记录日志，但无法决定「返回什么」—— 降级策略（如返回缓存、默认值、空数组）必须在业务 handler 里编码。Panic 或 panic-recover 不解决可用性问题。
- 别指望
gin.Recovery()挽救下游失败 —— 它只捕获 panic，不处理 HTTP 5xx 或 timeout - 对非关键第三方调用（如埋点上报、通知推送），建议用
go func() { ... }()异步发，但记得用带 timeout 的 context - 真要熔断（如连续 5 次失败暂停 30 秒），得用状态变量 +
time.Now()判断，不要依赖外部库增加链路复杂度
第三方 API 性能瓶颈从来不在 Gin，而在于你如何管理它的生命周期、连接、超时和失败路径。最常被忽略的是：把「调用失败」当成异常处理，而不是正常业务分支来设计。
