Skip to main content

yang_base/http/
client.rs

1//! HTTP 客户端核心实现
2//!
3//! 提供全局 HTTP 客户端和请求构建能力。
4
5use crate::error::BaseError;
6use crate::http::request::RequestBuilder;
7use reqwest::{Client, Method};
8use std::sync::{Arc, OnceLock, RwLock};
9use std::time::Duration;
10
11/// 全局 HTTP 客户端实例
12static GLOBAL_HTTP_CLIENT: OnceLock<HttpClient> = OnceLock::new();
13
14/// HTTP 客户端
15///
16/// 提供 HTTP 请求构建和发送能力
17///
18/// # 示例
19///
20/// ```rust,ignore
21/// use yang_base::http::HttpClient;
22///
23/// // 初始化全局客户端
24/// HttpClient::init_global(30)?;
25///
26/// // 使用全局客户端发起请求
27/// let response = HttpClient::global()?
28///     .get("https://api.example.com/users")
29///     .send()
30///     .await?;
31/// ```
32#[derive(Clone, Debug)]
33pub struct HttpClient {
34    /// reqwest 客户端
35    client: Client,
36
37    /// 默认超时时间
38    default_timeout: Duration,
39
40    /// 默认 Token(可选)
41    default_token: Arc<RwLock<Option<String>>>,
42}
43
44impl HttpClient {
45    /// 创建新的 HTTP 客户端
46    ///
47    /// # 参数
48    ///
49    /// - `timeout_secs`: 默认超时时间(秒)
50    ///
51    /// # 返回
52    ///
53    /// - `Ok(HttpClient)`: 客户端实例
54    /// - `Err(BaseError)`: 创建失败
55    ///
56    /// # 示例
57    ///
58    /// ```rust,ignore
59    /// let client = HttpClient::new(30)?;
60    /// ```
61    pub fn new(timeout_secs: u64) -> Result<Self, BaseError> {
62        let client = Client::builder()
63            .timeout(Duration::from_secs(timeout_secs))
64            .build()
65            .map_err(|e| BaseError::HttpClientCreateFailed(e.to_string()))?;
66
67        Ok(Self {
68            client,
69            default_timeout: Duration::from_secs(timeout_secs),
70            default_token: Arc::new(RwLock::new(None)),
71        })
72    }
73
74    /// 初始化全局 HTTP 客户端
75    ///
76    /// # 参数
77    ///
78    /// - `timeout_secs`: 默认超时时间(秒)
79    ///
80    /// # 返回
81    ///
82    /// - `Ok(())`: 初始化成功
83    /// - `Err(BaseError)`: 初始化失败
84    ///
85    /// # 示例
86    ///
87    /// ```rust,ignore
88    /// HttpClient::init_global(30)?;
89    /// ```
90    pub fn init_global(timeout_secs: u64) -> Result<(), BaseError> {
91        let client = Self::new(timeout_secs)?;
92
93        GLOBAL_HTTP_CLIENT
94            .set(client)
95            .map_err(|_| BaseError::HttpClientCreateFailed("全局客户端已初始化".to_string()))?;
96
97        log::info!("全局 HTTP 客户端已初始化,超时时间: {} 秒", timeout_secs);
98        Ok(())
99    }
100
101    /// 获取全局 HTTP 客户端
102    ///
103    /// # 返回
104    ///
105    /// - `Ok(&HttpClient)`: 客户端实例
106    /// - `Err(BaseError)`: 客户端未初始化
107    ///
108    /// # 示例
109    ///
110    /// ```rust,ignore
111    /// let client = HttpClient::global()?;
112    /// ```
113    pub fn global() -> Result<&'static HttpClient, BaseError> {
114        GLOBAL_HTTP_CLIENT
115            .get()
116            .ok_or(BaseError::HttpClientCreateFailed(
117                "全局客户端未初始化".to_string(),
118            ))
119    }
120
121    /// 设置默认 Token
122    ///
123    /// # 参数
124    ///
125    /// - `token`: Token 字符串
126    ///
127    /// # 示例
128    ///
129    /// ```rust,ignore
130    /// let mut client = HttpClient::new(30)?;
131    /// client.set_default_token("your_token".to_string());
132    /// ```
133    pub fn set_default_token(&self, token: String) {
134        let mut default_token = self.default_token.write().unwrap();
135        *default_token = Some(token);
136        log::debug!("已设置默认 Token");
137    }
138
139    /// 获取默认 Token
140    fn get_default_token(&self) -> Option<String> {
141        let default_token = self.default_token.read().unwrap();
142        default_token.clone()
143    }
144
145    /// 创建请求构建器
146    ///
147    /// # 参数
148    ///
149    /// - `method`: HTTP 方法
150    /// - `url`: 请求 URL
151    ///
152    /// # 返回
153    ///
154    /// - `RequestBuilder`: 请求构建器
155    ///
156    /// # 示例
157    ///
158    /// ```rust,ignore
159    /// use reqwest::Method;
160    ///
161    /// let response = client
162    ///     .request(Method::GET, "https://api.example.com/users")
163    ///     .send()
164    ///     .await?;
165    /// ```
166    pub fn request(&self, method: Method, url: &str) -> RequestBuilder {
167        RequestBuilder::new(
168            self.client.clone(),
169            method,
170            url.to_string(),
171            self.default_timeout,
172            self.get_default_token(),
173        )
174    }
175
176    /// GET 请求
177    ///
178    /// # 参数
179    ///
180    /// - `url`: 请求 URL
181    ///
182    /// # 返回
183    ///
184    /// - `RequestBuilder`: 请求构建器
185    ///
186    /// # 示例
187    ///
188    /// ```rust,ignore
189    /// let response = client
190    ///     .get("https://api.example.com/users")
191    ///     .send()
192    ///     .await?;
193    /// ```
194    pub fn get(&self, url: &str) -> RequestBuilder {
195        self.request(Method::GET, url)
196    }
197
198    /// POST 请求
199    ///
200    /// # 参数
201    ///
202    /// - `url`: 请求 URL
203    ///
204    /// # 返回
205    ///
206    /// - `RequestBuilder`: 请求构建器
207    ///
208    /// # 示例
209    ///
210    /// ```rust,ignore
211    /// let response = client
212    ///     .post("https://api.example.com/users")
213    ///     .json(&user)?
214    ///     .send()
215    ///     .await?;
216    /// ```
217    pub fn post(&self, url: &str) -> RequestBuilder {
218        self.request(Method::POST, url)
219    }
220
221    /// PUT 请求
222    ///
223    /// # 参数
224    ///
225    /// - `url`: 请求 URL
226    ///
227    /// # 返回
228    ///
229    /// - `RequestBuilder`: 请求构建器
230    ///
231    /// # 示例
232    ///
233    /// ```rust,ignore
234    /// let response = client
235    ///     .put("https://api.example.com/users/1")
236    ///     .json(&user)?
237    ///     .send()
238    ///     .await?;
239    /// ```
240    pub fn put(&self, url: &str) -> RequestBuilder {
241        self.request(Method::PUT, url)
242    }
243
244    /// DELETE 请求
245    ///
246    /// # 参数
247    ///
248    /// - `url`: 请求 URL
249    ///
250    /// # 返回
251    ///
252    /// - `RequestBuilder`: 请求构建器
253    ///
254    /// # 示例
255    ///
256    /// ```rust,ignore
257    /// let response = client
258    ///     .delete("https://api.example.com/users/1")
259    ///     .send()
260    ///     .await?;
261    /// ```
262    pub fn delete(&self, url: &str) -> RequestBuilder {
263        self.request(Method::DELETE, url)
264    }
265
266    /// PATCH 请求
267    ///
268    /// # 参数
269    ///
270    /// - `url`: 请求 URL
271    ///
272    /// # 返回
273    ///
274    /// - `RequestBuilder`: 请求构建器
275    ///
276    /// # 示例
277    ///
278    /// ```rust,ignore
279    /// let response = client
280    ///     .patch("https://api.example.com/users/1")
281    ///     .json(&updates)?
282    ///     .send()
283    ///     .await?;
284    /// ```
285    pub fn patch(&self, url: &str) -> RequestBuilder {
286        self.request(Method::PATCH, url)
287    }
288}