Skip to main content

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}