架构与系统设计 / 系统课时

按 gRPC Status Code 分类失败

按 gRPC Status Code 分类失败

这节建立一套可落地的 gRPC 失败分类规则:先从 Status Code 判断失败语义,再结合幂等性、剩余 Deadline 和服务端提供的可信信号决定返回、修正请求、退避重试或告警,避免把所有非 OK 响应都塞进统一重试器。

学习目标

  • 根据 gRPC Status Code 判断调用方应修正、返回、重试还是告警
  • 区分 UNAVAILABLE、RESOURCE_EXHAUSTED、ABORTED 与 DEADLINE_EXCEEDED 的重试边界
  • 为业务拒绝选择准确的 canonical code,避免错误触发基础设施重试

先按调用方动作分类

状态码不是严重程度等级,而是失败语义。真正有用的问题是:调用方需要改变什么才能成功,以及原样重试是否可能重复副作用。

处理方式 常见状态码 默认动作
修正请求或身份 INVALID_ARGUMENT、UNAUTHENTICATED、PERMISSION_DENIED 不原样重试
等业务状态改变 FAILED_PRECONDITION、NOT_FOUND、ALREADY_EXISTS、OUT_OF_RANGE 由业务流程决定
暂时性故障 UNAVAILABLE、部分 RESOURCE_EXHAUSTED 满足条件时退避重试
并发冲突 ABORTED 重做更高层事务或读改写流程
时间或调用方终止 DEADLINE_EXCEEDED、CANCELLED 检查预算或停止
服务端缺陷或数据损坏 INTERNAL、DATA_LOSS、通常的 UNKNOWN 优先告警和定位
服务不支持 UNIMPLEMENTED 修正版本或调用路径

RESOURCE_EXHAUSTED 不能只看状态码决定重试。它既可能表示短时过载,也可能表示硬配额、账户额度或容量上限耗尽;只有服务契约或结构化错误详情明确说明属于可恢复的瞬时限制时,客户端才应把它加入重试候选。UNAVAILABLE 也不是无条件重试许可,非幂等写操作仍要先解决重复执行问题。

用代码固化分类规则

下面的 Go 示例故意把 RESOURCE_EXHAUSTED 的额外上下文作为输入,而不是把它无条件归为 RetryWithBackoff。生产代码中的这一信号应来自明确的 API 契约或服务端结构化错误详情,不能根据错误文本猜测。

go
package main

import (
    "fmt"

    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"
)

type Action string

const (
    ReturnImmediately Action = "return_immediately"
    RetryWithBackoff  Action = "retry_with_backoff"
    RetryHigherLevel  Action = "retry_higher_level_operation"
    DoNotBlindRetry   Action = "do_not_blind_retry"
)

type RetryContext struct {
    // 仅在服务契约明确确认属于瞬时资源压力时设置。
    ResourceExhaustedTransient bool
}

func classify(code codes.Code, ctx RetryContext) Action {
    switch code {
    case codes.Unavailable:
        return RetryWithBackoff
    case codes.ResourceExhausted:
        // 硬配额耗尽不会因立即重试而恢复,因此必须单独处理。
        if ctx.ResourceExhaustedTransient {
            return RetryWithBackoff
        }
        return DoNotBlindRetry
    case codes.Aborted:
        return RetryHigherLevel
    case codes.DeadlineExceeded:
        // Deadline 到期不能证明服务端没有完成有副作用的操作。
        return DoNotBlindRetry
    default:
        return ReturnImmediately
    }
}

func main() {
    cases := []struct {
        err error
        ctx RetryContext
    }{
        {status.Error(codes.Unavailable, "backend restarting"), RetryContext{}},
        {status.Error(codes.InvalidArgument, "page_size must be positive"), RetryContext{}},
        {status.Error(codes.ResourceExhausted, "temporary overload"), RetryContext{ResourceExhaustedTransient: true}},
        {status.Error(codes.ResourceExhausted, "quota exceeded"), RetryContext{}},
        {status.Error(codes.Aborted, "concurrent update"), RetryContext{}},
        {status.Error(codes.DeadlineExceeded, "deadline exceeded"), RetryContext{}},
    }

    for _, c := range cases {
        st := status.Convert(c.err)
        fmt.Printf("%s (%s) -> %s\n", st.Code(), st.Message(), classify(st.Code(), c.ctx))
    }
}

保存为 main.go 后执行:

bash
go mod init status-demo
go get google.golang.org/grpc
go run .

预期输出:

text
Unavailable (backend restarting) -> retry_with_backoff
InvalidArgument (page_size must be positive) -> return_immediately
ResourceExhausted (temporary overload) -> retry_with_backoff
ResourceExhausted (quota exceeded) -> do_not_blind_retry
Aborted (concurrent update) -> retry_higher_level_operation
DeadlineExceeded (deadline exceeded) -> do_not_blind_retry

同一个 RESOURCE_EXHAUSTED 因上下文不同进入了两个分支:瞬时过载可以成为退避重试候选,硬配额耗尽则必须先改变配额或资源条件。这能避免客户端把不可恢复的限制放大成持续重试流量。

区分几个容易误判的状态码

ABORTED 通常表示并发控制使本次操作失效,例如事务冲突或乐观锁竞争。正确动作往往不是只重发最后一个 RPC,而是重新执行完整的“读取当前状态、计算变更、提交”流程。

FAILED_PRECONDITION 表示系统当前状态不满足操作前提,例如资源尚未初始化。它与 ABORTED 的关键区别是:前者通常需要某个外部状态先改变,后者通常允许调用方从更高层重新开始竞争。

DEADLINE_EXCEEDED 只说明调用方没有在 Deadline 前拿到结果,并不证明服务端没有完成操作。只读、幂等或有幂等键保护的 RPC,可以在新的整体预算内考虑再次调用;创建、扣款、发送消息等无去重保护的写操作不能因此直接重发。

业务错误不要伪装成基础设施故障

业务拒绝仍可通过 gRPC Status 表达,但 canonical code 应描述真实语义。参数非法用 INVALID_ARGUMENT,资源不存在用 NOT_FOUND,当前状态不允许操作可用 FAILED_PRECONDITION。不要为了让客户端“以后再试”就把支付拒绝、优惠券过期之类结果包装成 UNAVAILABLE 或 INTERNAL。

如果客户端还需要机器可读的业务原因,可以在合适的 canonical code 之外增加结构化错误详情。这样业务逻辑能读取细粒度原因,而重试器、指标和告警仍可把 UNAVAILABLE、INTERNAL 等状态码当成可靠性信号。

重试决策还要过三道门

状态码只能提供第一层判断。真正执行重试前,还要同时确认 RPC 是否具备幂等性或去重保护、调用链是否还有足够 Deadline,以及尝试次数和退避是否受到全局上限约束。

最实用的规则是让每个失败都回答“谁需要改变什么才能成功”。只有请求本身不变且故障可能自行恢复时,才值得进入重试候选;如果必须修正输入、身份、业务状态、配额或代码,原样重试就应尽快停止。

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

目录与阅读设置

阅读设置

17

记录一个想法

按 gRPC Status Code 分类失败

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

登录哪都通