本文深入探讨了在 Spring 6 和 Spring Boot 3 中，如何为新的 HTTP 接口实现健壮的重试机制。针对传统 `WebClient` `retryWhen()` 方法在 HTTP 接口中应用不便的问题，文章详细介绍了通过 `ExchangeFilterFunction` 拦截请求并处理错误响应，从而优雅地集成重试策略。通过代码示例，展示了如何配置 `WebClient` 并在 `HttpServiceProxyFactory` 中使用，确保所有通过 HTTP 接口发出的请求都能统一地应用重试逻辑，提升服务韧性。
Spring 6 HTTP 接口简介
Spring Framework 6 和 Spring Boot 3 引入了全新的 HTTP 接口（HTTP Interface），它允许开发者通过定义 Java 接口来声明 HTTP 客户端，并利用 HttpServiceProxyFactory 自动生成实现。这种方式极大地简化了声明式 HTTP 客户端的开发，类似于 OpenFeign 或 Retrofit，使得远程服务调用更加直观和类型安全。
一个典型的 HTTP 接口定义如下：
public interface TodoClient {
@GetExchange("/todos/{id}")
Mono<Todo> getTodo(@PathVariable String id);
}然后通过 HttpServiceProxyFactory 创建客户端实例：
WebClient webClient = WebClient.builder().baseUrl("http://localhost:8080").build();
HttpServiceProxyFactory factory = HttpServiceProxyFactory.builder(WebClientAdapter.forClient(webClient)).build();
TodoClient todoClient = factory.createClient(TodoClient.class);传统 WebClient 重试的局限性
在使用 WebClient 时，我们通常会利用其响应式流的特性，通过 retryWhen() 操作符来处理请求失败后的重试逻辑。例如：
public Mono<String> getData(String stockId) {
return webClient.get()
.uri("/data/{id}", stockId)
.retrieve()
.bodyToMono(String.class)
.retryWhen(Retry.backoff(3, Duration.ofSeconds(2)));
}然而，当使用 HTTP 接口时，getTodo() 方法直接返回 Mono
解决方案：利用 ExchangeFilterFunction 实现全局重试
为了在 Spring 6 HTTP 接口中实现统一的重试机制，我们需要在 WebClient 层面进行干预。WebClient 提供了 ExchangeFilterFunction 机制，允许我们拦截并修改请求和响应。通过自定义一个 ExchangeFilterFunction，我们可以在请求发出前或响应接收后执行自定义逻辑，包括错误处理和重试。
1. 定义重试过滤器
核心思想是创建一个 ExchangeFilterFunction，它会在 WebClient 执行请求后，检查响应状态码。如果响应是错误状态，则通过 Mono.error() 抛出异常，从而触发 retryWhen() 操作符的重试行为。
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.ClientResponse;
import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.reactive.function.client.support.WebClientAdapter;
import org.springframework.web.service.invoker.HttpServiceProxyFactory;
import reactor.core.publisher.Mono;
import reactor.util.retry.Retry;
import java.time.Duration;
@Configuration
public class HttpClientConfig {
private static final Logger log = LoggerFactory.getLogger(HttpClientConfig.class);
/**
* 定义一个重试过滤器
* 该过滤器会在请求失败（HTTP 错误状态码）时触发重试
*
* @return ExchangeFilterFunction 实例
*/
@Bean
public ExchangeFilterFunction retryFilter() {
return (request, next) ->
next.exchange(request) // 执行实际的HTTP请求
.flatMap(clientResponse ->
Mono.just(clientResponse)
.filter(response -> clientResponse.statusCode().isError()) // 检查响应是否为错误状态码
.flatMap(ClientResponse::createException) // 如果是错误，则创建并抛出WebClientResponseException
.flatMap(Mono::error) // 将异常包装成Mono.error()，以便retryWhen捕获
.thenReturn(clientResponse) // 如果不是错误，则直接返回响应
)
.retryWhen(
Retry.fixedDelay(3, Duration.ofSeconds(30)) // 配置重试策略：固定延迟30秒，重试3次
.doAfterRetry(retrySignal -> log.warn("HTTP请求失败，正在进行第 {} 次重试...", retrySignal.totalRetriesInARow() + 1))
.onRetryExhaustedThrow((retryBackoffSpec, retrySignal) -> {
log.error("HTTP请求重试次数耗尽，总计重试 {} 次。", retrySignal.totalRetriesInARow());
return retrySignal.failure(); // 重试耗尽后抛出原始异常
})
);
}
/**
* 配置并创建 TodoClient 实例，集成重试过滤器
*
* @return TodoClient 实例
*/
@Bean
public TodoClient todoClient(WebClient.Builder webClientBuilder) {
WebClient webClient = webClientBuilder
.baseUrl("http://localhost:8080") // 替换为你的服务基础URL
.filter(retryFilter()) // 将重试过滤器添加到WebClient
.build();
HttpServiceProxyFactory factory =
HttpServiceProxyFactory.builder(WebClientAdapter.forClient(webClient)).build();
return factory.createClient(TodoClient.class);
}
}在上述代码中：
- next.exchange(request)：执行实际的 HTTP 请求并返回一个 Mono
。 - flatMap(clientResponse -> ...)：处理 ClientResponse。
- filter(response -> clientResponse.statusCode().isError())：这是一个关键步骤，它检查 ClientResponse 的状态码是否表示错误（例如 4xx 或 5xx）。
- flatMap(ClientResponse::createException)：如果状态码是错误，createException() 会将 ClientResponse 转换为 WebClientResponseException 或其子类。
- flatMap(Mono::error)：将 WebClientResponseException 包装成一个错误信号，retryWhen() 操作符会捕获这个错误信号并根据配置执行重试。
- thenReturn(clientResponse)：如果响应不是错误状态，则直接返回原始的 ClientResponse，不触发重试。
- retryWhen(Retry.fixedDelay(3, Duration.ofSeconds(30)))：这是 Reactor 提供的重试策略。这里配置了固定延迟 30 秒，重试 3 次。doAfterRetry 用于在每次重试后记录日志，onRetryExhaustedThrow 则在重试次数耗尽后抛出原始异常。
2. 将过滤器集成到 WebClient
在创建 WebClient 实例时，通过 filter() 方法将自定义的 retryFilter() 添加进去。然后，使用这个配置了重试功能的 WebClient 来构建 HttpServiceProxyFactory。
@Bean
public TodoClient todoClient(WebClient.Builder webClientBuilder) {
WebClient webClient = webClientBuilder
.baseUrl("http://localhost:8080") // 替换为你的服务基础URL
.filter(retryFilter()) // 将重试过滤器添加到WebClient
.build();
HttpServiceProxyFactory factory =
HttpServiceProxyFactory.builder(WebClientAdapter.forClient(webClient)).build();
return factory.createClient(TodoClient.class);
}这样，所有通过 TodoClient 接口发出的请求，如果遇到 HTTP 错误状态码，都会自动应用配置的重试策略。
注意事项与最佳实践
- 重试的幂等性：重试通常适用于幂等操作（多次执行相同操作产生相同结果，例如 GET 请求）。对于非幂等操作（如 POST、PUT、DELETE），重试可能会导致副作用，需要谨慎评估。
-
重试策略选择：
- Retry.fixedDelay(maxAttempts, Duration.ofMillis(delay))：固定延迟重试。
- Retry.backoff(maxAttempts, Duration.ofMillis(firstBackoff))：指数退避重试，每次延迟时间会增加。
- Retry.max(maxAttempts)：只限制重试次数，不带延迟。 根据实际业务场景和后端服务负载能力选择合适的策略。
- 错误类型过滤：在更复杂的场景中，你可能只想对特定类型的错误（例如网络错误、特定 HTTP 状态码 503 Service Unavailable）进行重试，而不是所有错误。可以在 filter 逻辑中进一步细化判断条件。
- 超时配置：重试机制应与超时配置结合使用。确保每次尝试都有合理的超时时间，避免长时间阻塞。
- 熔断机制：对于频繁失败的服务，仅仅重试可能不足以解决问题，甚至会加剧问题。此时应考虑引入熔断器（Circuit Breaker）模式，例如使用 Resilience4j，当服务持续不可用时，快速失败并阻止进一步的请求，保护系统。
- 日志记录：在 doAfterRetry 中添加详细的日志记录，有助于在生产环境中追踪和调试重试行为。
- WebClient.Builder 注入：推荐通过注入 WebClient.Builder 来创建 WebClient 实例，这样可以利用 Spring Boot 自动配置的默认设置（如连接池、SSL等）。
总结
通过 ExchangeFilterFunction 机制，我们可以在 Spring 6/Spring Boot 3 的 HTTP 接口中优雅地实现统一的重试逻辑。这种方法将重试策略从业务逻辑中解耦，集中管理，提高了代码的可维护性和服务的韧性。在设计分布式系统时，重试是处理瞬时故障和提升系统健壮性的重要手段，但需结合业务特性和系统负载进行合理配置。
