🎯 今日核心问题

  1. 同一个 Retry 注解套在查询和退款上,为什么会把一次失败放大成三次事故?
  2. 超时到底算成功还是失败?读超时和连接超时该怎么区别处理?
  3. Resilience4j 的 Retry 和 CircuitBreaker 在 Agent 循环里怎么组合,顺序错了会怎样?

📖 精读提纲

【一】先给工具贴标签,再谈重试

重试的前提是「操作幂等」。所以第一步不是配参数,是给每个工具打上一张分类卡:

这张分类卡必须写进 ToolSpec,而不是靠人记。注解写在方法上是不够的,因为 Agent 是通过动态调度调工具的,注解很容易被反射路径绕过——这一点在第2周的工具注册表上就要补字段。

【二】超时是「结果未知」,不是「失败」

这是线上事故最常见的一个误解。连接超时(ConnectTimeout)意味着请求根本没发出去,可以安全重试;读超时(ReadTimeout)意味着请求已经到达对方、对方可能已经执行,只是响应没回来,此时结果未知。对非幂等写操作,读超时应该转入「查证流程」:用业务流水号去查对方状态,查到已执行就返回成功,查不到再决定是否补发。

工程上要保证每个非幂等写操作都带一个业务流水号(traceId 或自生成的 bizNo),否则你连查证都做不到。这条要求要写进工具契约,不是可选项。

【三】Resilience4j 的组合顺序

装饰顺序决定了语义。推荐顺序是 Retry( CircuitBreaker( TimeLimiter( Bulkhead( 实际调用 ) ) ) ):重试在最外层,每次重试都重新经过熔断器判断,熔断器打开时重试会立刻失败而不是持续打过去。反过来把 Retry 放在内层,熔断器看到的是「一整串重试」作为一个调用,计数会失真,而且熔断打开后重试仍然会在内部打满次数。

还要注意 TimeLimiter 必须用异步才有意义(Supplier<CompletionStage>),对同步阻塞方法它只能靠中断,而多数 HTTP 客户端不响应中断。真正有效的超时是客户端自己的 connect/read timeout,Resilience4j 的 TimeLimiter 是兜底不是主力。

【四】常见误区

💻 代码示例

工具级别声明副作用等级,统一由执行器决定是否重试。

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 怎么用唯一索引兜底,以及「模型自己生成了两次相同意图」这种更隐蔽的重复。