Skip to content

Commit e46da01

Browse files
CopilotCopilot
authored
🎨 #3824 【基础架构】升级到 Apache HttpClient 5.x 作为默认 HTTP 客户端
1 parent 9870012 commit e46da01

20 files changed

Lines changed: 313 additions & 24 deletions

File tree

‎README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,52 @@
114114
- **微信开放平台**（`weixin-java-open`）主要用于第三方平台，代公众号或小程序进行开发和管理
115115

116116

117+
---------------------------------
118+
### HTTP 客户端支持
119+
120+
本项目同时支持多种 HTTP 客户端实现，默认推荐使用 **Apache HttpClient 5.x**（最新稳定版本）。
121+
122+
#### 支持的 HTTP 客户端类型
123+
124+
| HTTP 客户端 | 说明 | 配置值 | 推荐程度 |
125+
|------------|------|--------|---------|
126+
| Apache HttpClient 5.x | Apache HttpComponents Client 5.x，最新版本 | `HttpComponents` | ⭐⭐⭐⭐⭐ 推荐 |
127+
| Apache HttpClient 4.x | Apache HttpClient 4.x，向后兼容 | `HttpClient` | ⭐⭐⭐⭐ 兼容 |
128+
| OkHttp | Square OkHttp 客户端 | `OkHttp` | ⭐⭐⭐ 可选 |
129+
| Jodd-http | Jodd 轻量级 HTTP 客户端 | `JoddHttp` | ⭐⭐ 可选 |
130+
131+
#### 配置方式
132+
133+
**Spring Boot 配置示例：**
134+
135+
```properties
136+
# 使用 HttpClient 5.x（推荐，MP/CP/Channel/QiDian 模块默认）
137+
wx.mp.config-storage.http-client-type=HttpComponents
138+
139+
# 使用 HttpClient 4.x（兼容模式，MiniApp 模块默认）
140+
wx.mp.config-storage.http-client-type=HttpClient
141+
142+
# 使用 OkHttp
143+
wx.mp.config-storage.http-client-type=OkHttp
144+
145+
# 使用 Jodd-http
146+
wx.mp.config-storage.http-client-type=JoddHttp
147+
```
148+
149+
**注意**：如果使用 Multi-Starter（如 `wx-java-mp-multi-spring-boot-starter`），枚举值需使用大写下划线格式：
150+
```properties
151+
# Multi-Starter 配置格式
152+
wx.mp.config-storage.http-client-type=HTTP_COMPONENTS # 注意使用大写下划线
153+
```
154+
155+
**注意事项：**
156+
1. **MiniApp 模块**已提供 `HttpComponents`（HttpClient 5.x）类型的配置选项，但当前默认仍为 HttpClient 4.x；如需启用 HttpClient 5.x，请确保所使用的集成模块（如 `wx-java-miniapp-spring-boot-starter`、`wx-java-miniapp-solon-plugin`）版本已支持该选项
157+
2. **MP、Channel、QiDian 模块**已完整支持 HttpClient 5.x，默认推荐使用
158+
3. **CP 模块**的支持情况取决于具体使用的 Starter 版本，请参考对应模块文档
159+
4. 如需使用 OkHttp 或 Jodd-http，需在项目中添加对应的依赖（scope为provided）
160+
5. HttpClient 4.x 和 HttpClient 5.x 可以共存，按需配置即可
161+
162+
117163
---------------------------------
118164
### 版本说明
119165

‎docs/HTTPCLIENT_UPGRADE_GUIDE.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# HttpClient 升级指南
2+
3+
## 概述
4+
5+
从 WxJava 4.7.x 版本开始，项目开始支持并推荐使用 **Apache HttpClient 5.x**（HttpComponents Client 5），同时保持对 HttpClient 4.x 的向后兼容。
6+
7+
## 为什么升级？
8+
9+
1. **Apache HttpClient 5.x 是最新稳定版本**：提供更好的性能和更多的功能
10+
2. **HttpClient 4.x 已经进入维护模式**：不再积极开发新功能
11+
3. **更好的安全性**：HttpClient 5.x 包含最新的安全更新和改进
12+
4. **向前兼容**：为未来的开发做好准备
13+
14+
## 支持的 HTTP 客户端
15+
16+
| HTTP 客户端 | 版本 | 配置值 | 状态 | 说明 |
17+
|------------|------|--------|------|------|
18+
| Apache HttpClient 5.x | 5.5 | `HttpComponents` | ⭐ 推荐 | 最新稳定版本 |
19+
| Apache HttpClient 4.x | 4.5.13 | `HttpClient` | ✅ 支持 | 向后兼容 |
20+
| OkHttp | 4.12.0 | `OkHttp` | ✅ 支持 | 需自行添加依赖 |
21+
| Jodd-http | 6.3.0 | `JoddHttp` | ✅ 支持 | 需自行添加依赖 |
22+
23+
## 模块支持情况
24+
25+
| 模块 | HttpClient 5.x 支持 | 默认客户端 |
26+
|------|-------------------|-----------|
27+
| weixin-java-mp（公众号） | ✅ 是 | HttpComponents (5.x) |
28+
| weixin-java-cp（企业微信） | ⚠️ 视集成方式而定 | 参考对应 starter 配置 |
29+
| weixin-java-channel（视频号） | ✅ 是 | HttpComponents (5.x) |
30+
| weixin-java-qidian（企点） | ✅ 是 | HttpComponents (5.x) |
31+
| weixin-java-miniapp（小程序） | ✅ 是 | HttpClient (4.x) |
32+
| weixin-java-pay（支付） | ✅ 是 | HttpComponents (5.x) |
33+
| weixin-java-open（开放平台） | ✅ 是 | HttpComponents (5.x) |
34+
35+
**注意**：
36+
- **weixin-java-miniapp 模块**已在核心 SDK 中提供 HttpClient 5.x（`HttpComponents`）支持，但默认仍使用 HttpClient 4.x（`HttpClient`）。如需启用 HttpClient 5.x，可通过配置 `http-client-type=HttpComponents` 显式指定。
37+
- **weixin-java-cp 模块**的支持情况取决于具体使用的 Starter 版本，请参考对应模块文档。
38+
39+
## 对现有项目的影响
40+
41+
### 对新项目
42+
- **无需任何修改**，直接使用最新版本即可
43+
- 支持 HttpClient 5.x 的模块会自动使用 HttpComponents (5.x)
44+
45+
### 对现有项目
46+
- **向后兼容**：不需要修改任何代码
47+
- HttpClient 4.x 依然可用，项目同时包含两个版本的依赖
48+
- 如果希望继续使用 HttpClient 4.x，只需在配置中显式指定
49+
50+
## 迁移步骤
51+
52+
### 1. 更新 WxJava 版本
53+
54+
在 `pom.xml` 中更新版本：
55+
56+
```xml
57+
<dependency>
58+
<groupId>com.github.binarywang</groupId>
59+
<artifactId>weixin-java-mp</artifactId>
60+
<version>最新版本</version> <!-- 请参考 Maven Central 或项目 README 获取最新版本号 -->
61+
</dependency>
62+
```
63+
64+
### 2. 检查配置（可选）
65+
66+
#### Spring Boot 项目
67+
68+
在 `application.properties` 或 `application.yml` 中：
69+
70+
```properties
71+
# 使用 HttpClient 5.x（推荐，无需配置，已经是默认值）
72+
wx.mp.config-storage.http-client-type=HttpComponents
73+
74+
# 或者继续使用 HttpClient 4.x
75+
wx.mp.config-storage.http-client-type=HttpClient
76+
```
77+
78+
#### 纯 Java 项目
79+
80+
```java
81+
// 使用 HttpClient 5.x（推荐）
82+
WxMpService wxMpService = new WxMpServiceHttpComponentsImpl();
83+
84+
// 或者继续使用 HttpClient 4.x
85+
WxMpService wxMpService = new WxMpServiceHttpClientImpl();
86+
```
87+
88+
### 3. 测试应用
89+
90+
升级后，建议进行全面测试以确保一切正常工作。
91+
92+
## 常见问题
93+
94+
### Q: 升级后会不会破坏现有代码？
95+
A: 不会。项目保持完全向后兼容，HttpClient 4.x 的所有实现都保持不变。
96+
97+
### Q: 我需要修改代码吗？
98+
A: 大多数情况下不需要。如果希望继续使用 HttpClient 4.x，只需在配置中指定 `http-client-type=HttpClient` 即可。
99+
100+
### Q: MiniApp 模块支持 HttpClient 5.x 吗？
101+
A: 支持。MiniApp 模块在核心 SDK 中已经提供了基于 HttpClient 5.x（`HttpComponents`）的支持，但默认仍会使用 HttpClient 4.x（`HttpClient`）以保持向后兼容。如果你使用的是框架集成（例如 Spring Boot Starter 或 Solon Plugin），可以通过显式配置 `http-client-type=HttpComponents` 来启用 HttpClient 5.x。
102+
103+
### Q: 我可以在同一个项目中同时使用两个版本吗？
104+
A: 可以。不同的模块可以配置使用不同的 HTTP 客户端。例如，MP 模块使用 HttpClient 5.x，MiniApp 模块默认使用 HttpClient 4.x，但也可以按需配置为 HttpClient 5.x。
105+
106+
### Q: 如何排除不需要的依赖？
107+
A: 如果只想使用一个版本，可以在 `pom.xml` 中排除另一个：
108+
109+
```xml
110+
<dependency>
111+
<groupId>com.github.binarywang</groupId>
112+
<artifactId>weixin-java-mp</artifactId>
113+
<version>最新版本</version>
114+
<exclusions>
115+
<!-- 排除 HttpClient 4.x -->
116+
<exclusion>
117+
<groupId>org.apache.httpcomponents</groupId>
118+
<artifactId>httpclient</artifactId>
119+
</exclusion>
120+
<exclusion>
121+
<groupId>org.apache.httpcomponents</groupId>
122+
<artifactId>httpmime</artifactId>
123+
</exclusion>
124+
</exclusions>
125+
</dependency>
126+
```
127+
128+
## 配置参考
129+
130+
### Spring Boot 完整配置示例
131+
132+
```properties
133+
# 公众号配置
134+
wx.mp.app-id=your_app_id
135+
wx.mp.secret=your_secret
136+
wx.mp.token=your_token
137+
wx.mp.aes-key=your_aes_key
138+
139+
# HTTP 客户端配置
140+
wx.mp.config-storage.http-client-type=HttpComponents # HttpComponents, HttpClient, OkHttp, JoddHttp
141+
142+
# HTTP 代理配置（可选）
143+
wx.mp.config-storage.http-proxy-host=proxy.example.com
144+
wx.mp.config-storage.http-proxy-port=8080
145+
wx.mp.config-storage.http-proxy-username=proxy_user
146+
wx.mp.config-storage.http-proxy-password=proxy_pass
147+
148+
# 超时配置（可选）
149+
wx.mp.config-storage.connection-timeout=5000
150+
wx.mp.config-storage.so-timeout=5000
151+
wx.mp.config-storage.connection-request-timeout=5000
152+
```
153+
154+
## 技术细节
155+
156+
### HttpClient 4.x 与 5.x 的主要区别
157+
158+
1. **包名变更**：
159+
- HttpClient 4.x: `org.apache.http.*`
160+
- HttpClient 5.x: `org.apache.hc.client5.*`, `org.apache.hc.core5.*`
161+
162+
2. **API 改进**：
163+
- HttpClient 5.x 提供更现代的 API 设计
164+
- 更好的异步支持
165+
- 改进的连接池管理
166+
167+
3. **性能优化**：
168+
- HttpClient 5.x 包含多项性能优化
169+
- 更好的资源管理
170+
171+
### 项目中的实现
172+
173+
WxJava 项目通过策略模式支持多种 HTTP 客户端：
174+
175+
```
176+
weixin-java-common/
177+
├── util/http/
178+
│ ├── apache/ # HttpClient 4.x 实现
179+
│ ├── hc/ # HttpClient 5.x (HttpComponents) 实现
180+
│ ├── okhttp/ # OkHttp 实现
181+
│ └── jodd/ # Jodd-http 实现
182+
```
183+
184+
每个模块都有对应的 Service 实现类：
185+
- `*ServiceHttpClientImpl` - 使用 HttpClient 4.x
186+
- `*ServiceHttpComponentsImpl` - 使用 HttpClient 5.x
187+
- `*ServiceOkHttpImpl` - 使用 OkHttp
188+
- `*ServiceJoddHttpImpl` - 使用 Jodd-http
189+
190+
## 反馈与支持
191+
192+
如果在升级过程中遇到问题，请：
193+
194+
1. 查看 [项目 Wiki](https://github.com/binarywang/WxJava/wiki)
195+
2. 在 [GitHub Issues](https://github.com/binarywang/WxJava/issues) 中搜索或提交问题
196+
3. 加入技术交流群（见 README.md）
197+
198+
## 总结
199+
200+
- ✅ **推荐使用 HttpClient 5.x**：性能更好，功能更强
201+
- ✅ **向后兼容**：可以继续使用 HttpClient 4.x
202+
- ✅ **灵活配置**：支持多种 HTTP 客户端，按需选择
203+
- ✅ **平滑迁移**：无需修改代码，仅需配置即可

‎pom.xml‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@
136136

137137
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
138138
<httpclient.version>4.5.13</httpclient.version>
139+
<httpclient5.version>5.5</httpclient5.version>
139140
<jetty.version>9.4.57.v20241219</jetty.version> <!-- 这个不能用10以上的版本，不支持jdk8-->
140141
</properties>
141142
<dependencyManagement>
@@ -157,13 +158,14 @@
157158
<version>4.12.0</version>
158159
<scope>provided</scope>
159160
</dependency>
161+
<!-- HttpClient 5.x - 默认依赖（推荐使用） -->
160162
<dependency>
161163
<groupId>org.apache.httpcomponents.client5</groupId>
162164
<artifactId>httpclient5</artifactId>
163-
<version>5.5</version>
164-
<scope>provided</scope>
165+
<version>${httpclient5.version}</version>
165166
</dependency>
166167

168+
<!-- HttpClient 4.x - 默认依赖（为了保持向后兼容） -->
167169
<dependency>
168170
<groupId>org.apache.httpcomponents</groupId>
169171
<artifactId>httpclient</artifactId>

‎solon-plugins/wx-java-channel-solon-plugin/src/main/java/com/binarywang/solon/wxjava/channel/enums/HttpClientType.java‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,11 @@
77
*/
88
public enum HttpClientType {
99
/**
10-
* HttpClient
10+
* HttpClient.
1111
*/
12-
HttpClient
12+
HttpClient,
13+
/**
14+
* HttpComponents.
15+
*/
16+
HttpComponents,
1317
}

‎solon-plugins/wx-java-channel-solon-plugin/src/main/java/com/binarywang/solon/wxjava/channel/properties/WxChannelProperties.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ public static class ConfigStorage {
7373
/**
7474
* http客户端类型
7575
*/
76-
private HttpClientType httpClientType = HttpClientType.HttpClient;
76+
private HttpClientType httpClientType = HttpClientType.HttpComponents;
7777

7878
/**
7979
* http代理主机

‎solon-plugins/wx-java-miniapp-solon-plugin/src/main/java/com/binarywang/solon/wxjava/miniapp/enums/HttpClientType.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,8 @@ public enum HttpClientType {
1919
* JoddHttp.
2020
*/
2121
JoddHttp,
22+
/**
23+
* HttpComponents.
24+
*/
25+
HttpComponents,
2226
}

‎solon-plugins/wx-java-mp-solon-plugin/src/main/java/com/binarywang/solon/wxjava/mp/enums/HttpClientType.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,8 @@ public enum HttpClientType {
1919
* JoddHttp.
2020
*/
2121
JoddHttp,
22+
/**
23+
* HttpComponents.
24+
*/
25+
HttpComponents,
2226
}

‎solon-plugins/wx-java-mp-solon-plugin/src/main/java/com/binarywang/solon/wxjava/mp/properties/WxMpProperties.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ public static class ConfigStorage implements Serializable {
7979
/**
8080
* http客户端类型.
8181
*/
82-
private HttpClientType httpClientType = HttpClientType.HttpClient;
82+
private HttpClientType httpClientType = HttpClientType.HttpComponents;
8383

8484
/**
8585
* http代理主机.

‎solon-plugins/wx-java-qidian-solon-plugin/src/main/java/com/binarywang/solon/wxjava/qidian/enums/HttpClientType.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,4 +19,8 @@ public enum HttpClientType {
1919
* JoddHttp.
2020
*/
2121
JoddHttp,
22+
/**
23+
* HttpComponents.
24+
*/
25+
HttpComponents,
2226
}

‎solon-plugins/wx-java-qidian-solon-plugin/src/main/java/com/binarywang/solon/wxjava/qidian/properties/WxQidianProperties.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ public static class ConfigStorage implements Serializable {
7474
/**
7575
* http客户端类型.
7676
*/
77-
private HttpClientType httpClientType = HttpClientType.HttpClient;
77+
private HttpClientType httpClientType = HttpClientType.HttpComponents;
7878

7979
/**
8080
* http代理主机.

0 commit comments

Comments
 (0)