# http-client-spring-boot-starter-parent
**Repository Path**: yqlcode/http-client-spring-boot-starter-parent
## Basic Information
- **Project Name**: http-client-spring-boot-starter-parent
- **Description**: 封装基于 httpclient5 的 RestTemplate和 webflux WebClient 的 工具Starter
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-11-12
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
#### 1. 概述
starter对`WebClient` 与`RestTemplate`的使用进行了包装,简化和统一call外部服务的实现,开箱即用
其中`RestTemplate`基于 `httpclient5`来进行实现
支持的功能:
* 配置 client 连接池
* 配置 call 外部服务的 retry 策略
* 配置 ssl 校验
starter 80%的代码由`deepseek`生成,20%的代码及结构手动调整
#### 2. 配置说明
##### 2.1 client连接属性配置
支持的配置
* 设置client连接池
* 配置retry策略 (全局retry配置)
* 可以设置全局的retry,也支持设置单个服务的retry策略,服务的策略优先于全局retry配置
* 对于WebClient
* `WebClientResponseException` 异常外的其他异常,默认会retry (此异常表示没有响应,一般为网络异常,连接超时,读取超时,连接被拒绝等异常等)
* 对于RestTemplate
* `RestClientException` 异常会retry,其他不会, (与上面一样,这个异常一般为网络异常,连接超时,读取超时,连接被拒绝等异常等)
* 匹配配置中的`retry-status-codes`中的response http status, 加上默认的`429`,都会retry
* http status `429` 表示当前Too Many Requests,这种情况默认给它重试机会
一个可用的配置参数sample如下,配置属性的具体含义,查看`HttpClientProperties`
对于配置的时间参数,单位都是秒
WebClient连接配置:
```yaml
http:
client:
type: webclient # webclient 或 rest_template
connect-timeout: 10
read-timeout: 30
pool:
max-total: 100
max-idle-time: 30 # 连接最大空闲时间
max-life-time: 60 # 连接最大生命周期
acquire-timeout: 10
retry:
enabled: true
max-attempts: 3
backoff-initial: 1
backoff-multiplier: 2.0
backoff-max: 30
retry-status-codes:
- 500
- 502
- 503
```
RestTemplate连接配置:
```yaml
http:
client:
type: rest_template # webclient 或 rest_template
connect-timeout: 10
read-timeout: 30
pool:
max-total: 100
max-idle-time: 30 # 连接最大空闲时间
max-life-time: 60 # 连接最大生命周期
default-max-per-route: 50 # RestTemplate特有, 每路由连接数
validate-after-inactivity: 3 # RestTemplate特有, 使用连接前检查是否已失效
acquire-timeout: 10
retry:
enabled: true
max-attempts: 3
backoff-initial: 1
backoff-multiplier: 2.0
backoff-max: 30
retry-status-codes:
- 500
- 502
- 503
```
##### 2.2 请求api配置
支持的配置
* 配置url
* 支持配置api的全路径
* 支持配置前缀,后面的api path部分在入参中指定
* 配置request header
* 配置ssl (支持`单项认证`与`双向认证`), 对于https的url, 默认都会trust all
* 如果需要进行ssl校验,需设置 `trust-all: false`
* 支持配置call单个外部服务的retry策略 (优先级高于全局配置)
一个请求的配置参数sample格式如下,配置属性的具体含义,查看`HttpProperties`
```yaml
http:
# 淘宝服务配置
dev:
url: http://localhost:8080/api/orders/health # url配置api全路径
headers:
app-key: your-taobao-app-key
app-secret: your-taobao-secret
retry:
enabled: true
max-attempts: 3
backoff-initial: 3
backoff-multiplier: 2.0
backoff-max: 30
retry-status-codes:
- 500
# 自签名证书(配置 trustStorePath 即可)
internal:
url: https://internal.company.com # url配置api 前缀, api部分在请求接口的path参数中指定
ssl:
trust-all: false
trust-store-path: /etc/ssl/truststore.jks
trust-store-password: changeit
# 双向认证(配置 keyStorePath)
secure:
url: https://secure.company.com # url配置api 前缀, api部分在请求接口的path参数中指定
ssl:
trust-all: false
trust-store-path: /etc/ssl/truststore.jks
trust-store-password: changeit
key-store-path: /etc/ssl/client.p12
key-store-password: client123
```
#### 使用说明
只需引入starter的依赖既可以,spring boot自动装配机制会通过starter中定义的`HttpClientAutoConfiguration`进行自动装配
1. 引入starter的依赖
```xml
io.github.http-client
http-client-spring-boot-starter
1.0.0
```
2. 定义配置类,读取配置的需要call的服务信息
```java
@Component
@ConfigurationProperties(prefix = "http.upload")
public class UploadProperties extends HttpProperties {
}
```
3. call 服务
call外部服务的参数信息,通过`HttpRequestBuilder` 来构建
call api有两个方法`execute` & `executeRaw`; 对于WebClient,还有两个对应的异步阻塞方法`executeAsync` & `executeAsync`
call api的使用sample
```java
@Service
public class SampleService {
@Autowired
private final HttpClient httpClient;
// get请求
Map queryParams = new HashMap<>();
HttpRequestBuilder requestBuilder = new HttpRequestBuilder()
.get()
.queryParams(queryParams);
HttpResponse response = httpClient.execute(
UploadProperties,
requestBuilder,
ResponseDTO.class
);
// get请求, 直接使用method方法来指定 httpMethod
Map queryParams = new HashMap<>();
HttpRequestBuilder requestBuilder = new HttpRequestBuilder()
.method(HttpMethod.GET)
.queryParams(queryParams);
HttpResponse response = httpClient.execute(
UploadProperties,
requestBuilder,
ResponseDTO.class
);
// post json 请求
HttpRequestBuilder requestBuilder = new HttpRequestBuilder()
.postJson() // 也可以写成 .post().contentTypeJson()
.body(RequestDTO);
HttpResponse response = httpClient.execute(
UploadProperties,
requestBuilder,
ResponseDTO.class
);
// post json 请求,直接返回目标api的raw body (String 类型)
HttpRequestBuilder requestBuilder = new HttpRequestBuilder()
.postJson() // 也可以写成 .post().contentTypeJson()
.body(RequestDTO);
HttpResponse response = httpClient.executeRaw(
UploadProperties,
requestBuilder
);
// post form 请求
Map formFields = new HashMap<>();
HttpRequestBuilder requestBuilder = new HttpRequestBuilder()
.postForm() // 也可以写成 .post().contentTypeForm()
.body(formFields);
HttpResponse response = httpClient.execute(
UploadProperties,
requestBuilder,
ResponseDTO.class
);
// post 带文件上传, 带form表单参数
Map formFields = new HashMap<>();
HttpRequestBuilder requestBuilder = new HttpRequestBuilder()
.post()
.addFile("file", file)
.addFormFields(formFields);
HttpResponse response = httpClient.execute(
UploadProperties,
requestBuilder,
ResponseDTO.class
);
// post 多文件上传, 带form表单参数
Map formFields = new HashMap<>();
HttpRequestBuilder requestBuilder = new HttpRequestBuilder()
.post()
.addFile("file1", file1)
.addFile("file2", file2)
.addFile("file3", file3)
.addFormFields(formFields);
HttpResponse response = httpClient.execute(
UploadProperties,
requestBuilder,
ResponseDTO.class
);
}
```
WebClient支持异步阻塞模式,用于Spring WebFlux项目,使用方法与上面一样方法签名变为 `executeAsync` & `executeRawAsync`
如果是Spring Mvc项目,直接使用同步方法`execute` & `executeRaw` 就可以~
RestTemplate中不支持异步,会抛出异常
```java
@Service
public class SampleService {
@Autowired
private final HttpClient httpClient;
// get请求
Map queryParams = new HashMap<>();
HttpRequestBuilder requestBuilder = new HttpRequestBuilder()
.get()
.queryParams(queryParams);
Mono> response = httpClient.executeAsync(
UploadProperties,
requestBuilder,
ResponseDTO.class
);
// .......
}
```