服务调用偶发超时,开发者常把重试写在 catch 中;高峰时数据库连接池被打满,又临时用 Semaphore 控制并发。Spring Framework 7 在核心框架中提供了 @Retryable、@ConcurrencyLimit 与 RetryTemplate,但"有重试注解"不等于"服务具备完整韧性"。本文从代理执行、尝试次数、事务边界和故障注入讲清适用范围,并回答它们与 Spring Retry、Resilience4j 的关系。
技术栈:Java 17+、Spring Framework 7.0.x、JUnit 5;使用 Spring Boot 时需选择实际引入 Spring Framework 7 的兼容版本(例如 Boot 4 系列),不能直接在 Boot 3.5 中照搬。
一、为什么这次值得关注?
Spring Framework 7.0 引入原生的 resilience 支持,包含方法级重试与并发限制。它让一部分轻量、同步、基于 Spring Bean 代理的容错场景不必额外引入第三方重试框架。
但要先厘清四个问题:
- 重试是在第一次失败之后再试,还是最多执行三次?
- 失败发生在事务提交之前还是之后,重复执行是否安全?
- 并发限制是"拒绝新请求"还是"等待许可",能否跨多个 Pod 生效?
- 熔断、超时、退避抖动、降级和重试预算是否也包含在这两个注解里?
如果没有回答这些问题,最容易出现的不是"重试不起作用",而是重试风暴:一个调用链的每一层都重试三次,实际下游请求被指数放大。
1.1 版本边界:不是所有 Spring Boot 都支持
| 组合 | 是否能直接使用 Spring Framework 7 注解 |
|---|---|
| Spring Boot 3.5 + Spring Framework 6.2 | 否;不是这套 API |
| Spring Boot 4 + Spring Framework 7 | 可按对应兼容版本集成 |
| 纯 Spring Framework 7.0 | 可以,需启用注解处理 |
Spring Retry 项目的旧 @Retryable |
不同包、不同 API,不应混淆 |
Spring Framework 7 使用的注解包是 org.springframework.resilience.annotation。Spring Retry 的传统注解是 org.springframework.retry.annotation,不要根据类名相同就直接复制旧配置。
1.2 与以前的 Spring Retry 有什么关系?
Spring Framework 7 的核心特性覆盖常见方法重试和并发限制,但并不意味着原有 Spring Retry 项目在所有复杂场景都可被等价替换。迁移时应逐一核对异常分类、退避策略、恢复回调、状态重试、指标与代理顺序,不能把注解包名改掉就视为升级完成。
二、先弄清重试次数:maxRetries 不是总调用次数
官方文档说明,@Retryable 默认最多额外重试 3 次,因此初次调用加上重试,最多可能执行 4 次。默认重试间隔为 1 秒;真实调用次数还取决于哪次成功、异常是否符合重试条件。
| maxRetries | 初始执行 | 最多额外重试 | 最多总尝试 |
|---|---|---|---|
| 0 | 1 | 0 | 1 |
| 1 | 1 | 1 | 2 |
| 2 | 1 | 2 | 3 |
| 3 | 1 | 3 | 4 |
重要区别: "最多尝试 3 次"与"最多重试 3 次"不是同一句话。预算、日志和告警要用统一口径。
2.1 一个可注入失败的服务
java
import java.util.concurrent.atomic.AtomicInteger;
import org.springframework.resilience.annotation.Retryable;
import org.springframework.stereotype.Service;
@Service
public class InventoryRemoteClient {
private final AtomicInteger attempts = new AtomicInteger();
@Retryable(includes = TransientRemoteException.class, maxRetries = 2)
public String fetchStock() {
int n = attempts.incrementAndGet();
if (n <= 2) {
throw new TransientRemoteException("temporary failure " + n);
}
return "stock=8";
}
public int attempts() {
return attempts.get();
}
}
class TransientRemoteException extends RuntimeException {
TransientRemoteException(String message) {
super(message);
}
}
这段代码用内存计数器模拟"前两次失败、第三次成功",仅用于验证代理重试。它不连接真实库存服务,不应被描述为生产压测结果。
预期结果: 在启用 resilience 代理后,通过 Spring 容器获取 InventoryRemoteClient 并调用 fetchStock(),返回 stock=8,attempts() 为 3。若直接 new InventoryRemoteClient(),方法没有经过代理,第一次就会抛异常。
2.2 启用注解处理
java
import org.springframework.context.annotation.Configuration;
import org.springframework.resilience.annotation.EnableResilientMethods;
@Configuration
@EnableResilientMethods
public class ResilienceConfiguration {
}
官方提供 @EnableResilientMethods,启用重试和并发限制的处理。不要误以为只在方法上贴注解就必然生效;还要检查 Bean 是否由 Spring 管理、代理是否被实际调用、是否发生自调用。
2.3 单元测试和 Spring 集成测试不是一回事
只对目标类直接执行 JUnit 测试,无法验证代理是否拦截方法。应启动 Spring 测试上下文:
java
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
@SpringBootTest
class InventoryRemoteClientTest {
@Autowired
InventoryRemoteClient client;
@Test
void retriesTwiceThenSucceeds() {
assertEquals("stock=8", client.fetchStock());
assertEquals(3, client.attempts());
}
}
这里的测试示例假定应用采用兼容的 Spring Boot 4 测试依赖,且没有其他测试提前调用同一个单例计数器。更稳妥的项目测试应在每个用例使用独立上下文或重置可变测试状态,避免用例顺序依赖。以上是预期断言,并未实际运行。
三、只重试临时错误,不要重试所有异常
对业务校验失败、认证失败、参数非法和永久不存在的资源,重试往往没有意义;对短暂网络抖动、可识别的 503 或特定数据库瞬时错误,才可能值得重试。
java
@Retryable(
includes = TransientRemoteException.class,
maxRetries = 2
)
public String load() {
return remoteApi.fetch();
}
includes 表示可重试异常类型。Spring Framework 7 文档还提供 excludes、更高级的谓词和退避配置;复杂场景需要按目标小版本的 Javadoc 检查参数与默认值。
3.1 为什么不能直接重试支付、扣款或创建订单?
假设请求在下游已提交订单,但响应在网络中丢失。调用方收到超时后再执行一次 createOrder(),可能创建两笔订单。注解无法知道第一次是否已经成功。
对有副作用的操作,必须先建立幂等语义,例如使用业务唯一请求 ID、数据库唯一约束、下游幂等接口或状态查询,再考虑自动重试。重试策略不能代替事务和幂等设计。
3.2 重试风暴的乘法效应
假设 A 调 B,B 调 C,A、B 都允许"初次调用 + 2 次重试",且每次都失败,最坏情况下 C 可能被请求 9 次:
text
A: 3 次尝试
每次 B: 3 次尝试
每次 B 调 C: 1 次
合计 C: 3 × 3 = 9 次
如果 C 自己又包装一次相同重试,次数还会增加。设计上应确定谁拥有重试权,通常在最了解错误语义、幂等与调用预算的边界重试,避免每层都独立重试。
四、@ConcurrencyLimit 管的是什么?
@ConcurrencyLimit 约束的是同一被代理方法同时执行的数量,不是每秒请求数,也不是跨集群的租户配额。
java
import org.springframework.resilience.annotation.ConcurrencyLimit;
import org.springframework.stereotype.Service;
@Service
public class ReportRenderer {
@ConcurrencyLimit(3)
public String render(long reportId) {
// 假设这里会执行耗时的数据库或文件操作
return "report-" + reportId;
}
}
这类限制适合保护本 JVM 中的昂贵资源,例如最多同时运行 3 个报表生成任务。它更接近信号量/并发闸门,而不是 Redis 分布式限流。
4.1 并发上限与 QPS 上限的区别
假设一个请求平均占用资源 2 秒,最大同时运行 3 个,稳定情况下粗略吞吐量可能接近 3 / 2 = 1.5 请求/秒;如果每个请求只耗时 100 毫秒,同样并发 3 的吞吐能力又完全不同。
因此 @ConcurrencyLimit(3) 不能解释为"每秒最多三个请求"。真实吞吐还受请求分布、排队、下游瓶颈和线程调度影响。
4.2 是排队等待,还是返回 429?
Spring Framework 文档将同步调用的 @ConcurrencyLimit 与 ConcurrencyThrottleInterceptor 类比,重点是限制同时进入的调用数量。它本身不是完整的 HTTP 429 限流器。
如果业务要求"超过 100ms 就拒绝并返回 429",还需要明确超时、等待队列和异常映射策略;不能假设注解自动提供指定等待时长、分布式限流、Retry-After 响应头。
4.3 多实例部署时,限制会被放大
假设每个 Pod 使用 @ConcurrencyLimit(3),有 4 个独立 Pod,集群理论上可能同时执行 12 个受保护操作。若数据库最多只能承受 5 个并发查询,这个配置仍可能压垮数据库。
跨 Pod 的全局上限,需要共享协调机制、中心队列、分布式配额或在下游资源自身施加限制。不要把 JVM 内的代理拦截器误认为全局锁。
五、重试与事务、缓存、异步调用的交互
这部分比注解写法更重要,因为同一个方法可能同时标记 @Transactional、@Retryable、@Cacheable 或 @Async。
5.1 与 @Transactional:事务应该在哪一层?
Spring Framework 7 官方文档说明,在其默认的相关代理组合中,@Retryable 与 @Transactional 同时作用时,链路是:
text
Retry(外层)
└─ Transaction(内层)
└─ 业务方法
每次重试进入新的事务。对数据库死锁或瞬时冲突,这通常比"一个事务失败后在同一事务里继续执行"更合理。但需要确认项目中没有额外自定义 AOP 顺序或外层调用者事务改变实际边界。
java
import org.springframework.dao.TransientDataAccessException;
import org.springframework.transaction.annotation.Transactional;
@Transactional
@Retryable(includes = TransientDataAccessException.class, maxRetries = 2)
public void updateStock() {
repository.updateStock();
}
不要把它误解成所有数据库错误都可以重试。 例如唯一键冲突通常是确定性业务冲突;如果在事务提交后发生响应丢失,外部副作用仍可能重复。
5.2 与 @Cacheable:缓存命中也参与调用链
官方文档描述的默认顺序是 Retry 在外、Cache 在内。每次重试都可能重新经过缓存拦截器;并发线程在两次尝试之间填充缓存时,下一次尝试可能直接命中缓存,不再访问目标方法。
因此日志里"重试次数 2"与"实际执行 SQL 次数 2"不一定相同,观测时应分清代理调用、缓存命中与目标方法执行。
5.3 与 @Async:重试发生在哪个线程?
官方说明 @Async 与 @Retryable 组合时,异步拦截器在外,重试在内。任务提交到异步执行器一次,后续重试在异步线程内发生;调用者收到的 Future/CompletableFuture 在最终完成后才反映结果。
这意味着异步线程可能在重试间隔内被占用;并发量、队列容量和调用超时仍要单独治理。对于大量长时间等待任务,不应简单地无限扩大线程池。
六、和 Resilience4j 到底怎么选?
两者不是完全等价的替代品。
| 需求 | Spring Framework 7 原生能力 | Resilience4j 等专用方案 |
|---|---|---|
| 简单方法级重试 | 适合 | 适合 |
| 简单本机并发限制 | 适合 | 可用 Bulkhead 等组件 |
| 熔断器状态机 | 不是这两个注解提供的能力 | 有 CircuitBreaker |
| 按业务维度限流 | 需自行设计 | 有 RateLimiter 等能力 |
| 重试/熔断/隔离组合 | 需额外设计 | 提供更多组件与集成 |
| 跨实例全局限额 | 不提供 | 通常仍需外部共享协调 |
| 复杂监控与恢复策略 | 需结合实际工程 | 专用生态更丰富 |
推荐决策: 如果服务只需要对明确的瞬时错误进行两次重试,并限制少量昂贵方法的本机并发,原生能力足够简洁。如果要统一治理熔断、退避、限流、超时、降级与指标,继续评估 Resilience4j 或其他成熟方案。
不要为了"框架内置"就迁移全部稳定运行的容错配置。版本升级的真实成本包括行为兼容、监控迁移、故障演练和调用链重排。
七、怎样做一次有说服力的验证?
只看到"第三次调用成功"还不够。建议在测试环境用假依赖构造以下故障矩阵。
| 测试场景 | 预期检查 |
|---|---|
| 前两次抛瞬时异常,第三次成功 | 最多 3 次总尝试 |
| 连续四次抛瞬时异常 | 第三次失败后传播最终异常(maxRetries=2) |
| 抛业务校验异常 | 不重试 |
| Bean 内部自调用 | 若未经过代理,不触发预期重试 |
| 并发 10 个请求,限制 3 | 目标方法同时执行数不超过 3 |
| 4 个 Pod 各限制 3 | 集群层面可能超过 3 |
| 方法带 @Transactional | 观察每次尝试的事务边界 |
| 方法带 @Async | 检查任务提交次数与 Future 最终状态 |
7.1 用 CountDownLatch 验证并发限制
可以让 10 个线程同时调用 Spring 容器中的 ReportRenderer,在方法入口递增 AtomicInteger current,更新 maxObserved,在 finally 中递减;方法中用受控的 CountDownLatch 保持部分调用不退出。
预期断言: maxObserved <= 3。同时给测试设置整体超时,避免因等待锁或线程数不足而永久挂起。直接 new ReportRenderer() 测试不到 Spring 代理限制。
7.2 观测指标应该怎么设计?
至少记录:
retry_attempts_total:按方法、异常类型、最终结果聚合,避免把用户 ID 当指标标签;retry_exhausted_total:重试耗尽的业务量;protected_concurrency:受保护方法的当前并发和峰值;- 下游请求总数、成功率、P95/P99、超时与连接池等待时间。
这些是建议的自定义业务指标名,不代表 Spring Framework 7 自动生成同名指标。上线前应核实具体版本可用的 Observation/Actuator 集成,避免重复计数。
八、生产落地时的五个边界
第一,重试必须有总预算。 结合调用超时和 SLA 计算最坏耗时。例如每次最多等待 2 秒,最多 3 次尝试,外加两段 1 秒退避,理论最坏等待约 8 秒(未计其他开销)。如果上游 HTTP 超时只有 3 秒,配置本身就不协调。
第二,重试只针对可恢复错误。 对 400、403、业务校验失败、永久不存在等错误,重试只会增加负载;对于 429 应尊重下游退避建议,不要立刻并发重放。
第三,写操作先做幂等。 数据库唯一键、幂等请求 ID 和下游状态查询应先于自动重试上线。
第四,并发限制不能代替容量规划。 同时评估连接池、线程池、CPU、慢查询、队列长度和多实例数量。
第五,必须演练最坏情况。 让依赖持续失败、让连接池变慢、模拟调用取消,检查重试是否造成线程堆积,是否影响其他接口,以及故障恢复后是否出现二次冲击。
九、结论
Spring Framework 7 的 @Retryable、@ConcurrencyLimit 把常见的方法级韧性能力带进核心框架,适合清晰、有限的重试与本地并发保护。但它们不是完整的"分布式容错平台":重试次数要算清,事务与幂等要分开,集群容量不能按单实例上限估算。
对于已有 Resilience4j 的项目,不必因为框架升级就立即替换;对于新项目,先把错误分类、最大尝试次数、总超时和并发上限定义好,再选择最简单且可验证的实现。
官方参考