🎯 今日核心问题
- 同一个
Retry注解套在查询和退款上,为什么会把一次失败放大成三次事故? - 超时到底算成功还是失败?读超时和连接超时该怎么区别处理?
- Resilience4j 的 Retry 和 CircuitBreaker 在 Agent 循环里怎么组合,顺序错了会怎样?
📖 精读提纲
【一】先给工具贴标签,再谈重试
重试的前提是「操作幂等」。所以第一步不是配参数,是给每个工具打上一张分类卡:
- 纯读、幂等(查订单、查物流、查知识库):可重试,指数退避,3 次以内。
- 写、天然幂等(按主键 upsert、置状态为 CANCELLED 这类「结果唯一」的操作):可重试,但必须带幂等键,见明天。
- 写、非幂等(发券、退款、发短信、创建工单):绝不自动重试。第一次超时不代表没执行,重试就是二次发券。
- 外部不可逆(调用第三方支付、物理下发):不重试,只能查证。
这张分类卡必须写进 ToolSpec,而不是靠人记。注解写在方法上是不够的,因为 Agent 是通过动态调度调工具的,注解很容易被反射路径绕过——这一点在第2周的工具注册表上就要补字段。
【二】超时是「结果未知」,不是「失败」
这是线上事故最常见的一个误解。连接超时(ConnectTimeout)意味着请求根本没发出去,可以安全重试;读超时(ReadTimeout)意味着请求已经到达对方、对方可能已经执行,只是响应没回来,此时结果未知。对非幂等写操作,读超时应该转入「查证流程」:用业务流水号去查对方状态,查到已执行就返回成功,查不到再决定是否补发。
工程上要保证每个非幂等写操作都带一个业务流水号(traceId 或自生成的 bizNo),否则你连查证都做不到。这条要求要写进工具契约,不是可选项。
【三】Resilience4j 的组合顺序
装饰顺序决定了语义。推荐顺序是 Retry( CircuitBreaker( TimeLimiter( Bulkhead( 实际调用 ) ) ) ):重试在最外层,每次重试都重新经过熔断器判断,熔断器打开时重试会立刻失败而不是持续打过去。反过来把 Retry 放在内层,熔断器看到的是「一整串重试」作为一个调用,计数会失真,而且熔断打开后重试仍然会在内部打满次数。
还要注意 TimeLimiter 必须用异步才有意义(Supplier<CompletionStage>),对同步阻塞方法它只能靠中断,而多数 HTTP 客户端不响应中断。真正有效的超时是客户端自己的 connect/read timeout,Resilience4j 的 TimeLimiter 是兜底不是主力。
【四】常见误区
- ❌ 对 4xx 重试。400/422 是你参数错了,重试一百次也一样;只对 429、5xx、连接异常重试。
- ❌ 固定间隔重试。三个 Agent 同时重试会把下游打穿,必须加 jitter(如 200ms ± 50%)。
- ❌ 把重试次数交给模型决定。模型会说「再试一次」,然后在同一轮里无限循环,实际是它自己在重试自己。
- ❌ 忽略「重试放大」:ReAct 每次循环都会重发全部历史,一次工具重试 3 次 = 3 倍 token + 3 倍延迟,超时预算要按最坏情况算。
💻 代码示例
工具级别声明副作用等级,统一由执行器决定是否重试。
public enum SideEffect { READ_ONLY, IDEMPOTENT_WRITE, NON_IDEMPOTENT_WRITE, IRREVERSIBLE }
public record ToolSpec(String name, Object target, Method method, SideEffect sideEffect) {
public boolean retryable() {
return sideEffect == SideEffect.READ_ONLY || sideEffect == SideEffect.IDEMPOTENT_WRITE;
}
}
Resilience4j 组合:重试只对可重试工具生效,且只针对幂等异常。
@Configuration
public class ResilienceConfig {
@Bean
public Retry agentRetry() {
RetryConfig c = RetryConfig.custom()
.maxAttempts(3)
.intervalFunction(IntervalFunction.ofExponentialRandomBackoff(
Duration.ofMillis(200), 2.0, 0.5))
.retryOnException(e -> isRetryable(e))
.ignoreExceptions(IllegalArgumentException.class,
BusinessRuleException.class,
NonRetryableToolException.class)
.failAfterMaxAttempts(true)
.build();
return Retry.of("agentTool", c);
}
private static boolean isRetryable(Throwable e) {
if (e instanceof java.net.ConnectException) return true; // 请求没出去
if (e instanceof java.net.http.HttpTimeoutException) return false; // 读超时:结果未知
if (e instanceof WebClientResponseException w) {
int s = w.getStatusCode().value();
return s == 429 || s >= 500;
}
return false;
}
@Bean
public CircuitBreaker agentBreaker() {
return CircuitBreaker.of("agentTool", CircuitBreakerConfig.custom()
.slidingWindowType(CircuitBreakerConfig.SlidingWindowType.COUNT_BASED)
.slidingWindowSize(20)
.minimumNumberOfCalls(10)
.failureRateThreshold(50f)
.waitDurationInOpenState(Duration.ofSeconds(30))
.permittedNumberOfCallsInHalfOpenState(3)
.build());
}
}
执行器把三件事绑在一起:分类、重试、读超时后的查证。
@Service
@RequiredArgsConstructor
public class ToolExecutor {
private final Retry retry;
private final CircuitBreaker breaker;
private final ToolRegistry registry;
public ToolResult execute(String tool, String args, String bizNo) {
ToolSpec spec = registry.spec(tool);
Supplier<ToolResult> call = () -> new ToolResult(registry.invoke(tool, args));
try {
if (spec.retryable()) {
return Decorators.ofSupplier(call).withCircuitBreaker(breaker).withRetry(retry).get();
}
// 非幂等:只走熔断,不重试;读超时转查证
return Decorators.ofSupplier(call).withCircuitBreaker(breaker).get();
} catch (Exception e) {
if (!spec.retryable() && isUnknownOutcome(e)) {
return ToolResult.reconcile(queryStatus(tool, bizNo));
}
return ToolResult.error(e);
}
}
private boolean isUnknownOutcome(Exception e) {
return e instanceof java.net.http.HttpTimeoutException
|| e instanceof java.io.IOException && !(e instanceof java.net.ConnectException);
}
private String queryStatus(String tool, String bizNo) {
return "UNKNOWN: 结果未确认,请用 bizNo=" + bizNo + " 查询后再决定是否重发,禁止直接重试";
}
}
✏️ 今日动手
把 createCompensation 和 queryLogistics 分别接上执行器:① mock 下游返回 500,确认查询工具重试 3 次、补偿工具只调 1 次;② mock 读超时(Thread.sleep 超过 readTimeout),确认补偿工具走的是查证路径且 Observation 里带 UNKNOWN;③ 用 Thread.sleep 让下游连续失败 10 次,观察熔断器在第几次打开、打开后 ReAct 循环的轮次是否立刻终止。
🔖 明日预告
今天说「幂等写可重试」,但幂等不是天上掉的。明天讲怎么造幂等键、去重表怎么设计、并发同 key 怎么用唯一索引兜底,以及「模型自己生成了两次相同意图」这种更隐蔽的重复。