Go net/http.Transport 返回错误时怎么区分原因

排查 Go HTTP 请求失败时，最容易混淆的是“服务端返回了错误状态码”和“Transport 根本没有完成一次 HTTP 事务”。前者通常是 resp != nil && err == nil，应按状态码处理；后者才进入 error 分类。不要只打印 err.Error()，应保留错误链，用 errors.Is 和 errors.As 判断取消、超时、连接阶段与包装类型。

先分清 HTTP 响应和 Transport 错误

http.Transport 的职责是完成底层 HTTP 交换。只要它拿到了合法的 HTTP 响应，服务器返回 404 或 503 仍然属于正常的响应路径，不能用“有 error”来判断业务失败。相反，DNS 失败、连接被拒绝、TLS 握手失败、读取超时等情况，往往只有 error，没有可供业务读取的响应。

调用 http.Client.Do 时还可能看到 *url.Error 包装层；直接调用自定义 RoundTripper 时则更应该保留原始 error 链。第一步只做边界判断：

resp, err := client.Do(req)
if err != nil {
    // 没有完成 HTTP 事务，继续沿错误链判断取消、超时或网络阶段。
    return classifyTransportError(err)
}
defer resp.Body.Close()
if resp.StatusCode >= 500 {
    // 这是服务端响应，不要当成 DNS 或连接错误重试。
    return fmt.Errorf("upstream status: %s", resp.Status)
}
return nil

保留 error 链并识别取消与超时

不要通过字符串匹配“timeout”或直接断言 err == context.DeadlineExceeded。请求库通常会包裹错误，可靠做法是先检查上下文原因，再用 errors.As 取出包装类型和网络接口。

func classifyTransportError(err error) string {
    if err == nil {
        // nil 表示本次调用没有传输错误。
        return "ok"
    }
    if errors.Is(err, context.Canceled) {
        // 调用方主动取消，通常不应自动重试。
        return "canceled"
    }
    if errors.Is(err, context.DeadlineExceeded) {
        // 上下文 deadline 到期，需与服务端慢或本地拨号慢区分。
        return "context-deadline"
    }

    var urlErr *url.Error
    if errors.As(err, &urlErr) {
        // url.Error 提供操作名和 URL，底层原因仍在 Unwrap 链中。
        if urlErr.Timeout() {
            return "url-timeout"
        }
    }
    var netErr net.Error
    if errors.As(err, &netErr) && netErr.Timeout() {
        // 网络层超时可能发生在拨号、TLS 或读写阶段。
        return "network-timeout"
    }
    return "other-transport-error"
}

context.DeadlineExceeded 说明调用截止时间已经到达；net.Error.Timeout() 说明某个网络操作超时，二者可以同时出现。日志应同时记录上下文 deadline、请求阶段和底层错误类型，不能只保留一个标签。

读取 net.OpError 并决定后续动作

net.OpError 常用于描述网络包的操作、网络类型和地址，例如拨号或读写阶段。它适合帮助定位“卡在哪一层”，但不等于“可以安全重试”。写入请求、非幂等 POST 和已经消耗部分请求体的场景，都要先确认服务端是否可能已经收到请求。

var opErr *net.OpError
if errors.As(err, &opErr) {
    // 这些字段用于日志和指标，不要把地址中的敏感信息直接外泄。
    slog.Warn("http transport failed",
        "op", opErr.Op,
        "network", opErr.Net,
        "addr", fmt.Sprint(opErr.Addr),
        "error_type", fmt.Sprintf("%T", err),
    )
}
// 只有幂等请求、可控次数和明确退避策略同时满足时才重试。

建议把修复动作分成三类：主动取消直接结束；上下文超时先检查 deadline 与下游耗时；拨号或连接错误再核对 DNS、代理、连接池和目标地址。TLS 证书、URL 解析、代理认证等确定性错误通常不应盲目重试。

常见问题

收到 503 时为什么 error 还是 nil？

因为 503 是合法 HTTP 响应。应读取状态码和响应体，再按业务决定降级或有限重试，不要把它和连接失败混为一谈。

为什么 errors.As 比类型断言更适合 Transport 错误？

http.Client 和其他中间层可能包装 error。errors.As 会沿 Unwrap 链查找目标类型，能保留包装层提供的上下文。

超时错误一定可以重试吗？

不一定。先判断请求是否幂等、请求体是否可重放，以及超时发生在建立连接还是服务端可能已处理之后。