本文深入探讨了在 spring 6 和 spring boot 3 中，如何为基于新 http 接口的客户端实现请求重试机制。由于 http 接口本身不直接提供重试功能，文章详细介绍了通过集成 `webclient` 的 `exchangefilterfunction` 来拦截并处理请求失败，从而实现灵活的、可配置的重试策略，确保服务调用的韧性。
理解 Spring 6 HTTP 接口与重试的挑战
Spring Framework 6 和 Spring Boot 3 引入了全新的 HTTP 接口（HTTP Interface），旨在提供一种声明式、类型安全的方式来定义 HTTP 客户端。通过结合 HttpServiceProxyFactory 和 WebClientAdapter，开发者可以像定义 Spring Data Repository 接口一样，简单地定义一个 Java 接口来代表远程 HTTP 服务，从而极大地简化了客户端代码的编写。
例如，一个典型的 HTTP 客户端接口可能如下所示：
public interface TodoClient {
@GetExchange("/todos/{id}")
Mono<Todo> getTodoById(@PathVariable String id);
}在使用传统的 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)));
}然而，当通过 HttpServiceProxyFactory 创建 HTTP 接口客户端时，retryWhen() 操作符无法直接应用于整个接口或单个方法，因为 HTTP 接口的调用被抽象化了，我们无法直接访问底层的 Mono 流来插入重试逻辑。这就需要一种更通用的机制来拦截所有通过该接口发出的请求并应用重试策略。
解决方案：利用 ExchangeFilterFunction 实现重试
解决这个问题的关键在于 WebClient 的 ExchangeFilterFunction。ExchangeFilterFunction 允许我们在实际发送 HTTP 请求之前或接收到响应之后，对请求和响应进行拦截和处理。通过构建一个自定义的 ExchangeFilterFunction，我们可以在其中嵌入重试逻辑，并将其应用于由 HttpServiceProxyFactory 使用的 WebClient 实例。
1. 定义重试过滤器
首先，我们需要创建一个 ExchangeFilterFunction bean，它将包含我们的重试逻辑。这个过滤器会在 WebClient 执行请求并收到响应后被激活。
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.reactive.function.client.ClientResponse;
import org.springframework.web.reactive.function.client.ExchangeFilterFunction;
import reactor.core.publisher.Mono;
import reactor.util.retry.Retry;
import java.time.Duration;
public class RetryFilterConfig {
private static final Logger log = LoggerFactory.getLogger(RetryFilterConfig.class);
// ... 其他配置或客户端 bean ...
public ExchangeFilterFunction retryFilter() {
return (request, next) ->
next.exchange(request) // 执行原始请求
.flatMap(clientResponse -> {
// 检查响应状态码是否为错误
if (clientResponse.statusCode().isError()) {
// 如果是错误，则创建一个异常并将其作为错误信号传播
// 这是关键一步，让 retryWhen 能够捕获到错误并触发重试
return clientResponse.createException()
.flatMap(Mono::error);
}
// 如果不是错误，则直接返回响应
return Mono.just(clientResponse);
})
.retryWhen(
// 配置重试策略
Retry.fixedDelay(3, Duration.ofSeconds(30)) // 固定延迟30秒，重试3次
.doAfterRetry(retrySignal -> log.warn("检测到错误，正在进行第 {} 次重试...", retrySignal.totalRetriesInARow() + 1)) // 每次重试后记录日志
.filter(throwable -> {
// 可选：根据异常类型决定是否重试
// 例如，只对 IOException 或特定的 WebClientResponseException 进行重试
// return throwable instanceof WebClientResponseException;
return true; // 默认对所有错误进行重试
})
);
}
}代码解析：
- next.exchange(request): 这会调用过滤器链中的下一个元素，最终会执行实际的 HTTP 请求。
- flatMap(clientResponse -> ...): 当 WebClient 收到响应时，这个 flatMap 会被执行。
- clientResponse.statusCode().isError(): 我们在这里检查响应的状态码是否表示错误（例如 4xx 或 5xx）。
- clientResponse.createException().flatMap(Mono::error): 这是实现重试的关键。 retryWhen() 操作符通常是在 Mono 或 Flux 发出错误信号时才会被触发。默认情况下，WebClient 对于非 2xx 状态码并不会直接发出错误信号，而是会返回一个包含错误状态码的 ClientResponse。为了让 retryWhen() 生效，我们必须显式地将错误状态码转换为一个 Mono.error() 信号。createException() 方法会根据响应状态码生成一个 WebClientResponseException 或其子类，然后我们通过 flatMap(Mono::error) 将其包装成一个错误信号。
- Retry.fixedDelay(3, Duration.ofSeconds(30)): 这是 Reactor Netty 提供的重试策略。
- fixedDelay(3, Duration.ofSeconds(30)): 表示最多重试 3 次，每次重试之间固定延迟 30 秒。
- doAfterRetry(...): 这是一个副作用操作，可以在每次重试发生后执行，常用于日志记录。
- filter(throwable -> ...): 允许你根据抛出的异常类型来决定是否应该进行重试。例如，你可能只想对网络相关的 IOException 或特定的 WebClientResponseException 进行重试，而对于客户端请求错误（如 400 Bad Request）则不重试。
2. 将过滤器应用于 WebClient
接下来，在创建 WebClient 实例时，通过 filter() 方法注册这个重试过滤器。这个 WebClient 实例随后会被 HttpServiceProxyFactory 用来创建 HTTP 接口客户端。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.reactive.function.client.WebClient;
import org.springframework.web.reactive.function.client.support.WebClientAdapter;
import org.springframework.web.service.invoker.HttpServiceProxyFactory;
@Configuration
public class HttpClientConfig {
// 假设 TodoClient 是你的 HTTP 接口
// public interface TodoClient { ... }
@Bean
public TodoClient todoClient(RetryFilterConfig retryFilterConfig) { // 注入 RetryFilterConfig
WebClient webClient =
WebClient.builder()
.baseUrl("http://localhost:8080") // 你的服务基础URL
.filter(retryFilterConfig.retryFilter()) // 注册重试过滤器
.build();
HttpServiceProxyFactory factory =
HttpServiceProxyFactory.builder(WebClientAdapter.forClient(webClient)).build();
return factory.createClient(TodoClient.class);
}
// 将 RetryFilterConfig 声明为一个 Bean
@Bean
public RetryFilterConfig retryFilterConfig() {
return new RetryFilterConfig();
}
}通过这种方式，所有通过 todoClient 接口发出的 HTTP 请求，如果遇到错误响应（由 isError() 判断），都会触发我们定义的重试逻辑。
拓展与注意事项
- 重试策略多样性： Reactor 的 Retry 提供了多种重试策略，如 backoff (指数退避)、fixedDelay (固定延迟)、max (最大重试次数) 等。你可以根据实际需求选择合适的策略。
- 条件重试： 使用 filter(Predicate<Throwable> predicate) 可以精确控制在何种错误条件下才进行重试。例如，你可能只希望对瞬时网络错误（如连接超时）进行重试，而对业务逻辑错误（如 404 Not Found）则不重试。
- 错误处理： 当重试次数用尽后，如果请求仍然失败，Mono 流将最终发出一个错误信号。你需要确保你的调用端能够妥善处理这个最终的错误。
- 幂等性： 在实现重试时，务必考虑请求的幂等性。对于非幂等操作（如创建资源），盲目重试可能导致重复创建，从而引发数据不一致问题。在这种情况下，可能需要更复杂的重试策略，或者避免对非幂等操作进行自动重试。
- 日志记录： 在 doAfterRetry 中添加详细的日志记录，有助于在生产环境中追踪重试行为，了解服务调用的稳定性。
- 全局与局部重试： 上述方法实现了全局重试，即对所有通过该 WebClient 发出的请求都生效。如果需要对特定接口方法实现不同的重试策略，则可能需要更细粒度的控制，例如在 HttpServiceProxyFactory 创建客户端后，对返回的 Mono 结果手动添加 retryWhen，但这会失去 HTTP 接口的声明式优势。
总结
Spring 6 的 HTTP 接口极大地提升了声明式 HTTP 客户端的开发效率。尽管它没有内置重试机制，但通过巧妙地结合 WebClient 的 ExchangeFilterFunction，我们可以构建一个强大且灵活的重试过滤器。这个过滤器能够拦截所有请求，将错误状态码转换为可被 Reactor retryWhen() 识别的错误信号，从而为我们的 HTTP 客户端提供了必要的韧性，使其在面对瞬时故障时能够自动恢复。在实际应用中，合理配置重试策略并考虑幂等性是确保系统稳定性和数据一致性的关键。
