Go基于自定义RoundTripper的HTTP客户端超时时随机返回两类错误的原因排查

根本原因 #

当你为http.Client设置Timeout字段时，标准库会在每个请求发起前，自动为请求上下文绑定一个和Timeout时长一致的超时定时器。定时器到期后会广播全局取消信号，信号的传递时序和http.DefaultTransport的执行进度没有强制约束，存在goroutine调度层面的竞态，这就是两类错误随机返回的核心原因。

两类错误的精准触发条件 #

触发返回context deadline exceeded #

• 到期的取消信号先被底层http.DefaultTransport的内部监听逻辑捕获时触发
• 该场景下Transport正处于阻塞等待状态：比如正在等待TCP连接建立、阻塞读服务端返回的响应头/响应体
• Transport内部的select逻辑直接命中req.Context().Done()分支，直接返回context原生的context.DeadlineExceeded错误实例
• 该错误顺着自定义rt.RoundTrip的透传流程返回给Client，Client校验确认context已超时后，将其包装为最终的*url.Error返回，最终打印的错误文本会包含context deadline exceeded

触发返回net/http: request canceled #

• 到期的取消信号先被Client层的主流程监听逻辑捕获时触发
• 该场景下Transport刚好处于两段阻塞流程的间隙：比如刚完成某段TCP读操作、还没进入下一次监听取消信号的select分支，没有第一时间收到广播的取消信号
• Client主流程goroutine感知到context超时后，主动终止对Transport返回值的等待，直接返回内置的errRequestCanceled错误实例（对应固定文本net/http: request canceled），Transport后续的返回值会被直接丢弃

实践补充 #

• 两类错误在语义上完全等价：从Go 1.20开始，net/http: request canceled对应的错误实例实现了Unwrap方法，可通过errors.Is(err, context.DeadlineExceeded)统一识别为超时类错误，无需依赖错误字符串做判断
• 你实现的自定义rt.RoundTripper逻辑不会改变这个竞态特性：因为竞态完全发生在Client与Transport的原生交互流程中，自定义层仅做错误透传，不参与取消信号的传递逻辑
• 哪怕你在自定义RoundTripper中对Transport返回的错误做了格式包装，这个竞态特性依然存在：当Client层先捕获超时信号时，流程会直接在Client层终止，根本不会走到自定义RoundTripper的错误返回分支

内容的提问来源于stack exchange，提问作者2hamed