Java 后端 / 系统课时
配置超时、重试与连接池
配置超时、重试与连接池
本课把基础 HTTP 调用改造成可用于生产的客户端:限制连接建立、连接租用和响应等待时间,复用受控连接池,并只对网络异常、429 和 5xx 等临时故障执行有边界的重试。
学习目标
- 区分连接超时、连接池等待超时和响应超时
- 使用 Apache HttpClient 5 配置连接池上限与空闲连接清理
- 仅对幂等且可能恢复的失败执行退避重试
设计保护链路
一次调用可能在三个位置等待:建立 TCP 连接、从连接池租用连接、等待远端响应。任何一个等待没有上限,都会持续占用业务线程。重试位于这些超时之后,但必须先判断请求是否幂等、失败是否具有临时性,并设置最大次数和退避间隔。

引入客户端与重试依赖
保留现有的 spring-boot-starter-web,再加入 Apache HttpClient 5 和 Spring Retry。使用 Spring Boot 的依赖管理时不要手写版本号,以免与当前 Boot 版本管理的组件冲突。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.apache.httpcomponents.client5</groupId>
<artifactId>httpclient5</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.retry</groupId>
<artifactId>spring-retry</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>依赖生效后,RestClient 仍负责上层请求 API,HttpComponentsClientHttpRequestFactory 负责把请求交给带连接池的 Apache HttpClient。
配置超时与连接池
下面两个文件组成完整客户端。连接超时限制建连时间,连接池等待超时限制线程等待可用连接的时间,响应超时限制收到响应前的等待时间。Apache 客户端自带重试被关闭,避免与业务层重试叠加。
// PartnerHttpConfiguration.java
package com.example.integration;
import java.time.Duration;
import org.apache.hc.client5.http.config.ConnectionConfig;
import org.apache.hc.client5.http.config.RequestConfig;
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManager;
import org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManagerBuilder;
import org.apache.hc.core5.util.TimeValue;
import org.apache.hc.core5.util.Timeout;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.retry.support.RetryTemplate;
import org.springframework.web.client.ResourceAccessException;
import org.springframework.web.client.RestClient;
@Configuration
public class PartnerHttpConfiguration {
@Bean
PoolingHttpClientConnectionManager partnerConnectionManager() {
ConnectionConfig connectionConfig = ConnectionConfig.custom()
.setConnectTimeout(Timeout.ofSeconds(2))
.setSocketTimeout(Timeout.ofSeconds(3))
.build();
return PoolingHttpClientConnectionManagerBuilder.create()
.setDefaultConnectionConfig(connectionConfig)
.setMaxConnTotal(100)
.setMaxConnPerRoute(20)
.build();
}
@Bean(destroyMethod = "close")
CloseableHttpClient partnerHttpClient(
PoolingHttpClientConnectionManager manager) {
RequestConfig requestConfig = RequestConfig.custom()
.setConnectionRequestTimeout(Timeout.ofMilliseconds(500))
.setResponseTimeout(Timeout.ofSeconds(3))
.build();
return HttpClients.custom()
.setConnectionManager(manager)
.setDefaultRequestConfig(requestConfig)
.disableAutomaticRetries()
.evictExpiredConnections()
.evictIdleConnections(TimeValue.ofSeconds(30))
.build();
}
@Bean
RestClient partnerRestClient(
RestClient.Builder builder,
CloseableHttpClient httpClient) {
return builder
.baseUrl("https://partner.example")
.requestFactory(
new HttpComponentsClientHttpRequestFactory(httpClient))
.build();
}
@Bean
RetryTemplate partnerGetRetryTemplate() {
return RetryTemplate.builder()
.maxAttempts(3)
.exponentialBackoff(
Duration.ofMillis(200),
2.0,
Duration.ofSeconds(1),
true)
.retryOn(ResourceAccessException.class)
.retryOn(PartnerClient.PartnerRetryableException.class)
.notRetryOn(PartnerClient.PartnerClientException.class)
.build();
}
}// PartnerClient.java
package com.example.integration;
import org.springframework.http.HttpStatusCode;
import org.springframework.retry.support.RetryTemplate;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestClient;
@Component
public class PartnerClient {
private final RestClient restClient;
private final RetryTemplate retryTemplate;
public PartnerClient(
RestClient partnerRestClient,
RetryTemplate partnerGetRetryTemplate) {
this.restClient = partnerRestClient;
this.retryTemplate = partnerGetRetryTemplate;
}
public OrderResponse getOrder(long id) {
return retryTemplate.execute(context -> restClient.get()
.uri("/orders/{id}", id)
.retrieve()
.onStatus(
status -> status.value() == 429
|| status.is5xxServerError(),
(request, response) -> {
throw new PartnerRetryableException(
response.getStatusCode().value());
})
.onStatus(HttpStatusCode::is4xxClientError,
(request, response) -> {
throw new PartnerClientException(
response.getStatusCode().value());
})
.body(OrderResponse.class));
}
public CreateOrderResponse createOrder(CreateOrderRequest request) {
// 普通 POST 不自动重试,避免重复创建资源。
return restClient.post()
.uri("/orders")
.body(request)
.retrieve()
.body(CreateOrderResponse.class);
}
public record OrderResponse(long id, String status) {
}
public record CreateOrderRequest(String productCode, int quantity) {
}
public record CreateOrderResponse(long id) {
}
public static final class PartnerRetryableException
extends RuntimeException {
PartnerRetryableException(int statusCode) {
super("Retryable partner status: " + statusCode);
}
}
public static final class PartnerClientException
extends RuntimeException {
PartnerClientException(int statusCode) {
super("Non-retryable partner status: " + statusCode);
}
}
}验证重试边界
下面的测试让第一次 GET 返回 503,第二次返回成功。它证明最大尝试次数包含首次调用,并验证临时服务端错误会进入重试。将文件保存为 src/test/java/com/example/integration/PartnerClientRetryTest.java。
package com.example.integration;
import org.junit.jupiter.api.Test;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.retry.support.RetryTemplate;
import org.springframework.test.web.client.MockRestServiceServer;
import org.springframework.web.client.RestClient;
import static org.assertj.core.api.Assertions.assertThat;
import static org.springframework.test.web.client.match.MockRestRequestMatchers.requestTo;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withStatus;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withSuccess;
class PartnerClientRetryTest {
@Test
void shouldRetryTemporaryServerFailure() {
RestClient.Builder builder = RestClient.builder();
MockRestServiceServer server =
MockRestServiceServer.bindTo(builder).build();
server.expect(requestTo("https://partner.example/orders/42"))
.andRespond(withStatus(HttpStatus.SERVICE_UNAVAILABLE));
server.expect(requestTo("https://partner.example/orders/42"))
.andRespond(withSuccess(
"{\"id\":42,\"status\":\"PAID\"}",
MediaType.APPLICATION_JSON));
RetryTemplate retryTemplate = RetryTemplate.builder()
.maxAttempts(3)
.fixedBackoff(10)
.retryOn(
PartnerClient.PartnerRetryableException.class)
.notRetryOn(
PartnerClient.PartnerClientException.class)
.build();
PartnerClient client = new PartnerClient(
builder.baseUrl("https://partner.example").build(),
retryTemplate);
PartnerClient.OrderResponse response = client.getOrder(42L);
assertThat(response.status()).isEqualTo("PAID");
server.verify();
System.out.println("status=" + response.status());
}
}执行测试:
./mvnw -q -Dtest=PartnerClientRetryTest test预期输出:
status=PAID划分可重试请求
GET、HEAD 等幂等读取通常可以重试;网络中断、连接超时、429 和短暂 5xx 也可能恢复。参数错误、认证失败、权限不足等 4xx 不应重试,因为重复请求不会改变结果。
POST、扣款和发消息等操作默认不可重试。只有服务端支持幂等键、客户端在每次尝试中复用同一个键,并且双方明确重复请求语义时,才可以把该操作加入重试。连接池上限应根据实例并发量和合作方承载能力压测确定,而不是简单设得越大越好。