Go / 系统课时

分类下游调用错误

分类下游调用错误

下游调用失败后,真正困难的不是打印 err,而是判断它属于取消、超时、连接故障还是 HTTP 业务错误。Go 的网络错误通常经过多层包装,因此应优先用 errors.Is 和 errors.As 分类,再结合响应状态码决定重试、降级或直接返回。

学习目标

  • 用 errors.Is 识别调用取消与 deadline 到期,用 errors.As 识别网络超时。
  • 正确区分“请求发送失败”和“收到非 2xx HTTP 响应”。
  • 根据错误类型、请求幂等性和剩余预算选择重试、降级或直接失败。

先区分传输错误与 HTTP 错误

http.Client.Do 返回非空 err,表示请求在发送、重定向或读取响应头等过程中失败;常见原因包括取消、超时、DNS、连接被拒绝或 TLS 问题。此时错误经常被 *url.Error 包装,不应依赖字符串匹配。

收到 404、429、503 等 HTTP 状态时,Do 通常仍然返回 err == nil,因为 HTTP 交换本身已经成功。是否把这个状态视为业务失败,需要应用根据 resp.StatusCode 判断,并在处理完成后关闭响应体。

下游 HTTP 调用错误分类决策流程

用标准错误链做分类

分类顺序应先处理语义最明确的错误,再落到宽泛的网络错误。errors.Is 能穿透包装识别 context.Canceled 和 context.DeadlineExceeded;errors.As 则可以找到实现了 net.Error 的底层错误,并读取 Timeout()。

下面的程序构造取消、客户端超时、503、404 和连接关闭五种情况,并把它们归为稳定的错误类别。

go
package main

import (
    "context"
    "errors"
    "fmt"
    "net"
    "net/http"
    "net/http/httptest"
    "time"
)

type kind string

const (
    ok            kind = "ok"
    canceled      kind = "canceled"
    timeout       kind = "timeout"
    network       kind = "network"
    httpRetryable kind = "http_retryable"
    httpPermanent kind = "http_permanent"
)

func classify(resp *http.Response, err error) kind {
    if err != nil {
        switch {
        case errors.Is(err, context.Canceled):
            return canceled
        case errors.Is(err, context.DeadlineExceeded):
            return timeout
        }

        var netErr net.Error
        if errors.As(err, &netErr) && netErr.Timeout() {
            return timeout
        }
        return network
    }

    if resp.StatusCode >= 200 && resp.StatusCode < 300 {
        return ok
    }

    switch resp.StatusCode {
    case http.StatusTooManyRequests,
        http.StatusBadGateway,
        http.StatusServiceUnavailable,
        http.StatusGatewayTimeout:
        return httpRetryable
    default:
        return httpPermanent
    }
}

func call(client *http.Client, ctx context.Context, rawURL string) kind {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
    if err != nil {
        panic(err)
    }

    resp, err := client.Do(req)
    if resp != nil {
        defer resp.Body.Close()
    }
    return classify(resp, err)
}

func main() {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        switch r.URL.Path {
        case "/slow":
            time.Sleep(100 * time.Millisecond)
            fmt.Fprintln(w, "ok")
        case "/busy":
            http.Error(w, "try later", http.StatusServiceUnavailable)
        case "/missing":
            http.NotFound(w, r)
        default:
            fmt.Fprintln(w, "ok")
        }
    }))

    client := &http.Client{Timeout: 40 * time.Millisecond}

    ctx, cancel := context.WithCancel(context.Background())
    cancel()
    fmt.Println("canceled:", call(client, ctx, server.URL+"/ok"))
    fmt.Println("slow:", call(client, context.Background(), server.URL+"/slow"))
    fmt.Println("busy:", call(client, context.Background(), server.URL+"/busy"))
    fmt.Println("missing:", call(client, context.Background(), server.URL+"/missing"))

    // 关闭监听后再次访问,稳定制造连接层失败。
    baseURL := server.URL
    server.Close()
    fmt.Println("closed:", call(client, context.Background(), baseURL))
}

预期输出

text
canceled: canceled
slow: timeout
busy: http_retryable
missing: http_permanent
closed: network

这里没有比较具体错误文本,因此不会依赖 *url.Error 或 *net.OpError 的格式。如果还需要区分 DNS、连接拒绝等更细原因,可以继续用 errors.As 提取 *net.OpError,而不是解析 err.Error()。

把分类结果映射为动作

取消通常表示调用者已经放弃请求,应立即停止,不要重试。deadline 到期也通常不应在原请求内继续重试,因为剩余预算已经不足;若系统存在更高层重试机制,应由更高层重新计算预算。

网络故障和超时只有在请求具备幂等性、请求体可重放且剩余预算允许时才考虑重试。GET、HEAD 等通常更适合自动重试;会产生副作用的 POST 应依赖业务幂等键或明确的接口契约,不能因为“没收到响应”就假设服务端一定没有执行。

HTTP 状态也不能简单按“4xx 永不重试、5xx 全部重试”处理。429 应尊重服务端限流语义和可能存在的 Retry-After;502、503、504 常可在预算内退避重试;400、401、403、404 多数需要直接修正请求或返回上游。500 是否重试要看接口契约和故障模式,盲目重试可能放大故障。

降级前保留可观察信息

分类后应记录稳定字段,例如目标服务、请求方法、错误类别、状态码和重试次数,而不是把整个错误字符串当作分类依据。对于 HTTP 错误,可在限制长度后读取少量响应体用于诊断;不要无上限地把下游错误页写入日志或原样返回给上游。

最终的错误处理顺序可以保持简单:先用错误链判断取消与网络失败,再在成功收到响应时判断状态码,最后结合幂等性与剩余预算决定动作。这样分类规则可测试、可观测,也不会把“HTTP 返回失败状态”和“根本没有拿到 HTTP 响应”混为一谈。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

分类下游调用错误

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通