一文学会 Spring Boot 中的 Spring Retry：打造高弹性应用

在现代软件开发中，构建弹性（Resilience）应用程序是至关重要的。无论是网络抖动、数据库连接中断，还是第三方服务临时不可用，这些常见问题都可能导致系统故障。直接抛出异常或让应用程序崩溃并不是最佳选择，相反，通过重试机制可以让系统优雅地从临时故障中恢复。

Spring Boot 提供了 Spring Retry 模块，这是一个功能强大且易于使用的工具，用于实现重试逻辑。本文将从基础配置到高级用法，全面介绍如何在 Spring Boot 中使用 Spring Retry，帮助你打造更加健壮的应用程序。我们还会探讨最佳实践、常见错误以及扩展场景，让你对 Spring Retry 有更深的理解。

什么是 Spring Retry？

Spring Retry 是 Spring 框架的一个模块，专门为处理临时性故障提供重试支持。它允许开发者通过简单的配置，为可能失败的操作（如 API 调用、数据库查询等）添加自动重试逻辑，而无需手动编写复杂的循环代码。

Spring Retry 的核心目标是：

处理临时故障：如网络延迟、超时或服务短暂不可用。
提高系统可靠性：通过自动重试减少失败的概率。
简化开发：提供声明式（注解）和编程式（模板）两种方式，降低实现难度。

常见的应用场景包括：

重试第三方 API 调用。
处理数据库事务中的临时连接问题。
在消息队列（如 Kafka、RabbitMQ）中重试消息处理。
实现指数退避策略，避免对故障服务造成额外压力。

Spring Retry 的核心特性

灵活的重试策略：
- 支持自定义重试次数、特定异常类型和重试条件。
- 允许排除某些异常，避免不必要的重试。
多样化的退避策略：
- 支持固定延迟、指数退避（Exponential Backoff）等。
- 可配置随机抖动（Jitter），减少并发重试的冲突。
声明式支持：
- 使用 @Retryable 和 @Recover 注解，简化重试逻辑的实现。
有状态与无状态重试：
- 无状态重试适用于幂等操作。
- 有状态重试适合需要跟踪上下文的非幂等操作（如事务）。
集成性：
- 与 Spring Boot 无缝集成，支持 AOP（面向切面编程）驱动的声明式重试。
- 可与其他容错工具（如 Resilience4j、Hystrix）结合使用。

为什么需要重试机制？

重试机制是构建高可用系统的重要组成部分，它带来以下好处：

增强系统弹性：自动处理临时故障，避免因小问题导致系统不可用。
提升用户体验：通过重试减少失败请求，让用户感知更顺畅。
降低运维成本：自动化恢复减少人工干预的需求。
支持复杂容错模式：可与断路器、限流等机制结合，构建更强大的容错体系。

然而，重试并非万能药，过度或不当的重试可能导致资源浪费或加剧系统压力。因此，合理的配置和策略至关重要。

在 Spring Boot 中配置 Spring Retry

步骤 1：添加依赖

在 pom.xml 中添加以下依赖：

<dependency>
    <groupId>org.springframework.retry</groupId>
    <artifactId>spring-retry</artifactId>
    <version>2.0.10</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-aop</artifactId>
</dependency>

spring-retry：提供重试核心功能。
spring-boot-starter-aop：支持基于注解的声明式重试（通过 Spring AOP 实现）。

注意：请根据需要选择最新版本的 spring-retry，可以通过 Maven Central 查看。

步骤 2：启用 Spring Retry

在 Spring Boot 配置类中添加 @EnableRetry 注解，启用重试功能：

import org.springframework.context.annotation.Configuration;
import org.springframework.retry.annotation.EnableRetry;

@Configuration
@EnableRetry
public class RetryConfig {
}

启用后，Spring 会自动识别 @Retryable 和 @Recover 注解，并为标注的方法添加重试逻辑。

使用 `@Retryable` 和 `@Recover` 注解

Spring Retry 提供了一种声明式的重试方式，通过注解可以轻松为方法添加重试逻辑。

`@Retryable`：定义重试行为

@Retryable 注解用于标记需要重试的方法，支持以下常用参数：

retryFor：指定需要重试的异常类型（默认空，表示所有异常）。
exclude：指定不需要重试的异常类型。
maxAttempts：最大重试次数（包括第一次尝试）。
backoff：退避策略，定义重试之间的延迟。

以下是一个简单的示例：

import lombok.extern.slf4j.Slf4j;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Service;

@Service
@Slf4j
public class ApiService {

    @Retryable(
            retryFor = {RuntimeException.class},
            maxAttempts = 3,
            backoff = @Backoff(delay = 2000, multiplier = 2)
    )
    public String fetchData() {
        log.info("Attempting to fetch data...");
        // 模拟随机失败
        if (Math.random() > 0.5) {
            throw new RuntimeException("Temporary API failure");
        }
        return "Data retrieved successfully";
    }
}

解析：

异常类型：仅对 RuntimeException 进行重试。
重试次数：最多尝试 3 次（1 次初始调用 + 2 次重试）。
退避策略：初始延迟 2 秒，每次重试延迟翻倍（2s → 4s）。

运行结果可能如下：

Attempting to fetch data... // 第一次失败
Attempting to fetch data... // 2 秒后重试
Data retrieved successfully // 成功

`@Recover`：定义回退逻辑

当所有重试尝试失败后，Spring Retry 会调用 @Recover 注解标记的回退方法。回退方法的签名需要满足以下条件：

返回类型与原方法一致。
第一个参数是触发重试的异常类型。
方法必须位于同一类中。

示例：

import lombok.extern.slf4j.Slf4j;
import org.springframework.retry.annotation.Recover;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Service;

@Service
@Slf4j
public class RetryService {

    @Retryable(retryFor = {RuntimeException.class}, maxAttempts = 3)
    public String fetchData() {
        log.info("Attempting to fetch data...");
        throw new RuntimeException("API failure");
    }

    @Recover
    public String recover(RuntimeException e) {
        log.info("Recovering from failure: {}", e.getMessage());
        return "Default data";
    }
}

运行结果：

Attempting to fetch data... // 第一次失败
Attempting to fetch data... // 第二次失败
Attempting to fetch data... // 第三次失败
Recovering from failure: API failure // 调用回退方法

注意：

如果没有定义 @Recover 方法，重试失败后会直接抛出异常。
回退方法可以根据异常类型提供不同的处理逻辑。

创建 REST API 演示重试

为了更直观地展示 Spring Retry 的效果，我们创建一个简单的 REST 控制器，调用带有重试逻辑的服务。

import lombok.Data;
import lombok.RequiredArgsConstructor;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/v1")
@RequiredArgsConstructor
public class RetryController {

    private final RetryService retryService;

    @GetMapping("/simple-retry")
    public ResponseEntity<ApiResponse> simpleRetry() {
        try {
            String result = retryService.callExternalService();
            return ResponseEntity.ok(new ApiResponse(true, result, null));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(new ApiResponse(false, null, e.getMessage()));
        }
    }

    @GetMapping("/simple-recovery")
    public ResponseEntity<ApiResponse> simpleRecovery() {
        try {
            String result = retryService.fetchData();
            return ResponseEntity.ok(new ApiResponse(true, result, null));
        } catch (Exception e) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body(new ApiResponse(false, null, e.getMessage()));
        }
    }
}

@Data
class ApiResponse {
    private boolean success;
    private String data;
    private String error;

    public ApiResponse(boolean success, String data, String error) {
        this.success = success;
        this.data = data;
        this.error = error;
    }
}

对应的 RetryService：

import lombok.extern.slf4j.Slf4j;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Recover;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Service;

@Service
@Slf4j
public class RetryService {
    private int attemptCount = 0;

    @Retryable(
            retryFor = {RuntimeException.class},
            maxAttempts = 3,
            backoff = @Backoff(delay = 2000, multiplier = 2)
    )
    public String callExternalService() {
        attemptCount++;
        log.info("Attempting to call external service. Attempt #{}", attemptCount);
        if (attemptCount < 3) {
            log.info("Service temporarily unavailable");
            throw new RuntimeException("Service temporarily unavailable");
        }
        return "Service call successful!";
    }

    @Retryable(retryFor = {RuntimeException.class}, maxAttempts = 3)
    public String fetchData() {
        log.info("Attempting to fetch data...");
        throw new RuntimeException("API failure");
    }

    @Recover
    public String recover(RuntimeException e) {
        log.info("Recovering from failure: {}", e.getMessage());
        return "Default data";
    }
}

测试 Spring Retry

我们使用 Postman 或 cURL 测试上述 API。

测试 1：简单重试 (`GET /api/v1/simple-retry`)

curl --location 'http://localhost:8080/api/v1/simple-retry'

日志：

Attempting to call external service. Attempt #1
Service temporarily unavailable
Attempting to call external service. Attempt #2
Service temporarily unavailable
Attempting to call external service. Attempt #3

响应：

{
    "success": true,
    "data": "Service call successful!",
    "error": null
}

解析：前两次调用失败，第三次成功，符合预期。

测试 2：带恢复的重试 (`GET /api/v1/simple-recovery`)

curl --location 'http://localhost:8080/api/v1/simple-recovery'

日志：

Attempting to fetch data...
Attempting to fetch data...
Attempting to fetch data...
Recovering from failure: API failure

响应：

{
    "success": true,
    "data": "Default data",
    "error": null
}

解析：三次重试均失败，最终调用回退方法返回默认数据。

有状态与无状态重试

Spring Retry 支持两种重试模式：

无状态重试（默认）：
- 每次重试独立执行，适合幂等操作（如查询 API）。
- 示例：上面的 callExternalService 和 fetchData 方法。
有状态重试：
- 在重试间保留状态，适合非幂等操作（如数据库事务）。
- 通过设置 @Retryable(stateful = true) 启用。

示例：

@Retryable(stateful = true, retryFor = {SQLException.class}, maxAttempts = 3)
public void processTransaction() {
    // 非幂等数据库操作
    throw new SQLException("Database temporarily unavailable");
}

注意：有状态重试需要谨慎使用，因为它会维护调用上下文，可能增加内存开销。

使用 `RetryTemplate` 自定义重试

对于更复杂的场景，可以通过 RetryTemplate 以编程方式实现重试逻辑。

配置 `RetryTemplate`

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.retry.backoff.ExponentialBackOffPolicy;
import org.springframework.retry.policy.SimpleRetryPolicy;
import org.springframework.retry.support.RetryTemplate;

@Configuration
public class RetryConfig {

    @Bean
    public RetryTemplate retryTemplate() {
        RetryTemplate retryTemplate = new RetryTemplate();

        // 配置重试策略
        SimpleRetryPolicy retryPolicy = new SimpleRetryPolicy();
        retryPolicy.setMaxAttempts(5);
        retryTemplate.setRetryPolicy(retryPolicy);

        // 配置退避策略
        ExponentialBackOffPolicy backOffPolicy = new ExponentialBackOffPolicy();
        backOffPolicy.setInitialInterval(1000); // 初始延迟 1 秒
        backOffPolicy.setMultiplier(2); // 每次延迟翻倍
        retryTemplate.setBackOffPolicy(backOffPolicy);

        return retryTemplate;
    }
}

使用 `RetryTemplate`

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.retry.support.RetryTemplate;
import org.springframework.stereotype.Service;

@Service
public class TemplateRetryService {

    @Autowired
    private RetryTemplate retryTemplate;

    public String callWithRetry() {
        return retryTemplate.execute(context -> {
            // 重试逻辑
            if (context.getRetryCount() < 2) {
                throw new RuntimeException("Temporary failure");
            }
            return "Success after retries";
        }, context -> {
            // 回退逻辑
            return "Default response";
        });
    }
}

优势：

提供更高的灵活性，可以动态调整重试逻辑。
适合复杂场景，如嵌套重试或动态策略。

Spring Retry 最佳实践

选择性重试异常：
- 仅对临时性异常（如 IOException、TimeoutException）进行重试。
- 使用 exclude 参数排除不可恢复的异常（如 IllegalArgumentException）。
合理配置退避策略：
- 使用指数退避减少对故障服务的压力。
- 添加随机抖动（Jitter）避免重试风暴。
限制重试次数：
- 设置合理的 maxAttempts，避免无限重试导致资源耗尽。
- 通常 3-5 次重试足以应对大多数临时故障。
监控与日志：
- 使用日志记录每次重试的详细信息，便于调试和监控。
- 集成监控工具（如 Spring Actuator、Prometheus）跟踪重试次数和成功率。
结合其他容错机制：
- 将 Spring Retry 与断路器（如 Resilience4j）结合，防止重试加剧系统故障。
- 使用限流（Rate Limiting）控制重试频率。
测试重试逻辑：
- 在开发环境中模拟故障（如网络延迟、超时）验证重试效果。
- 确保回退逻辑能够正确处理所有失败场景。

常见用例

外部 API 调用：
- 重试因网络问题或服务不可用导致的失败请求。
- 示例：调用支付网关 API。
数据库操作：
- 重试因连接池耗尽或锁冲突导致的失败查询。
- 示例：批量插入数据时重试。
消息队列：
- 重试因消费者故障导致的消息处理失败。
- 示例：Kafka 消费者重试消息处理。
文件操作：
- 重试因临时权限问题或网络中断导致的文件上传/下载失败。

常见错误及解决方法

@Retryable 失效：
- 原因：注解用在私有方法或非 Spring 管理的 Bean 上。
- 解决：确保方法是公共的，且类被 Spring 管理（加 @Service 或 @Component）。
未触发重试：
- 原因：目标异常未包含在 retryFor 中。
- 解决：检查异常类型，必要时扩展 retryFor 列表。
回退方法未调用：
- 原因：@Recover 方法签名不匹配（如返回类型或参数错误）。
- 解决：确保 @Recover 方法与 @Retryable 方法的返回类型一致，且异常参数正确。
性能问题：
- 原因：重试次数过多或延迟过短。
- 解决：调整 maxAttempts 和 backoff 参数，启用指数退避。
线程安全问题：
- 原因：在重试方法中使用共享资源（如静态变量）未加锁。
- 解决：确保重试逻辑是线程安全的，或使用局部变量。

扩展：与断路器结合

Spring Retry 通常与断路器模式结合使用，以进一步提升系统容错能力。例如，可以使用 Resilience4j 实现断路器：

添加 Resilience4j 依赖

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-spring-boot3</artifactId>
    <version>2.2.0</version>
</dependency>

配置断路器

resilience4j.circuitbreaker:
  instances:
    externalService:
      slidingWindowSize: 10
      failureRateThreshold: 50
      waitDurationInOpenState: 10000

结合使用

import io.github.resilience4j.circuitbreaker.annotation.CircuitBreaker;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Service;

@Service
public class CombinedService {

    @Retryable(retryFor = {RuntimeException.class}, maxAttempts = 3, backoff = @Backoff(delay = 1000))
    @CircuitBreaker(name = "externalService", fallbackMethod = "circuitBreakerFallback")
    public String callService() {
        // 模拟外部服务调用
        throw new RuntimeException("Service failure");
    }

    public String circuitBreakerFallback(Throwable t) {
        return "Circuit breaker fallback";
    }
}

效果：

重试：尝试 3 次调用服务。
断路器：如果失败率超过阈值，断路器打开，直接调用回退方法。

结论

Spring Retry 是构建弹性 Spring Boot 应用程序的强大工具。通过声明式的 @Retryable 和 @Recover 注解，或者编程式的 RetryTemplate，开发者可以轻松实现重试逻辑，应对临时故障。结合最佳实践和合理的配置，Spring Retry 能够显著提高系统可靠性和用户体验。

无论是处理外部 API 调用、数据库操作，还是消息队列处理，Spring Retry 都能提供灵活的解决方案。如果你希望进一步增强容错能力，可以将其与断路器、限流等机制结合，构建更加健壮的系统。

想了解更多？ 可以参考 Spring Retry 官方文档或留言讨论！

这篇文章对原文进行了重写和扩展，增加了更详细的解析、示例代码和优化建议，同时保持了清晰的结构和易读性。如果你有其他需求或想深入某个部分，请告诉我！

目录CONTENT

一文学会 Spring Boot 中的 Spring Retry：打造高弹性应用

一文学会 Spring Boot 中的 Spring Retry：打造高弹性应用

什么是 Spring Retry？

Spring Retry 的核心特性

为什么需要重试机制？

在 Spring Boot 中配置 Spring Retry

步骤 1：添加依赖

步骤 2：启用 Spring Retry

使用 `@Retryable` 和 `@Recover` 注解

`@Retryable`：定义重试行为

`@Recover`：定义回退逻辑

创建 REST API 演示重试

测试 Spring Retry

测试 1：简单重试 (`GET /api/v1/simple-retry`)

测试 2：带恢复的重试 (`GET /api/v1/simple-recovery`)

有状态与无状态重试

使用 `RetryTemplate` 自定义重试

配置 `RetryTemplate`

使用 `RetryTemplate`

Spring Retry 最佳实践

常见用例

常见错误及解决方法

扩展：与断路器结合

添加 Resilience4j 依赖

配置断路器

结合使用

结论

评论区

一文学会 Spring Boot 中的 Spring Retry：打造高弹性应用

一文学会 Spring Boot 中的 Spring Retry：打造高弹性应用

什么是 Spring Retry？

Spring Retry 的核心特性

为什么需要重试机制？

在 Spring Boot 中配置 Spring Retry

步骤 1：添加依赖

步骤 2：启用 Spring Retry

使用 @Retryable 和 @Recover 注解

@Retryable：定义重试行为

@Recover：定义回退逻辑

创建 REST API 演示重试

测试 Spring Retry

测试 1：简单重试 (GET /api/v1/simple-retry)

测试 2：带恢复的重试 (GET /api/v1/simple-recovery)

有状态与无状态重试

使用 RetryTemplate 自定义重试

配置 RetryTemplate

使用 RetryTemplate

Spring Retry 最佳实践

常见用例

常见错误及解决方法

扩展：与断路器结合

添加 Resilience4j 依赖

配置断路器

结合使用

结论

评论区

使用 `@Retryable` 和 `@Recover` 注解

`@Retryable`：定义重试行为

`@Recover`：定义回退逻辑

测试 1：简单重试 (`GET /api/v1/simple-retry`)

测试 2：带恢复的重试 (`GET /api/v1/simple-recovery`)

使用 `RetryTemplate` 自定义重试

配置 `RetryTemplate`

使用 `RetryTemplate`