Go net/http.Client 怎样保留错误信息

我在给 HTTP 客户端补日志时，最容易踩的坑不是“没有 error”，而是把不同阶段的错误混成一条字符串。http.Client.Do 的正确边界是：请求没有拿到可用响应时返回 error；服务端返回 404、500 等非 2xx 状态时，通常仍然是 err == nil。因此，保留错误信息的做法是把“请求阶段”“状态判断”“响应体读取”分开记录，并用 %w 保留原始 cause。

推荐把原始错误作为可 unwrap 的 cause，再附加阶段和状态码等上下文；不要用新的字符串覆盖旧 error，也不要把 HTTP 状态码伪装成网络错误。

本文要点：先判断 err；再处理 resp.StatusCode；读取 body 时另行包装错误；最后让上层用 errors.As、errors.Is 或结构化字段做决策。

先把 Client.Do 的三种结果分开

第一类是没有完成 HTTP 交互，例如 DNS、连接或 TLS 失败，此时 err != nil，返回的 resp 通常可以忽略。第二类是已经拿到响应，但状态码表示业务失败，这并不会自动进入 error 分支。第三类是响应存在，读取 Body 时才失败，例如超时发生在读 body 阶段。三类问题的重试和告警策略并不相同。

还要记住生命周期：当 err == nil 时关闭 resp.Body，最好读到 EOF；否则底层 Transport 可能无法复用连接。这个关闭动作属于资源管理，不应通过重新拼接错误字符串来“顺手处理”。

用 %w 保留请求阶段的原始错误

func fetch(ctx context.Context, client *http.Client, rawURL string) ([]byte, error) {
    // 把 URL 解析和请求创建也放进阶段化错误，方便日志定位。
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
    if err != nil {
        return nil, fmt.Errorf("创建 HTTP 请求: %w", err)
    }

    // Do 的 error 代表未能取得可用响应或客户端策略失败。
    resp, err := client.Do(req)
    if err != nil {
        var urlErr *url.Error
        if errors.As(err, &urlErr) {
            return nil, fmt.Errorf("发送 HTTP 请求（操作=%s）: %w", urlErr.Op, err)
        }
        return nil, fmt.Errorf("发送 HTTP 请求: %w", err)
    }
    // err 为 nil 才进入响应生命周期，函数退出时统一关闭 body。
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("读取 HTTP 响应体（状态=%d）: %w", resp.StatusCode, err)
    }
    if resp.StatusCode = 300 {
        // 状态码不是传输 error，保留有限的 body 只用于诊断。
        return nil, fmt.Errorf("HTTP 状态异常（状态=%d，响应体=%q）", resp.StatusCode, strings.TrimSpace(string(body)))
    }
    return body, nil
}

这里的关键不是包装文字，而是末尾的 %w。它让调用方仍能用 errors.As 找到 *url.Error，也能继续判断超时；如果改成 %v 或直接使用 err.Error()，可判断的类型链就断了。

状态码、读取错误与请求错误不要互相覆盖

如果 Do 返回了 error，应该先保留它；不要因为打印了一个“请求失败”就再构造一个全新的错误。相反，拿到 response 后，状态码属于协议结果，body 读取错误属于消费响应时的故障。日志可以同时带上阶段、URL、状态码和 trace id，但原始 cause 只应有一条清晰的链。

对 JSON 接口来说，还可以把“读取成功但反序列化失败”作为下一个阶段包装。这样同一个请求可能分别得到 read response body 或 decode response，排查时不会误以为服务端没有响应。

自定义错误让重试和日志共享上下文

type HTTPError struct {
    // Stage 用于区分 request、read 和 decode 阶段。
    Stage  string
    Status int
    Err    error
}

func (e *HTTPError) Error() string {
    // 保留状态码与阶段，底层错误交给 Unwrap 继续判断。
    if e.Status != 0 {
        return fmt.Sprintf("HTTP %s（状态=%d）: %v", e.Stage, e.Status, e.Err)
    }
    return fmt.Sprintf("HTTP %s: %v", e.Stage, e.Err)
}

func (e *HTTPError) Unwrap() error { return e.Err }

上层可以通过 var he *HTTPError 配合 errors.As 读取阶段和状态，再对 he.Err 做超时或临时错误判断。若错误是状态码问题，重试前还要确认方法是否幂等、请求体能否重新生成，以及服务端是否会把重复提交当成新操作。

判断清单：什么信息值得保留

一句话收束：Client.Do 的 error 链负责保留“为什么没有完成请求”，响应字段负责描述“服务器返回了什么”，body 和解码阶段再各自追加上下文。分层记录后，日志可读、重试可控，错误也不会在包装过程中丢失。

相关问题

非 2xx 状态要不要返回 error？

如果当前函数的契约把 4xx/5xx 视为业务失败，可以返回自定义的 HTTPError；但应明确它来自响应状态，而不是把它误判成网络传输失败。

为什么只 defer Close 还不够？

Close 负责释放响应体；为了更好复用连接，仍应在不需要提前停止时把 body 读到 EOF。遇到读取错误时则保留读取阶段的原始错误。