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}