yang_base/http/client.rs
1//! HTTP 客户端核心实现
2//!
3//! 提供 HTTP 客户端和请求构建能力;实例在启动期经
4//! [`ToolsBuilder::http`](crate::tools::ToolsBuilder) 注册进应用资源,
5//! 运行期通过 `Tools::http()` 或 `ActionContext::http()` 获取。
6
7use crate::error::BaseError;
8use crate::http::request::RequestBuilder;
9use reqwest::{Client, Method};
10use std::sync::{Arc, RwLock};
11use std::time::Duration;
12
13/// HTTP 客户端配置
14///
15/// 用于通过 `HttpClient::with_config` 创建自定义配置的客户端
16///
17/// # 示例
18///
19/// ```rust,ignore
20/// use yang_base::http::{HttpClient, HttpClientConfig};
21///
22/// let config = HttpClientConfig {
23/// timeout_secs: 60,
24/// pool_max_idle_per_host: 10,
25/// user_agent: Some("MyApp/1.0".to_string()),
26/// ..Default::default()
27/// };
28/// let client = HttpClient::with_config(config)?;
29/// ```
30#[derive(Debug, Clone)]
31#[non_exhaustive]
32pub struct HttpClientConfig {
33 /// 请求超时时间(秒),默认 30 秒
34 pub timeout_secs: u64,
35
36 /// 每个主机最大空闲连接数,默认 10
37 pub pool_max_idle_per_host: usize,
38
39 /// 连接池空闲超时时间(秒),默认 90 秒
40 pub pool_idle_timeout_secs: u64,
41
42 /// 自定义 User-Agent,默认为 None(使用 reqwest 默认值)
43 pub user_agent: Option<String>,
44
45 /// 是否接受无效的 TLS 证书,默认 false(生产环境不应设为 true)
46 pub accept_invalid_certs: bool,
47
48 /// 代理 URL,默认为 None(不使用代理)
49 pub proxy_url: Option<String>,
50
51 /// 熔断器策略,默认 None(不启用)。设为 `Some(..)` 后,对连续失败的目标
52 /// host 快速失败(返回 `BaseError::HttpCircuitBreakerOpen`),按 host 分键。
53 pub circuit_breaker: Option<crate::http::CircuitBreakerConfig>,
54}
55
56impl Default for HttpClientConfig {
57 fn default() -> Self {
58 Self {
59 timeout_secs: 30,
60 pool_max_idle_per_host: 10,
61 pool_idle_timeout_secs: 90,
62 user_agent: None,
63 accept_invalid_certs: false,
64 proxy_url: None,
65 circuit_breaker: None,
66 }
67 }
68}
69
70impl HttpClientConfig {
71 /// 验证 HTTP 客户端配置。
72 ///
73 /// 拒绝会导致请求立即失败或连接池配置退化的零值参数。
74 pub fn validate(&self) -> Result<(), BaseError> {
75 if self.timeout_secs == 0 {
76 return Err(BaseError::ParamInvalid(
77 "http.timeout_secs".to_string(),
78 "HTTP 请求超时时间必须大于 0 秒".to_string(),
79 ));
80 }
81 if self.pool_max_idle_per_host == 0 {
82 return Err(BaseError::ParamInvalid(
83 "http.pool_max_idle_per_host".to_string(),
84 "每个主机最大空闲连接数必须大于 0".to_string(),
85 ));
86 }
87 if self.pool_idle_timeout_secs == 0 {
88 return Err(BaseError::ParamInvalid(
89 "http.pool_idle_timeout_secs".to_string(),
90 "连接池空闲超时时间必须大于 0 秒".to_string(),
91 ));
92 }
93 if let Some(circuit_breaker) = &self.circuit_breaker {
94 circuit_breaker.validate()?;
95 }
96
97 Ok(())
98 }
99}
100
101#[cfg(test)]
102mod config_tests {
103 use super::*;
104
105 #[test]
106 fn test_http_client_config_validate_rejects_zero_values() {
107 let invalid_configs = [
108 HttpClientConfig {
109 timeout_secs: 0,
110 ..HttpClientConfig::default()
111 },
112 HttpClientConfig {
113 pool_max_idle_per_host: 0,
114 ..HttpClientConfig::default()
115 },
116 HttpClientConfig {
117 pool_idle_timeout_secs: 0,
118 ..HttpClientConfig::default()
119 },
120 ];
121
122 for config in invalid_configs {
123 let err = config.validate().expect_err("HTTP 客户端零值配置应被拒绝");
124
125 assert!(matches!(err, BaseError::ParamInvalid(_, _)));
126 }
127 }
128
129 #[test]
130 fn test_with_config_rejects_invalid_config_before_building_client() {
131 let config = HttpClientConfig {
132 timeout_secs: 0,
133 ..HttpClientConfig::default()
134 };
135
136 let err = HttpClient::with_config(config)
137 .expect_err("无效 HTTP 配置应在构建 reqwest client 前被拒绝");
138
139 assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "http.timeout_secs"));
140 }
141
142 #[test]
143 fn test_http_client_config_validate_rejects_invalid_circuit_breaker_config() {
144 let config = HttpClientConfig {
145 circuit_breaker: Some(crate::http::CircuitBreakerConfig {
146 failure_threshold: 0,
147 ..crate::http::CircuitBreakerConfig::default()
148 }),
149 ..HttpClientConfig::default()
150 };
151
152 let err = config
153 .validate()
154 .expect_err("HTTP 客户端应拒绝非法熔断器配置");
155
156 assert!(matches!(
157 err,
158 BaseError::ParamInvalid(field, _) if field == "http.circuit_breaker.failure_threshold"
159 ));
160 }
161}
162
163/// HTTP 客户端
164///
165/// 提供 HTTP 请求构建和发送能力。
166///
167/// 内部持有 `Arc<reqwest::Client>`,`clone()` 时复用同一连接池(即 `Arc::clone`),
168/// 不会创建新的底层连接池。
169///
170/// # 示例
171///
172/// ```rust,ignore
173/// use yang_base::http::HttpClient;
174/// use yang_base::tools::ToolsBuilder;
175///
176/// // 启动期:把客户端注册进应用资源并冻结
177/// let tools = ToolsBuilder::new().http(HttpClient::new(30)?).build()?;
178///
179/// // 运行期:从 Tools 获取客户端发起请求(Action 内为 ctx.http()?)
180/// let response = tools.http()?
181/// .get("https://api.example.com/users")
182/// .send()
183/// .await?;
184/// ```
185#[derive(Clone, Debug)]
186pub struct HttpClient {
187 /// reqwest 客户端(Arc 包装,clone 时复用同一连接池)
188 client: Client,
189
190 /// 默认超时时间
191 default_timeout: Duration,
192
193 /// 默认 Token(可选)
194 default_token: Arc<RwLock<Option<String>>>,
195
196 /// 熔断器(可选,默认 None)。clone 时共享同一份状态。
197 circuit_breaker: Option<crate::http::CircuitBreaker>,
198}
199
200impl HttpClient {
201 /// 使用结构化配置创建 HTTP 客户端
202 ///
203 /// # 参数
204 ///
205 /// - `cfg`: HTTP 客户端配置
206 ///
207 /// # 返回
208 ///
209 /// - `Ok(HttpClient)`: 客户端实例
210 /// - `Err(BaseError::HttpClientCreateFailed)`: 创建失败(如代理 URL 无效)
211 ///
212 /// # 示例
213 ///
214 /// ```rust,ignore
215 /// use yang_base::http::{HttpClient, HttpClientConfig};
216 ///
217 /// let config = HttpClientConfig {
218 /// timeout_secs: 60,
219 /// pool_max_idle_per_host: 20,
220 /// ..Default::default()
221 /// };
222 /// let client = HttpClient::with_config(config)?;
223 /// ```
224 pub fn with_config(cfg: HttpClientConfig) -> Result<Self, BaseError> {
225 cfg.validate()?;
226
227 // 构建 reqwest 客户端
228 let mut builder = Client::builder()
229 .timeout(Duration::from_secs(cfg.timeout_secs))
230 .pool_max_idle_per_host(cfg.pool_max_idle_per_host)
231 .pool_idle_timeout(Duration::from_secs(cfg.pool_idle_timeout_secs))
232 .danger_accept_invalid_certs(cfg.accept_invalid_certs);
233
234 // 设置自定义 User-Agent
235 if let Some(ua) = cfg.user_agent {
236 builder = builder.user_agent(ua);
237 }
238
239 // 设置代理
240 if let Some(proxy_url) = cfg.proxy_url {
241 let proxy =
242 reqwest::Proxy::all(&proxy_url).map_err(BaseError::HttpClientCreateFailed)?;
243 builder = builder.proxy(proxy);
244 }
245
246 let client = builder.build().map_err(BaseError::HttpClientCreateFailed)?;
247
248 let circuit_breaker = cfg
249 .circuit_breaker
250 .map(crate::http::CircuitBreaker::new)
251 .transpose()?;
252
253 Ok(Self {
254 client,
255 default_timeout: Duration::from_secs(cfg.timeout_secs),
256 default_token: Arc::new(RwLock::new(None)),
257 circuit_breaker,
258 })
259 }
260
261 /// 创建新的 HTTP 客户端
262 ///
263 /// 委托给 `with_config`,使用默认配置并仅覆盖超时时间。
264 ///
265 /// # 参数
266 ///
267 /// - `timeout_secs`: 默认超时时间(秒)
268 ///
269 /// # 返回
270 ///
271 /// - `Ok(HttpClient)`: 客户端实例
272 /// - `Err(BaseError)`: 创建失败
273 ///
274 /// # 示例
275 ///
276 /// ```rust,ignore
277 /// let client = HttpClient::new(30)?;
278 /// ```
279 pub fn new(timeout_secs: u64) -> Result<Self, BaseError> {
280 // 委托给 with_config,仅覆盖超时时间
281 Self::with_config(HttpClientConfig {
282 timeout_secs,
283 ..Default::default()
284 })
285 }
286
287 /// 设置默认 Token
288 ///
289 /// # 参数
290 ///
291 /// - `token`: Token 字符串
292 ///
293 /// # 示例
294 ///
295 /// ```rust,ignore
296 /// let mut client = HttpClient::new(30)?;
297 /// client.set_default_token("your_token".to_string());
298 /// ```
299 pub fn set_default_token(&self, token: String) {
300 // 使用 unwrap_or_else 处理锁中毒:即使锁中毒也能恢复数据并继续写入
301 let mut default_token = self
302 .default_token
303 .write()
304 .unwrap_or_else(|p| p.into_inner());
305 *default_token = Some(token);
306 log::debug!("已设置默认 Token");
307 }
308
309 /// 获取默认 Token
310 fn get_default_token(&self) -> Option<String> {
311 // 使用 unwrap_or_else 处理锁中毒:即使锁中毒也能恢复数据并继续读取
312 let default_token = self.default_token.read().unwrap_or_else(|p| p.into_inner());
313 default_token.clone()
314 }
315
316 /// 创建请求构建器
317 ///
318 /// 注意:`self.client.clone()` 是 `Arc::clone`,复用同一底层连接池,
319 /// 不会创建新的 TCP 连接池,多个请求共享连接。
320 ///
321 /// # 参数
322 ///
323 /// - `method`: HTTP 方法
324 /// - `url`: 请求 URL
325 ///
326 /// # 返回
327 ///
328 /// - `RequestBuilder`: 请求构建器
329 ///
330 /// # 示例
331 ///
332 /// ```rust,ignore
333 /// use reqwest::Method;
334 ///
335 /// let response = client
336 /// .request(Method::GET, "https://api.example.com/users")
337 /// .send()
338 /// .await?;
339 /// ```
340 pub fn request(&self, method: Method, url: &str) -> RequestBuilder {
341 // self.client.clone() 是 Arc::clone,复用同一连接池
342 RequestBuilder::new(
343 self.client.clone(),
344 method,
345 url.to_string(),
346 self.default_timeout,
347 self.get_default_token(),
348 self.circuit_breaker.clone(),
349 )
350 }
351
352 /// GET 请求
353 ///
354 /// # 参数
355 ///
356 /// - `url`: 请求 URL
357 ///
358 /// # 返回
359 ///
360 /// - `RequestBuilder`: 请求构建器
361 ///
362 /// # 示例
363 ///
364 /// ```rust,ignore
365 /// let response = client
366 /// .get("https://api.example.com/users")
367 /// .send()
368 /// .await?;
369 /// ```
370 pub fn get(&self, url: &str) -> RequestBuilder {
371 self.request(Method::GET, url)
372 }
373
374 /// POST 请求
375 ///
376 /// # 参数
377 ///
378 /// - `url`: 请求 URL
379 ///
380 /// # 返回
381 ///
382 /// - `RequestBuilder`: 请求构建器
383 ///
384 /// # 示例
385 ///
386 /// ```rust,ignore
387 /// let response = client
388 /// .post("https://api.example.com/users")
389 /// .json(&user)?
390 /// .send()
391 /// .await?;
392 /// ```
393 pub fn post(&self, url: &str) -> RequestBuilder {
394 self.request(Method::POST, url)
395 }
396
397 /// PUT 请求
398 ///
399 /// # 参数
400 ///
401 /// - `url`: 请求 URL
402 ///
403 /// # 返回
404 ///
405 /// - `RequestBuilder`: 请求构建器
406 ///
407 /// # 示例
408 ///
409 /// ```rust,ignore
410 /// let response = client
411 /// .put("https://api.example.com/users/1")
412 /// .json(&user)?
413 /// .send()
414 /// .await?;
415 /// ```
416 pub fn put(&self, url: &str) -> RequestBuilder {
417 self.request(Method::PUT, url)
418 }
419
420 /// DELETE 请求
421 ///
422 /// # 参数
423 ///
424 /// - `url`: 请求 URL
425 ///
426 /// # 返回
427 ///
428 /// - `RequestBuilder`: 请求构建器
429 ///
430 /// # 示例
431 ///
432 /// ```rust,ignore
433 /// let response = client
434 /// .delete("https://api.example.com/users/1")
435 /// .send()
436 /// .await?;
437 /// ```
438 pub fn delete(&self, url: &str) -> RequestBuilder {
439 self.request(Method::DELETE, url)
440 }
441
442 /// PATCH 请求
443 ///
444 /// # 参数
445 ///
446 /// - `url`: 请求 URL
447 ///
448 /// # 返回
449 ///
450 /// - `RequestBuilder`: 请求构建器
451 ///
452 /// # 示例
453 ///
454 /// ```rust,ignore
455 /// let response = client
456 /// .patch("https://api.example.com/users/1")
457 /// .json(&updates)?
458 /// .send()
459 /// .await?;
460 /// ```
461 pub fn patch(&self, url: &str) -> RequestBuilder {
462 self.request(Method::PATCH, url)
463 }
464}