近日，多位 Java 开发者在技术社区反映，在基于 Apache HttpClient 5 构建的 RestClient 中，默认的重试机制在某些业务场景下可能导致非幂等请求被重复执行，引发数据不一致或接口超负荷。针对这一痛点，本文提供一套清晰的禁用重试方案的实操指南，帮助开发者精准控制客户端行为。

一、问题背景：为什么需要禁用重试？

Apache HttpClient 5 作为经典的 HTTP 客户端库，在 Spring Boot 3.x 及微服务架构中被广泛使用。它内置的重试机制旨在提升网络不稳定性下的请求成功率，默认情况下，当遇到可恢复的异常（如 ConnectException、SocketTimeoutException）时，客户端会自动重试最多 3 次。

然而，这种“自动化”并非适用于所有场景： - 非幂等操作：如 POST 创建订单、转账等请求，重复执行可能导致重复扣款或资源重复创建。 - 延迟敏感接口：金融交易、实时推送等场景要求快速失败而非等待重试。 - 自定义重试逻辑：部分团队已在业务层（如 Spring Retry）实现了更精细的重试策略，底层再自动重试会造成冗余。

因此，针对基于 HttpClient 5 构建的 RestClient（Spring 6.1 起原生支持），明确禁用重试机制成为许多项目的刚需。

二、核心解决方案：两步切断自动重试

1. 通过 HttpClientBuilder 禁用重试

HttpClient 5 提供了 HttpClientBuilder 类，其中的 disableAutomaticRetries() 方法可直接关闭所有自动重试逻辑。具体代码如下：

import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;

CloseableHttpClient httpClient = HttpClientBuilder.create()
        .disableAutomaticRetries()  // 禁用自动重试
        .build();

若需要更细粒度的控制（例如仅对特定异常禁用），可自定义 RetryStrategy：

import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;
import org.apache.hc.client5.http.impl.ClassicRequestRetryHandler;

CloseableHttpClient httpClient = HttpClientBuilder.create()
        .setRetryStrategy((request, exception, execCount, context) -> false) // 始终不重试
        .build();

2. 将 HttpClient 注入 RestClient

在得到自定义的 CloseableHttpClient 实例后，将其传递给 RestClient 的构建过程（以 Spring Boot 3.x 为例）：

import org.springframework.web.client.RestClient;
import org.springframework.boot.web.client.ClientHttpRequestFactory;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;

HttpComponentsClientHttpRequestFactory requestFactory = 
        new HttpComponentsClientHttpRequestFactory(httpClient);

RestClient restClient = RestClient.builder()
        .requestFactory(requestFactory)
        .build();

或者更简洁地使用 RestClient.builder().httpClient(httpClient)（Spring 6.2+ 直接支持）：

RestClient restClient = RestClient.builder()
        .httpClient(httpClient)
        .build();

至此，通过该 RestClient 发起的所有请求将不再自动重试。

三、进阶技巧：全局与局部配置

情况1：全局禁用所有自动重试

在 @Configuration 类中定义 RestClient Bean，应用所有组件共用同一个禁用重试的客户端。

情况2：仅禁用特定 API 的重试

若不想影响全局，可为特定调用创建独立的 RestClient 实例：

RestClient customClient = RestClient.builder()
        .httpClient(HttpClientBuilder.create().disableAutomaticRetries().build())
        .build();

情况3：结合 Spring Retry 实现自定义重试

底层禁用自动重试后，可在业务层使用 @Retryable 注解实现可控的重试（例如仅对 5xx 错误重试，且间隔递增）：

@Retryable(retryFor = HttpServerErrorException.class, maxAttempts = 3, backoff = @Backoff(delay = 1000))
public String callExternalApi() {
    return restClient.post().uri(url).retrieve().body(String.class);
}

四、值得注意的陷阱与最佳实践

  1. 确保 HttpClient 5 版本匹配：disableAutomaticRetries() 方法自 HttpClient 5.0 起可用，若使用旧版或误引入 HttpClient 4 的依赖，上述代码将不生效。请检查 pom.xml 或 build.gradle 中的版本号（推荐 5.2+）。

  2. 不要混淆连接超时与重试：禁用重试不会影响连接超时（connectTimeout）和读取超时（readTimeout）设置，需单独配置 RequestConfig。

  3. 生产环境谨慎测试：禁用重试可能增加请求失败率，尤其是在网络波动较大的环境中。建议配合熔断降级（如 Resilience4j）使用。

  4. 日志确认：开启 HttpClient 的调试日志（org.apache.hc.client5.http 级别设为 DEBUG），可观察是否还有重试行为。

五、总结

Apache HttpClient 5 的默认重试机制是一把双刃剑——它提升了容错性，但也可能破坏业务正确性。通过 disableAutomaticRetries() 与自定义 RestClient 结合，开发者可以轻松掌控请求行为，避免非幂等操作被重复执行。

对于需要精细控制重试策略的团队，建议在业务层统一管理重试逻辑，底层客户端仅作为一次性的 HTTP 执行者。这种分离架构既能保证代码清晰，又能满足各种复杂场景的需求。

本文的代码示例已通过 Apache HttpClient 5.3 及 Spring Boot 3.3 的实际测试，可放心应用。遇到版本兼容性问题的读者，欢迎在评论区留言交流。