服务注册与分布式协调 / 系统课时
设计 Retry Policy 与失败分类
设计 Retry Policy 与失败分类
Retry Policy 的目标不是“失败就多试几次”,而是在可恢复故障上自动等待并重试,同时让无论重试多少次都不会改变结果的业务拒绝尽快失败。设计时要一起考虑退避节奏、总时间预算、最大尝试次数和错误类型,否则重试本身会放大下游故障。
学习目标
- 按暂时故障、间歇故障和永久故障判断 Activity 是否值得重试
- 配置初始间隔、退避系数、最大间隔、最大尝试次数与不可重试错误类型
- 用
ApplicationFailure明确表达业务拒绝,并避免错误包装破坏重试语义
先按恢复可能性分类失败
可重试与否取决于“相同输入稍后再执行,成功概率是否会提高”,而不是错误看起来是否严重。
| 失败类型 | 典型例子 | 建议 |
|---|---|---|
| 暂时故障 | 连接超时、503、短时限流 | 重试,并使用退避降低瞬时压力 |
| 间歇故障 | 偶发网络抖动、依赖节点切换 | 重试,但限制总时间和最大间隔 |
| 永久故障 | 参数非法、余额不足、业务规则拒绝 | 不重试,立即把失败交给 Workflow 决策 |
业务拒绝通常需要改变输入、人工处理或执行补偿,原样重试只会重复消耗资源。相反,503 或连接失败可能在数秒后恢复,适合交给 Activity 的 Retry Policy 自动处理。
把重试参数变成压力预算
initialInterval 决定第一次失败后等待多久,backoffCoefficient 决定间隔如何放大,maximumInterval 给退避设置上限,maximumAttempts 限制尝试次数。比如初始 2 秒、系数 2、最大 20 秒时,等待序列会近似为 2、4、8、16、20 秒,之后不再继续指数增长。
不要只靠 maximumAttempts 控制重试。更稳妥的方式是让 Schedule-To-Close 约束整个 Activity Execution 的总时间,再用尝试次数作为额外护栏。这样即使单次执行时间或退避发生变化,重试链也不会无限占用业务时限。

配置 Retry Policy
下面是片段示例,依赖项目中已注册的 activities.ts。支付调用的单次尝试最多 15 秒,整个执行最多 2 分钟;暂时故障最多尝试 5 次,而 BusinessRejected 和 InvalidRequest 一旦出现就不进入下一次尝试。
import { proxyActivities } from '@temporalio/workflow';
import type * as activities from './activities';
export const { chargePayment } = proxyActivities<typeof activities>({
startToCloseTimeout: '15s',
scheduleToCloseTimeout: '2m',
retry: {
initialInterval: '2s',
backoffCoefficient: 2,
maximumInterval: '20s',
maximumAttempts: 5,
nonRetryableErrorTypes: ['BusinessRejected', 'InvalidRequest'],
},
});生效行为是:普通可重试失败会按退避节奏再次调度;当 ApplicationFailure.type 命中不可重试列表时立即结束 Activity Execution;即使尝试次数尚未用完,达到 Schedule-To-Close 总时限也会停止继续重试。
用 ApplicationFailure 表达业务拒绝
Activity 实现应该把业务语义编码为稳定的错误类型,而不是让 Workflow 解析错误字符串。下面的片段把 422 类业务拒绝转换成 BusinessRejected,而 503 仍抛出普通错误,让 Retry Policy 处理。
import { ApplicationFailure } from '@temporalio/common';
export async function chargePayment(
amount: number,
responseStatus: number,
): Promise<string> {
if (responseStatus === 422) {
throw ApplicationFailure.create({
message: `payment rejected for amount ${amount}`,
type: 'BusinessRejected',
details: [amount],
});
}
if (responseStatus === 503) {
throw new Error('payment service temporarily unavailable');
}
return `charged:${amount}`;
}预期结果是 responseStatus 为 422 时,错误类型命中 nonRetryableErrorTypes,不会安排下一次尝试;为 503 时,该普通错误会被 Activity 失败转换机制视为可重试失败,并在总时限和 Retry Policy 允许的范围内继续尝试;其他状态返回成功结果。
如果某个错误由 Activity 实现者就能确定“任何调用方都不应该重试”,还可以在 ApplicationFailure.create() 中设置 nonRetryable: true。这种标记会直接阻止重试,不再依赖调用方是否把该类型加入列表。
最终验收应同时覆盖两个路径:一个暂时故障确实产生退避后的后续尝试,一个永久业务拒绝只执行一次。只有“该重试的会恢复、不该重试的立即停”同时成立,Retry Policy 才真正减少故障而不是制造重试风暴。