架构与系统设计 / 系统课时
为可重试方法设计幂等语义
为可重试方法设计幂等语义
显式重试会把“一次调用”变成“可能执行多次”,而客户端收到 UNAVAILABLE、超时等结果并不能证明服务端没有完成写入。本课把可重试方法收紧为可验证的幂等契约:同一业务意图重复到达时,只产生一次副作用,并稳定返回第一次执行的业务结果。
学习目标
- 区分 gRPC 重试能力与业务幂等保证,识别重复执行窗口
- 用请求唯一键、参数摘要和原子约束阻止重复写入
- 为可重试状态码建立与幂等语义一致的验收条件
先把“可重试”定义清楚
启用重试策略后,客户端可能在一次逻辑 RPC 中发起多个调用尝试并重放请求。只要某次尝试已经进入服务端应用逻辑,就存在“服务端已成功、响应却没有到达客户端”的不确定窗口。因此,读操作通常容易满足幂等要求;创建、扣款、发券等写操作则必须额外定义重复请求的处理规则。
真正安全的目标不是“第二次请求不报错”,而是:同一个业务意图无论到达一次还是多次,最终业务副作用都等价于执行一次。对于创建类接口,重复调用还应返回第一次创建出的同一个资源标识,而不是再次创建资源。

用请求唯一键标识一次业务意图
请求唯一键应在第一次调用前由业务调用方生成,并在该业务操作的所有重试中保持不变。它不是“每次网络请求的 ID”,而是“一次业务意图的 ID”。服务端的去重范围至少应包含调用方身份、RPC 方法和请求唯一键,避免不同租户或不同方法之间发生键碰撞。
下面是接口定义片段;它依赖正常的 Protobuf 代码生成流程,不是独立可执行程序。
syntax = "proto3";
package orders.v1;
service OrderService {
rpc CreateOrder(CreateOrderRequest) returns (CreateOrderResponse);
}
message CreateOrderRequest {
string request_id = 1;
string sku = 2;
int32 quantity = 3;
}
message CreateOrderResponse {
string order_id = 1;
}request_id 只解决“如何识别同一次意图”。服务端还应保存请求参数摘要,例如对规范化后的 sku、quantity 计算哈希。同一个键再次出现但摘要不同,说明调用方错误复用了幂等键,应返回明确的非重试错误,而不是把第一次请求的结果套到新的参数上。
服务端去重必须原子化
“先查询是否存在,再执行写入”会留下竞态窗口:两个并发尝试都可能查询到记录不存在,然后分别执行一次副作用。更稳妥的做法是依赖数据库唯一约束原子抢占幂等键,再根据抢占结果决定当前请求是否有资格执行业务逻辑。
以下 PostgreSQL 示例可直接演示原子占位。同一个 scope_key 第一次插入成功,第二次因主键冲突不会再次获得执行资格。
CREATE TEMP TABLE idempotency_claims (
scope_key text PRIMARY KEY,
request_hash text NOT NULL
);
INSERT INTO idempotency_claims(scope_key, request_hash)
VALUES ('user-42|orders.v1.OrderService/CreateOrder|req-7', 'hash-a')
ON CONFLICT DO NOTHING
RETURNING scope_key;
INSERT INTO idempotency_claims(scope_key, request_hash)
VALUES ('user-42|orders.v1.OrderService/CreateOrder|req-7', 'hash-a')
ON CONFLICT DO NOTHING
RETURNING scope_key;预期结果
第一次 INSERT:RETURNING 返回 1 行,INSERT 0 1
第二次 INSERT:RETURNING 返回 0 行,INSERT 0 0生产实现还应保存处理状态和业务结果。首次抢占成功后执行真实业务;成功时记录 SUCCEEDED 与 order_id。重复请求若命中相同参数且状态已成功,就直接返回原结果;若状态仍为 PROCESSING,则按接口契约等待、返回暂不可用状态,或要求客户端稍后使用同一幂等键重试。
让重试状态码服从幂等契约
只有业务语义允许重复尝试时,才应把方法交给自动重试策略。UNAVAILABLE 常用于表示临时不可用,但它对非幂等写操作并不天然安全;客户端看到 DEADLINE_EXCEEDED 也不能据此断定服务端没有完成写入。任何再次尝试都必须复用原请求唯一键,并受同一个端到端时间预算约束。
INVALID_ARGUMENT、FAILED_PRECONDITION 这类需要调用方修正输入或前置状态的问题通常不应自动重试。ABORTED 是否适合重试则取决于业务契约:有些事务冲突可以从更高层重新执行,有些操作必须先重新读取最新状态后才能决定下一步。
验收时至少覆盖一个“提交后丢响应”场景:第一次请求已经成功写入业务数据,但客户端没有收到成功响应,随后使用相同 request_id 再次调用。通过条件是业务表只有一份副作用、重复请求返回相同业务结果,并且同键不同参数会被拒绝。满足这些条件后,gRPC 重试才真正建立在安全的业务语义之上。