Golang处理API错误的实用方法

Go处理外部API错误的关键在于摒弃“捕获panic”的思维，转而通过主动检查error、精准分层（网络层如net.Error的Temporary/Timeout判断、HTTP状态码异常、JSON解析失败等业务层问题）并为每一类错误设计差异化的应对策略——比如对超时或临时网络错误重试，对401/403做鉴权刷新，对5xx记录告警而非盲目重试，对JSON解析失败则校验Content-Type、记录原始响应、采用宽松结构体或json.RawMessage延迟解析；同时必须禁用DefaultClient，为不同服务配置独立的http.Client与精细化调优的Transport，才能真正构建出健壮、可观测、可维护的外部依赖调用体系。

直接说结论：Go 处理外部 API 错误，核心不是“捕获 panic”，而是主动检查 error、区分网络层与业务层错误、并为每类错误设计明确的 fallback 或重试策略。

HTTP 请求返回非 2xx 状态码时，http.Client.Do 不会返回 error

这是最常踩的坑：很多人以为 resp, err := client.Do(req) 中的 err 覆盖了所有失败场景，其实它只反映底层连接、超时、TLS 握手等网络问题。HTTP 状态码如 400、401、503 都会正常返回 *http.Response，且 err == nil。

• 必须手动检查 resp.StatusCode，例如：if resp.StatusCode = 300
• 别忘了调用 resp.Body.Close()，否则连接不会复用，容易触发 too many open files
• 建议封装一个 checkStatus(resp *http.Response) 辅助函数，统一处理常见状态码（如把 401 转成自定义 ErrUnauthorized）

超时、连接拒绝、DNS 失败等网络错误，要归到 net.Error 分类处理

这类错误来自底层系统调用，类型是 net.OpError（实现了 net.Error 接口），特点是可判断是否临时性（Temporary()）或超时（Timeout()），这对重试逻辑至关重要。

• 用类型断言识别：if netErr, ok := err.(net.Error); ok && netErr.Timeout() { ... }
• context.WithTimeout 是更推荐的方式——把超时控制交给 context，而不是依赖 http.Client.Timeout 字段（后者无法中断 DNS 解析等阻塞操作）
• 注意：某些代理或中间件可能把网络错误伪装成 HTTP 5xx 响应，需结合日志和监控交叉验证

JSON 解析失败（json.Unmarshal error）往往暴露 API 契约变更

当服务端字段类型变化（比如字符串变数字）、新增必填字段、或返回了未文档化的错误体（如 Nginx 的 HTML 错误页），json.Unmarshal 就会失败。这类错误不是网络问题，也不能简单重试。

• 永远先检查 resp.Header.Get("Content-Type") 是否包含 application/json，避免对 text/html 或空响应体强行解码
• 用 json.RawMessage 延迟解析关键字段，或定义宽松结构体（如字段全为指针或 interface{}），再按需校验
• 记录原始响应体（截断前 512 字节）到日志，比只记 json: cannot unmarshal string into Go struct 有用得多

不要用全局 http.DefaultClient，为不同 API 设置独立 client 实例

共享 http.DefaultClient 会导致超时、重定向、Transport 配置互相干扰；更隐蔽的问题是：某个不守规矩的第三方 SDK 可能偷偷修改它的 Transport，导致你的请求行为异常。

• 为每个外部服务新建 client：paymentClient := &http.Client{Timeout: 5 * time.Second, Transport: trans}
• 自定义 http.Transport 时，务必设置 MaxIdleConns 和 MaxIdleConnsPerHost，否则默认 100 会吃光连接池
• 如果需要注入 trace ID 或 auth token，用中间件函数包装 RoundTrip，而不是在每次请求前改写 req.Header

真正难的不是写 if err != nil，而是搞清这个 err 到底属于哪一层——是 DNS 没查到？TCP 连不上？TLS 握手失败？HTTP 状态码异常？还是 JSON 字段缺失？每一层对应的恢复动作都不同。漏掉一层分类，就可能把本该告警的 503 当成可重试的临时错误来循环调用。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Golang处理API错误的实用方法》文章吧，也可关注golang学习网公众号了解相关技术文章。