架构与系统设计 / 系统课时
按 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 契约或服务端结构化错误详情,不能根据错误文本猜测。
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 后执行:
go mod init status-demo
go get google.golang.org/grpc
go run .预期输出:
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,以及尝试次数和退避是否受到全局上限约束。
最实用的规则是让每个失败都回答“谁需要改变什么才能成功”。只有请求本身不变且故障可能自行恢复时,才值得进入重试候选;如果必须修正输入、身份、业务状态、配额或代码,原样重试就应尽快停止。