Spring Retryable 注解测试失败的常见原因与正确实践

日期：2026-01-07 00:00 / 作者：碧海醫心

本文详解 spring `@retryable` 注解在单元测试中失效的典型原因，重点剖析代理机制限制、测试配置误区及 ide 干扰问题，并提供可立即验证的完整测试方案。

Spring 的 @Retryable 是一个强大且常用的声明式重试机制，但其底层依赖 Spring AOP 代理（默认为 JDK 动态代理或 CGLIB），这导致它仅对通过 Spring 容器注入的 Bean 调用生效——即必须满足“外部 Bean 调用目标 Bean 的 @Retryable 方法”这一前提。若直接在测试类中 new 实例、或通过非代理对象调用（如 this.accessorMethod()），重试逻辑将完全被绕过。

你当前的测试结构看似合理，但存在几个关键隐患：

✅ 正
确配置的必要条件

@EnableRetry 必须作用于 Spring 配置类（而非测试类）
将 @EnableRetry 移至 test-config.xml 对应的 Java 配置类（如 TestConfig.java）中，或在 XML 中显式启用：
@Retryable 方法所在类必须由 Spring 管理（@Service/@Component）
确保 MyAccessor 是 Spring Bean（例如添加 @Component），且 myService 和 myAccessor 均通过 @Autowired 注入，而非手动 new。

⚠️ 测试代码中的典型错误

你的测试方法中：

@Test
public void serviceMethodRetryTest() {
    try {
        this.myService.serviceMethod(this.parameter); // ✅ 正确：通过代理 Bean 调用
    } catch (UncategorizedSQLException exception) {
        log.error("Error while executing test: {}", exception.getMessage());
    }
}

表面看符合要求，但实际可能因以下原因失败：

异常未被 @Retryable 捕获：@Retryable(include = {...}) 仅对指定异常类型触发重试。若抛出的是 SQLException 的子类（如 SQLTimeoutException），而该子类未被 include 显式包含，重试将跳过。
maxAttemptsExpression 解析失败：确保 retry.maxAttempts 在 application-test.properties 或 test-config.xml 中正确定义（如），否则默认为 3，但表达式解析失败会导致降级为无重试。

? 推荐的可验证测试方案

@SpringBootTest(classes = {TestConfig.class})
@Import(TestRetryConfiguration.class)
class MyServiceTest {

    @Autowired
    private MyService myService;

    @MockBean
    private MyAccessor myAccessor; // 关键：Mock 出问题并控制行为

    @Test
    void serviceMethodRetryTest() {
        // 模拟 accessorMethod 连续 2 次抛出 SQLException，第 3 次成功
        given(myAccessor.accessorMethod("test"))
            .willThrow(new SQLException("DB timeout"))  // 第1次
            .willThrow(new SQLException("DB timeout"))  // 第2次
            .willReturn("success");                     // 第3次

        String result = myService.serviceMethod("test");

        assertThat(result).isEqualTo("success");
        // 验证重试次数（需自定义 RetryListener 记录调用）
        verify(myAccessor, times(3)).accessorMethod("test");
    }
}

? 核心注意事项

IDE 缓存干扰：如答案所述，某些 IDE（IntelliJ IDEA）在运行测试时可能未刷新代理类或使用了旧的字节码缓存。务必执行 Build → Rebuild Project 并清除 IDE 缓存（File → Invalidate Caches and Restart）。
不要在 @Retryable 方法内 catch 并吞掉异常：你代码中 catch (final Exception exception) { return null; } 会阻止异常向上抛出，导致 @Retryable 完全无法感知失败——重试只响应抛出的异常，不响应返回值。
启用日志观察重试过程：添加 logging.level.org.springframework.retry=DEBUG，可清晰看到 Retry: count=1, Retry: count=2 等日志。

✅ 总结