Skip to main content

yang_base/http/
request.rs

1//! HTTP 请求构建器实现
2//!
3//! 提供链式调用接口构建 HTTP 请求。
4
5use crate::error::BaseError;
6use crate::http::response::Response;
7use reqwest::header::{HeaderMap, HeaderName, HeaderValue};
8use reqwest::{Client, Method};
9use serde::Serialize;
10use std::time::Duration;
11
12/// 判断 HTTP 方法是否幂等(可默认安全重试)。
13///
14/// 依据 RFC 9110:GET/HEAD/OPTIONS/TRACE 为安全方法,PUT/DELETE 幂等;
15/// POST/PATCH 非幂等,重复发送可能造成重复写入(重复扣款、重复插入等)。
16///
17/// `reqwest::Method` 的 `PartialEq` 是手写实现,故这里用常量相等比较,
18/// 不使用 `matches!` 的结构性常量模式匹配。
19fn is_idempotent_method(method: &Method) -> bool {
20    *method == Method::GET
21        || *method == Method::HEAD
22        || *method == Method::OPTIONS
23        || *method == Method::TRACE
24        || *method == Method::PUT
25        || *method == Method::DELETE
26}
27
28fn redact_url_for_log(url: &str) -> String {
29    let Ok(mut parsed_url) = reqwest::Url::parse(url) else {
30        return "<invalid-url>".to_string();
31    };
32
33    parsed_url.set_query(None);
34    if !parsed_url.username().is_empty() {
35        let _ = parsed_url.set_username("***");
36    }
37    if parsed_url.password().is_some() {
38        let _ = parsed_url.set_password(Some("***"));
39    }
40
41    parsed_url.to_string()
42}
43
44/// 请求级重试策略配置(L-4)。
45///
46/// 对临时性失败(连接错误、可重试的 5xx 等)按指数退避自动重试。
47/// 默认不重试——只有显式调用 [`RequestBuilder::retry`] 才启用。
48///
49/// 注意:当前仅实现「重试 + 指数退避 + 抖动」。熔断(circuit breaker)尚未实现,
50/// 如需熔断请在调用方或网关层处理。
51///
52/// 非幂等方法(POST/PATCH)默认不参与重试——即使启用了重试也只发送一次;
53/// 需要重试时须显式设置 [`RetryConfig::retry_non_idempotent`] 为 `true`,
54/// 由调用方自行承担重复写入(重复扣款/重复插入)的风险。
55///
56/// 重试等待受 [`RetryConfig::total_budget_ms`] 总预算钳制,避免长退避把单次
57/// `send()` 拖成不可控的长尾;另有 [`RetryConfig::jitter_percent`] 抖动去同步
58/// 并发重试。本配置只在调用方显式调用 [`RequestBuilder::retry`] 时生效,
59/// 应用层应另外配置 transport 的 `request_timeout`
60/// (`AxumTransportConfig::request_timeout`,默认 `None`)作为最终兜底。
61///
62/// # 示例
63///
64/// ```rust,ignore
65/// use yang_base::http::RetryConfig;
66///
67/// let cfg = RetryConfig {
68///     max_retries: 3,
69///     retry_on: vec![502, 503, 504],
70///     backoff_ms: 100, // 第 n 次重试前等待 backoff_ms * 2^(n-1) 毫秒
71///     retry_non_idempotent: false, // POST/PATCH 不重试
72///     total_budget_ms: 30_000,     // 单次 send() 内全部退避等待的总预算
73///     jitter_percent: 25,          // 退避抖动幅度 ±25%
74/// };
75/// ```
76#[derive(Debug, Clone)]
77pub struct RetryConfig {
78    /// 最大重试次数(不含首次请求)。0 等价于不重试。
79    pub max_retries: u32,
80    /// 命中这些 HTTP 状态码时重试(如 `[502, 503, 504]`)。
81    pub retry_on: Vec<u16>,
82    /// 初始退避毫秒数,按 `backoff_ms * 2^attempt` 指数增长。
83    pub backoff_ms: u64,
84    /// 是否允许非幂等方法(POST/PATCH)重试。默认 `false`。
85    ///
86    /// 默认关闭时,非幂等请求即使启用了重试也只发送一次,避免
87    /// 「服务端已处理但响应超时/连接中断」时重复扣款、重复插入。
88    /// 仅当调用方确认接口幂等(如带幂等键)时才可置为 `true`。
89    pub retry_non_idempotent: bool,
90    /// 单次 `send()` 内全部重试等待的总时间预算(毫秒)。
91    ///
92    /// 每次退避等待取 `min(抖动后退避, 剩余预算)`;预算耗尽后不再等待,
93    /// 直接返回最后一次请求的结果。必须大于 0(禁止「无预算」后门),
94    /// 上限 300_000 毫秒(`MAX_TOTAL_BUDGET_MS`)。
95    pub total_budget_ms: u64,
96    /// 单次退避的抖动幅度(百分比 `0..=100`)。0 表示不抖动。
97    ///
98    /// 抖动用于打散并发请求的同步重试(惊群):实际上限为初始退避的
99    /// ±`jitter_percent`%,取 `SystemTime` 纳秒 + 进程号 + 重试序号混合的
100    /// 非密码学熵源,不引入额外依赖。
101    pub jitter_percent: u8,
102}
103
104impl Default for RetryConfig {
105    fn default() -> Self {
106        Self {
107            max_retries: 3,
108            retry_on: vec![502, 503, 504],
109            backoff_ms: 100,
110            retry_non_idempotent: false,
111            total_budget_ms: 30_000,
112            jitter_percent: 25,
113        }
114    }
115}
116
117impl RetryConfig {
118    const MAX_RETRIES: u32 = 10;
119    const MAX_BACKOFF_MS: u64 = 60_000;
120    const MAX_TOTAL_BUDGET_MS: u64 = 300_000;
121
122    /// 验证请求级重试策略。
123    ///
124    /// `max_retries == 0` 表示显式禁用重试,此时 `retry_on` 与 `backoff_ms` 不参与发送。
125    pub fn validate(&self) -> Result<(), BaseError> {
126        if self.max_retries > Self::MAX_RETRIES {
127            return Err(BaseError::ParamInvalid(
128                "http.retry.max_retries".to_string(),
129                format!("最大重试次数不能超过 {}", Self::MAX_RETRIES),
130            ));
131        }
132
133        if self.max_retries == 0 {
134            return Ok(());
135        }
136
137        if self.retry_on.is_empty() {
138            return Err(BaseError::ParamInvalid(
139                "http.retry.retry_on".to_string(),
140                "启用重试时 retry_on 不能为空".to_string(),
141            ));
142        }
143
144        if let Some(status) = self
145            .retry_on
146            .iter()
147            .copied()
148            .find(|status| !(100..=599).contains(status))
149        {
150            return Err(BaseError::ParamInvalid(
151                "http.retry.retry_on".to_string(),
152                format!("非法 HTTP 状态码: {status}"),
153            ));
154        }
155
156        if self.backoff_ms == 0 {
157            return Err(BaseError::ParamInvalid(
158                "http.retry.backoff_ms".to_string(),
159                "启用重试时初始退避时间必须大于 0 毫秒".to_string(),
160            ));
161        }
162
163        if self.backoff_ms > Self::MAX_BACKOFF_MS {
164            return Err(BaseError::ParamInvalid(
165                "http.retry.backoff_ms".to_string(),
166                format!("初始退避时间不能超过 {} 毫秒", Self::MAX_BACKOFF_MS),
167            ));
168        }
169
170        if self.total_budget_ms == 0 || self.total_budget_ms > Self::MAX_TOTAL_BUDGET_MS {
171            return Err(BaseError::ParamInvalid(
172                "http.retry.total_budget_ms".to_string(),
173                format!("重试总预算必须在 1..={} 毫秒内", Self::MAX_TOTAL_BUDGET_MS),
174            ));
175        }
176
177        if self.jitter_percent > 100 {
178            return Err(BaseError::ParamInvalid(
179                "http.retry.jitter_percent".to_string(),
180                "退避抖动百分比不能超过 100".to_string(),
181            ));
182        }
183
184        Ok(())
185    }
186}
187
188/// 对退避时长施加 ±`jitter_percent`% 抖动,避免并发请求同步重试(惊群)。
189///
190/// 纯整数运算:`span = base_ms / 100 * jitter_percent`,返回值落在
191/// `[base_ms - span, base_ms + span]`。熵源仅用于打散去同步,非密码学用途,
192/// 故直接复用 `SystemTime` 纳秒 + 进程号 + 重试序号,不引入 `rand` 等依赖。
193fn jittered_backoff(base_ms: u64, jitter_percent: u8, attempt: u32) -> u64 {
194    let jp = u64::from(jitter_percent.min(100));
195    if base_ms == 0 || jp == 0 {
196        return base_ms;
197    }
198
199    let span = base_ms / 100 * jp;
200    if span == 0 {
201        return base_ms;
202    }
203
204    let entropy = std::time::SystemTime::now()
205        .duration_since(std::time::UNIX_EPOCH)
206        .map_or(0, |d| u64::from(d.subsec_nanos()))
207        ^ u64::from(std::process::id())
208        ^ u64::from(attempt);
209
210    base_ms
211        .saturating_sub(span)
212        .saturating_add(entropy % span.saturating_mul(2).saturating_add(1))
213}
214
215/// HTTP 请求构建器
216///
217/// 提供链式调用接口构建 HTTP 请求。
218///
219/// # Header 错误处理
220///
221/// `header`、`headers` 等方法在解析失败时不会立即返回错误,而是将错误信息
222/// 累积到内部 `header_errors` 列表中。调用 `send()` 时,若存在累积的 header
223/// 错误,则返回 `BaseError::ParamInvalid("header", ...)` 而不发送请求。
224///
225/// # 示例
226///
227/// ```rust,ignore
228/// // tools 为启动期经 ToolsBuilder::http(...) 冻结的应用资源;Action 内则用 ctx.http()?
229/// let response = tools.http()?
230///     .get("https://api.example.com/users")
231///     .header("X-Custom-Header", "value")
232///     .query("page", "1")
233///     .bearer_token("your_token")
234///     .timeout(60)
235///     .send()
236///     .await?;
237/// ```
238pub struct RequestBuilder {
239    /// reqwest 客户端(Arc 包装,clone 时复用同一连接池)
240    client: Client,
241
242    /// HTTP 方法
243    method: Method,
244
245    /// 请求 URL
246    url: String,
247
248    /// 请求头
249    headers: HeaderMap,
250
251    /// 累积的 header 解析错误列表
252    ///
253    /// `header`、`headers` 方法在解析失败时将错误描述追加到此列表,
254    /// `send()` 时若非空则返回 `BaseError::ParamInvalid`。
255    header_errors: Vec<String>,
256
257    /// 查询参数
258    query_params: Vec<(String, String)>,
259
260    /// 请求体
261    body: Option<Vec<u8>>,
262
263    /// 超时时间
264    timeout: Duration,
265
266    /// 出站响应体最大允许字节数(来自 HttpClientConfig)
267    max_response_bytes: usize,
268
269    /// Token(可选)
270    token: Option<String>,
271
272    /// 重试策略(可选,默认不重试)
273    retry: Option<RetryConfig>,
274
275    /// 熔断器(可选,默认 None)。来自创建该构建器的 HttpClient,共享状态。
276    circuit_breaker: Option<crate::http::CircuitBreaker>,
277}
278
279impl RequestBuilder {
280    /// 创建新的请求构建器
281    ///
282    /// # 参数
283    ///
284    /// - `client`: reqwest 客户端(Arc 包装,clone 时复用同一连接池)
285    /// - `method`: HTTP 方法
286    /// - `url`: 请求 URL
287    /// - `timeout`: 超时时间
288    /// - `max_response_bytes`: 出站响应体最大允许字节数
289    /// - `token`: 默认 Token
290    /// - `circuit_breaker`: 熔断器(可选,来自 HttpClient)
291    pub(crate) fn new(
292        client: Client,
293        method: Method,
294        url: String,
295        timeout: Duration,
296        max_response_bytes: usize,
297        token: Option<String>,
298        circuit_breaker: Option<crate::http::CircuitBreaker>,
299    ) -> Self {
300        Self {
301            client,
302            method,
303            url,
304            headers: HeaderMap::new(),
305            header_errors: Vec::new(),
306            query_params: Vec::new(),
307            body: None,
308            timeout,
309            max_response_bytes,
310            token,
311            retry: None,
312            circuit_breaker,
313        }
314    }
315
316    /// 设置请求头
317    ///
318    /// 若 header 名称或值解析失败,错误信息将被累积到内部错误列表,
319    /// 不会立即返回错误。调用 `send()` 时若存在累积错误则返回 `BaseError::ParamInvalid`。
320    ///
321    /// # 参数
322    ///
323    /// - `name`: 请求头名称
324    /// - `value`: 请求头值
325    ///
326    /// # 示例
327    ///
328    /// ```rust,ignore
329    /// let response = client
330    ///     .get("https://api.example.com/users")
331    ///     .header("X-Custom-Header", "value")
332    ///     .send()
333    ///     .await?;
334    /// ```
335    pub fn header(mut self, name: &str, value: &str) -> Self {
336        // 解析 header 名称
337        let header_name = match HeaderName::from_bytes(name.as_bytes()) {
338            Ok(n) => n,
339            Err(e) => {
340                // 累积错误,不立即返回
341                self.header_errors
342                    .push(format!("非法 header 名称 '{}': {}", name, e));
343                return self;
344            }
345        };
346
347        // 解析 header 值
348        let header_value = match HeaderValue::from_str(value) {
349            Ok(v) => v,
350            Err(e) => {
351                // 累积错误,不立即返回
352                self.header_errors
353                    .push(format!("非法 header 值 '{}': {}", value, e));
354                return self;
355            }
356        };
357
358        self.headers.insert(header_name, header_value);
359        self
360    }
361
362    /// 批量设置请求头
363    ///
364    /// 若任意 header 名称或值解析失败,错误信息将被累积到内部错误列表,
365    /// 不会立即返回错误。调用 `send()` 时若存在累积错误则返回 `BaseError::ParamInvalid`。
366    ///
367    /// # 参数
368    ///
369    /// - `headers`: 请求头列表
370    ///
371    /// # 示例
372    ///
373    /// ```rust,ignore
374    /// let response = client
375    ///     .get("https://api.example.com/users")
376    ///     .headers(vec![
377    ///         ("X-Custom-Header-1", "value1"),
378    ///         ("X-Custom-Header-2", "value2"),
379    ///     ])
380    ///     .send()
381    ///     .await?;
382    /// ```
383    pub fn headers(mut self, headers: Vec<(&str, &str)>) -> Self {
384        for (name, value) in headers {
385            // 解析 header 名称
386            let header_name = match HeaderName::from_bytes(name.as_bytes()) {
387                Ok(n) => n,
388                Err(e) => {
389                    // 累积错误,继续处理其余 header
390                    self.header_errors
391                        .push(format!("非法 header 名称 '{}': {}", name, e));
392                    continue;
393                }
394            };
395
396            // 解析 header 值
397            let header_value = match HeaderValue::from_str(value) {
398                Ok(v) => v,
399                Err(e) => {
400                    // 累积错误,继续处理其余 header
401                    self.header_errors
402                        .push(format!("非法 header 值 '{}': {}", value, e));
403                    continue;
404                }
405            };
406
407            self.headers.insert(header_name, header_value);
408        }
409        self
410    }
411
412    /// 设置 Content-Type
413    ///
414    /// # 参数
415    ///
416    /// - `content_type`: Content-Type 值
417    ///
418    /// # 示例
419    ///
420    /// ```rust,ignore
421    /// let response = client
422    ///     .post("https://api.example.com/users")
423    ///     .content_type("application/json")
424    ///     .send()
425    ///     .await?;
426    /// ```
427    pub fn content_type(self, content_type: &str) -> Self {
428        self.header("Content-Type", content_type)
429    }
430
431    /// 设置 Bearer Token
432    ///
433    /// # 参数
434    ///
435    /// - `token`: Token 字符串
436    ///
437    /// # 示例
438    ///
439    /// ```rust,ignore
440    /// let response = client
441    ///     .get("https://api.example.com/users")
442    ///     .bearer_token("your_token")
443    ///     .send()
444    ///     .await?;
445    /// ```
446    pub fn bearer_token(mut self, token: &str) -> Self {
447        self.token = Some(token.to_string());
448        self
449    }
450
451    /// 设置 User-Agent
452    ///
453    /// # 参数
454    ///
455    /// - `user_agent`: User-Agent 值
456    ///
457    /// # 示例
458    ///
459    /// ```rust,ignore
460    /// let response = client
461    ///     .get("https://api.example.com/users")
462    ///     .user_agent("MyApp/1.0")
463    ///     .send()
464    ///     .await?;
465    /// ```
466    pub fn user_agent(self, user_agent: &str) -> Self {
467        self.header("User-Agent", user_agent)
468    }
469
470    /// 添加查询参数
471    ///
472    /// # 参数
473    ///
474    /// - `key`: 参数名
475    /// - `value`: 参数值
476    ///
477    /// # 示例
478    ///
479    /// ```rust,ignore
480    /// let response = client
481    ///     .get("https://api.example.com/users")
482    ///     .query("page", "1")
483    ///     .query("limit", "10")
484    ///     .send()
485    ///     .await?;
486    /// ```
487    pub fn query(mut self, key: &str, value: &str) -> Self {
488        self.query_params.push((key.to_string(), value.to_string()));
489        self
490    }
491
492    /// 批量添加查询参数
493    ///
494    /// # 参数
495    ///
496    /// - `params`: 查询参数列表
497    ///
498    /// # 示例
499    ///
500    /// ```rust,ignore
501    /// let response = client
502    ///     .get("https://api.example.com/users")
503    ///     .queries(vec![("page", "1"), ("limit", "10")])
504    ///     .send()
505    ///     .await?;
506    /// ```
507    pub fn queries(mut self, params: Vec<(&str, &str)>) -> Self {
508        for (key, value) in params {
509            self.query_params.push((key.to_string(), value.to_string()));
510        }
511        self
512    }
513
514    /// 设置 JSON 请求体
515    ///
516    /// # 参数
517    ///
518    /// - `json`: 可序列化为 JSON 的数据
519    ///
520    /// # 返回
521    ///
522    /// - `Ok(Self)`: 设置成功
523    /// - `Err(BaseError)`: 序列化失败
524    ///
525    /// # 示例
526    ///
527    /// ```rust,ignore
528    /// #[derive(Serialize)]
529    /// struct User {
530    ///     name: String,
531    ///     email: String,
532    /// }
533    ///
534    /// let user = User {
535    ///     name: "Alice".to_string(),
536    ///     email: "alice@example.com".to_string(),
537    /// };
538    ///
539    /// let response = client
540    ///     .post("https://api.example.com/users")
541    ///     .json(&user)?
542    ///     .send()
543    ///     .await?;
544    /// ```
545    pub fn json<T: Serialize>(mut self, json: &T) -> Result<Self, BaseError> {
546        let json_bytes =
547            serde_json::to_vec(json).map_err(|e| BaseError::JsonSerializeFailed(e.to_string()))?;
548
549        self.body = Some(json_bytes);
550        self = self.content_type("application/json");
551
552        Ok(self)
553    }
554
555    /// 设置表单请求体
556    ///
557    /// 使用 `serde_urlencoded` 对表单数据进行 URL 编码,正确处理特殊字符、
558    /// 空格、UTF-8 字符等,并自动设置 `Content-Type: application/x-www-form-urlencoded`。
559    ///
560    /// # 参数
561    ///
562    /// - `form`: 表单数据(键值对列表)
563    ///
564    /// # 示例
565    ///
566    /// ```rust,ignore
567    /// let response = client
568    ///     .post("https://api.example.com/login")
569    ///     .form(vec![("username", "alice"), ("password", "secret")])
570    ///     .send()
571    ///     .await?;
572    /// ```
573    pub fn form(mut self, form: Vec<(&str, &str)>) -> Self {
574        // 使用 serde_urlencoded 进行标准 URL 编码,正确处理特殊字符
575        match serde_urlencoded::to_string(&form) {
576            Ok(encoded) => {
577                self.body = Some(encoded.into_bytes());
578                // 自动设置 Content-Type
579                self = self.content_type("application/x-www-form-urlencoded");
580            }
581            Err(e) => {
582                // 编码失败时累积错误
583                self.header_errors.push(format!("表单数据编码失败: {}", e));
584            }
585        }
586        self
587    }
588
589    /// 设置原始字节请求体
590    ///
591    /// # 参数
592    ///
593    /// - `body`: 字节数据
594    ///
595    /// # 示例
596    ///
597    /// ```rust,ignore
598    /// let response = client
599    ///     .post("https://api.example.com/upload")
600    ///     .body(vec![0x00, 0x01, 0x02])
601    ///     .send()
602    ///     .await?;
603    /// ```
604    pub fn body(mut self, body: Vec<u8>) -> Self {
605        self.body = Some(body);
606        self
607    }
608
609    /// 设置文本请求体
610    ///
611    /// # 参数
612    ///
613    /// - `text`: 文本数据
614    ///
615    /// # 示例
616    ///
617    /// ```rust,ignore
618    /// let response = client
619    ///     .post("https://api.example.com/notes")
620    ///     .text("Hello, World!")
621    ///     .send()
622    ///     .await?;
623    /// ```
624    pub fn text(mut self, text: &str) -> Self {
625        self.body = Some(text.as_bytes().to_vec());
626        self = self.content_type("text/plain");
627        self
628    }
629
630    /// 设置超时时间
631    ///
632    /// # 参数
633    ///
634    /// - `timeout_secs`: 超时时间(秒)
635    ///
636    /// # 示例
637    ///
638    /// ```rust,ignore
639    /// let response = client
640    ///     .get("https://api.example.com/users")
641    ///     .timeout(60)
642    ///     .send()
643    ///     .await?;
644    /// ```
645    pub fn timeout(mut self, timeout_secs: u64) -> Self {
646        self.timeout = Duration::from_secs(timeout_secs);
647        self
648    }
649
650    /// 设置出站响应体最大允许字节数。
651    ///
652    /// 与 `HttpClientConfig::max_response_bytes` 语义一致:读取响应体时超限
653    /// 返回 `BaseError::HttpResponseTooLarge`。设为 0 会在 `send()` 前被拒绝。
654    ///
655    /// # 参数
656    ///
657    /// - `bytes`: 响应体最大允许字节数(必须大于 0)
658    ///
659    /// # 示例
660    ///
661    /// ```rust,ignore
662    /// let response = client
663    ///     .get("https://api.example.com/users")
664    ///     .max_response_bytes(1024 * 1024)
665    ///     .send()
666    ///     .await?;
667    /// ```
668    pub fn max_response_bytes(mut self, bytes: usize) -> Self {
669        self.max_response_bytes = bytes;
670        self
671    }
672
673    /// 设置请求级重试策略(L-4)。
674    ///
675    /// 默认不重试。启用后,对连接错误与命中 `retry_on` 的状态码按指数退避重试。
676    ///
677    /// 非幂等方法(POST/PATCH)默认不参与重试,需
678    /// [`RetryConfig::retry_non_idempotent`] 置为 `true` 才显式承担重复写风险。
679    ///
680    /// # 参数
681    ///
682    /// - `config`: 重试策略
683    ///
684    /// # 示例
685    ///
686    /// ```rust,ignore
687    /// use yang_base::http::RetryConfig;
688    ///
689    /// let response = client
690    ///     .get("https://api.example.com/users")
691    ///     .retry(RetryConfig::default())
692    ///     .send()
693    ///     .await?;
694    /// ```
695    pub fn retry(mut self, config: RetryConfig) -> Self {
696        self.retry = Some(config);
697        self
698    }
699
700    /// 发送请求
701    ///
702    /// 在发送前检查累积的 header 错误。若存在任何 header 解析错误,
703    /// 则返回 `BaseError::ParamInvalid("header", ...)` 而不发送请求。
704    ///
705    /// # 返回
706    ///
707    /// - `Ok(Response)`: 响应对象
708    /// - `Err(BaseError::ParamInvalid)`: 存在非法 header
709    /// - `Err(BaseError::HttpRequestFailed)`: 请求发送失败
710    ///
711    /// # 示例
712    ///
713    /// ```rust,ignore
714    /// let response = client
715    ///     .get("https://api.example.com/users")
716    ///     .send()
717    ///     .await?;
718    /// ```
719    pub async fn send(self) -> Result<Response, BaseError> {
720        // 检查累积的 header 错误,若非空则提前返回错误
721        if !self.header_errors.is_empty() {
722            return Err(BaseError::ParamInvalid(
723                "header".to_string(),
724                self.header_errors.join("; "),
725            ));
726        }
727
728        if self
729            .query_params
730            .iter()
731            .any(|(key, _)| key.trim().is_empty())
732        {
733            return Err(BaseError::ParamInvalid(
734                "query".to_string(),
735                "query 参数名称不能为空".to_string(),
736            ));
737        }
738
739        let parsed_url = reqwest::Url::parse(&self.url).map_err(|err| {
740            BaseError::ParamInvalid("url".to_string(), format!("非法 HTTP URL: {}", err))
741        })?;
742        if !matches!(parsed_url.scheme(), "http" | "https") {
743            return Err(BaseError::ParamInvalid(
744                "url".to_string(),
745                "HTTP 客户端仅支持 http 和 https URL".to_string(),
746            ));
747        }
748
749        if let Some(token) = &self.token {
750            let auth_value = format!("Bearer {}", token);
751            if let Err(err) = HeaderValue::from_str(&auth_value) {
752                return Err(BaseError::ParamInvalid(
753                    "authorization".to_string(),
754                    format!("非法 bearer token,无法构造 Authorization 头: {}", err),
755                ));
756            }
757        }
758
759        if self.timeout.is_zero() {
760            return Err(BaseError::ParamInvalid(
761                "http.timeout_secs".to_string(),
762                "HTTP 请求超时时间必须大于 0 秒".to_string(),
763            ));
764        }
765
766        if self.max_response_bytes == 0 {
767            return Err(BaseError::ParamInvalid(
768                "http.max_response_bytes".to_string(),
769                "HTTP 响应体上限必须大于 0 字节".to_string(),
770            ));
771        }
772
773        if let Some(retry) = &self.retry {
774            retry.validate()?;
775        }
776
777        let retry = self.retry.clone();
778
779        // 解析目标 host 用于熔断分键;无熔断器或解析失败时为 None(按无熔断处理)。
780        let host = self
781            .circuit_breaker
782            .as_ref()
783            .and_then(|_| parsed_url.host_str().map(|h| h.to_string()));
784
785        // 无重试策略:单次发送(与原行为一致,仅多一层熔断准入)
786        let Some(retry) = retry else {
787            return self.send_guarded(host.as_deref()).await;
788        };
789
790        // 非幂等方法未显式 opt-in:退化为单次发送。
791        // 该闸门同时覆盖状态码重试分支与传输错误重试分支——POST/PATCH 一旦命中
792        // `retry_on` 或连接中断同样会重放已生效的写入,须一并拦截。
793        if !is_idempotent_method(&self.method) && !retry.retry_non_idempotent {
794            return self.send_guarded(host.as_deref()).await;
795        }
796
797        // 有重试策略:最多发送 1 + max_retries 次。
798        // `remaining_budget_ms` 是本轮 `send()` 内全部退避等待共享的总预算。
799        let mut attempt: u32 = 0;
800        let mut remaining_budget_ms = retry.total_budget_ms;
801        loop {
802            let result = self.send_guarded(host.as_deref()).await;
803
804            let should_retry = match &result {
805                // 命中可重试状态码
806                Ok(resp) => retry.retry_on.contains(&resp.status()),
807                // 连接/超时等传输错误也重试
808                Err(BaseError::HttpRequestFailed(_)) => true,
809                // 熔断打开(HttpCircuitBreakerOpen)等其它错误不重试
810                Err(_) => false,
811            };
812
813            if !should_retry || attempt >= retry.max_retries {
814                return result;
815            }
816
817            // 指数退避 backoff_ms * 2^attempt,叠加抖动,再受剩余预算钳制:
818            // 预算耗尽(钳制后为 0)时不再等待,直接返回最后一次结果,避免
819            // 「重试 + 长退避」把单次 send() 拖成长尾。
820            let base = retry.backoff_ms.saturating_mul(1u64 << attempt.min(20));
821            let sleep_ms =
822                jittered_backoff(base, retry.jitter_percent, attempt).min(remaining_budget_ms);
823            if sleep_ms == 0 {
824                return result;
825            }
826
827            tokio::time::sleep(Duration::from_millis(sleep_ms)).await;
828            remaining_budget_ms -= sleep_ms;
829            attempt += 1;
830        }
831    }
832
833    /// 在熔断器准入检查下发送一次请求,并按结果记录成功/失败。
834    ///
835    /// - 准入:若熔断器对该 host 处于 Open(且未冷却),直接返回
836    ///   `BaseError::HttpCircuitBreakerOpen`,不实际发请求。
837    /// - 记账:传输错误与 5xx 视为失败,2xx/3xx/4xx 视为成功。
838    ///
839    /// 当 `host` 为 `None`(无熔断器或 URL 解析不出 host)时,等价于直接 `send_once`。
840    async fn send_guarded(&self, host: Option<&str>) -> Result<Response, BaseError> {
841        let breaker = self.circuit_breaker.as_ref();
842
843        if let (Some(breaker), Some(host)) = (breaker, host) {
844            if !breaker.allow(host) {
845                return Err(BaseError::HttpCircuitBreakerOpen(host.to_string()));
846            }
847        }
848
849        let result = self.send_once().await;
850
851        if let (Some(breaker), Some(host)) = (breaker, host) {
852            match &result {
853                Ok(resp) if resp.status() >= 500 => breaker.on_failure(host),
854                Ok(_) => breaker.on_success(host),
855                Err(_) => breaker.on_failure(host),
856            }
857        }
858
859        result
860    }
861
862    /// 构建并发送一次请求(不含重试)。
863    ///
864    /// 因重试需要重复发送,这里借用 `&self` 并克隆可复用的请求部件
865    /// (headers / query / body 均可 clone;`client` 为 `Arc`,clone 复用连接池)。
866    async fn send_once(&self) -> Result<Response, BaseError> {
867        // 构建请求
868        // 注意:self.client.clone() 是 Arc::clone,复用同一底层连接池,不创建新的 TCP 连接池
869        let mut request = self
870            .client
871            .request(self.method.clone(), &self.url)
872            .timeout(self.timeout);
873
874        // 添加请求头
875        request = request.headers(self.headers.clone());
876
877        // 添加 Token
878        if let Some(token) = &self.token {
879            request = request.bearer_auth(token);
880        }
881
882        // 添加查询参数
883        if !self.query_params.is_empty() {
884            request = request.query(&self.query_params);
885        }
886
887        // 添加请求体
888        if let Some(body) = &self.body {
889            request = request.body(body.clone());
890        }
891
892        // 发送请求(NG-1:记录方法/URL/状态码/耗时,便于排查外部 API 慢响应与失败)。
893        // URL 日志脱敏:移除 query,并隐藏 userinfo,避免泄漏 token/password。
894        let start = std::time::Instant::now();
895        let result = request.send().await;
896        let elapsed_ms = start.elapsed().as_millis();
897        let log_url = redact_url_for_log(&self.url);
898        match &result {
899            Ok(resp) => {
900                tracing::debug!(
901                    target: "yang_base::http",
902                    method = %self.method,
903                    url = %log_url,
904                    status = resp.status().as_u16(),
905                    elapsed_ms = elapsed_ms as u64,
906                    "HTTP 出站请求完成"
907                );
908            }
909            Err(e) => {
910                tracing::warn!(
911                    target: "yang_base::http",
912                    method = %self.method,
913                    url = %log_url,
914                    elapsed_ms = elapsed_ms as u64,
915                    error = %e,
916                    "HTTP 出站请求失败"
917                );
918            }
919        }
920        let response = result.map_err(BaseError::HttpRequestFailed)?;
921
922        Ok(Response::new(response, self.max_response_bytes))
923    }
924}
925
926#[cfg(test)]
927mod retry_config_tests {
928    use super::*;
929    use std::sync::atomic::Ordering;
930
931    #[test]
932    fn test_redact_url_for_log_removes_query_and_userinfo() {
933        let redacted = redact_url_for_log("https://user:secret@example.com/path?token=secret&x=1");
934
935        assert_eq!(redacted, "https://***:***@example.com/path");
936        assert!(!redacted.contains("token"));
937        assert!(!redacted.contains("secret"));
938        assert!(!redacted.contains("user"));
939    }
940
941    #[test]
942    fn test_retry_config_validate_rejects_unsafe_values() {
943        let invalid_configs = [
944            RetryConfig {
945                max_retries: 11,
946                ..RetryConfig::default()
947            },
948            RetryConfig {
949                max_retries: 1,
950                retry_on: Vec::new(),
951                ..RetryConfig::default()
952            },
953            RetryConfig {
954                max_retries: 1,
955                backoff_ms: 0,
956                ..RetryConfig::default()
957            },
958            RetryConfig {
959                max_retries: 1,
960                backoff_ms: 60_001,
961                ..RetryConfig::default()
962            },
963            RetryConfig {
964                max_retries: 1,
965                retry_on: vec![99],
966                ..RetryConfig::default()
967            },
968            RetryConfig {
969                max_retries: 1,
970                retry_on: vec![600],
971                ..RetryConfig::default()
972            },
973        ];
974
975        for config in invalid_configs {
976            assert!(matches!(
977                config.validate(),
978                Err(BaseError::ParamInvalid(_, _))
979            ));
980        }
981    }
982
983    #[test]
984    fn test_retry_config_validate_rejects_bad_budget_and_jitter() {
985        let cases = [
986            // 总预算不能为 0(不留「无预算」后门)
987            (
988                "http.retry.total_budget_ms",
989                RetryConfig {
990                    max_retries: 1,
991                    total_budget_ms: 0,
992                    ..RetryConfig::default()
993                },
994            ),
995            // 总预算不能超过上限
996            (
997                "http.retry.total_budget_ms",
998                RetryConfig {
999                    max_retries: 1,
1000                    total_budget_ms: RetryConfig::MAX_TOTAL_BUDGET_MS + 1,
1001                    ..RetryConfig::default()
1002                },
1003            ),
1004            // 抖动百分比不能超过 100
1005            (
1006                "http.retry.jitter_percent",
1007                RetryConfig {
1008                    max_retries: 1,
1009                    jitter_percent: 101,
1010                    ..RetryConfig::default()
1011                },
1012            ),
1013        ];
1014
1015        for (expected_field, config) in cases {
1016            let err = match config.validate() {
1017                Ok(()) => panic!("非法 {expected_field} 应被 validate() 拒绝"),
1018                Err(err) => err,
1019            };
1020            assert!(
1021                matches!(&err, BaseError::ParamInvalid(field, _) if field == expected_field),
1022                "期望 ParamInvalid({expected_field}),实际 {err:?}"
1023            );
1024        }
1025    }
1026
1027    #[test]
1028    fn test_retry_config_default_and_boundaries_are_valid() {
1029        assert!(
1030            RetryConfig::default().validate().is_ok(),
1031            "默认配置必须通过校验"
1032        );
1033
1034        // 边界:预算取上限、抖动取 100 均为合法值
1035        assert!(RetryConfig {
1036            max_retries: 1,
1037            total_budget_ms: RetryConfig::MAX_TOTAL_BUDGET_MS,
1038            jitter_percent: 100,
1039            ..RetryConfig::default()
1040        }
1041        .validate()
1042        .is_ok());
1043    }
1044
1045    #[test]
1046    fn test_jittered_backoff_identity_and_bounds() {
1047        // jitter_percent = 0:恒等返回 base
1048        for base in [0_u64, 1, 99, 100, 1_000, u64::MAX] {
1049            assert_eq!(
1050                jittered_backoff(base, 0, 0),
1051                base,
1052                "jitter_percent=0 时退避时长不应改变"
1053            );
1054        }
1055
1056        // base = 0:任何抖动都只能得到 0
1057        assert_eq!(jittered_backoff(0, 100, 3), 0);
1058
1059        // span 向下取整为 0(base < 100):不做抖动,避免下溢
1060        assert_eq!(jittered_backoff(50, 1, 0), 50);
1061
1062        // jitter_percent = 100:结果落在 [base - span, base + span]
1063        let base = 1_000_u64;
1064        let span = base / 100 * 100;
1065        for attempt in 0..64 {
1066            let got = jittered_backoff(base, 100, attempt);
1067            assert!(
1068                (base - span..=base + span).contains(&got),
1069                "第 {attempt} 次抖动的退避 {got} 应落在 [{}, {}]",
1070                base - span,
1071                base + span
1072            );
1073        }
1074    }
1075
1076    /// 起一个对每个请求都回 `503` 的本地监听器,用于验证重试次数与耗时。
1077    ///
1078    /// 返回 `(监听地址, 请求计数)`;监听线程随测试结束由进程回收。
1079    fn spawn_503_listener() -> (
1080        std::net::SocketAddr,
1081        std::sync::Arc<std::sync::atomic::AtomicUsize>,
1082    ) {
1083        use std::io::{Read, Write};
1084        use std::sync::atomic::{AtomicUsize, Ordering};
1085        use std::sync::Arc;
1086
1087        let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("本地监听端口应可绑定");
1088        let addr = listener.local_addr().expect("应能取得监听地址");
1089        let counter = Arc::new(AtomicUsize::new(0));
1090        let counter_for_thread = Arc::clone(&counter);
1091
1092        std::thread::spawn(move || {
1093            for stream in listener.incoming() {
1094                let Ok(mut stream) = stream else { break };
1095                counter_for_thread.fetch_add(1, Ordering::SeqCst);
1096                // 读走请求再回 503,避免客户端写请求时收到 EPIPE
1097                let mut buf = [0u8; 1024];
1098                let _ = stream.read(&mut buf);
1099                let _ = stream.write_all(
1100                    b"HTTP/1.1 503 Service Unavailable\r\nContent-Length: 0\r\nConnection: close\r\n\r\n",
1101                );
1102                let _ = stream.flush();
1103            }
1104        });
1105
1106        (addr, counter)
1107    }
1108
1109    /// 预算钳制:总预算小于首轮退避时只睡剩余预算,随后立即返回最后一次结果。
1110    #[tokio::test]
1111    async fn test_send_clamps_backoff_wait_to_total_budget() {
1112        let (addr, counter) = spawn_503_listener();
1113        let client = crate::http::HttpClient::new(30).expect("HTTP client should be valid");
1114
1115        let started = std::time::Instant::now();
1116        let result = client
1117            .get(&format!("http://{addr}/always-503"))
1118            .retry(RetryConfig {
1119                max_retries: 3,
1120                retry_on: vec![503],
1121                backoff_ms: 1_000,
1122                jitter_percent: 0,
1123                total_budget_ms: 5,
1124                ..RetryConfig::default()
1125            })
1126            .send()
1127            .await;
1128        let elapsed = started.elapsed();
1129
1130        // 预算耗尽不等于丢结果:仍须把最后一次响应(503)返回给调用方
1131        let resp = match result {
1132            Ok(resp) => resp,
1133            Err(err) => panic!("预算耗尽后应返回最后一次响应而非错误: {err:?}"),
1134        };
1135        assert_eq!(resp.status(), 503);
1136
1137        // 未钳制时退避合计 1000 + 2000 + 4000 = 7000ms;钳制后只有 1 次 5ms 等待
1138        assert!(
1139            elapsed < Duration::from_millis(500),
1140            "退避等待应被总预算钳制(未钳制需约 7s),实际耗时 {elapsed:?}"
1141        );
1142
1143        // 等监听线程计数落定:预算耗尽后不应再发第 3 次请求
1144        tokio::time::sleep(Duration::from_millis(200)).await;
1145        assert_eq!(
1146            counter.load(Ordering::SeqCst),
1147            2,
1148            "预算耗尽后应停止重试(首次 + 1 次重试共 2 次请求)"
1149        );
1150    }
1151
1152    #[tokio::test]
1153    async fn test_send_rejects_invalid_retry_config_before_network() {
1154        let builder = RequestBuilder::new(
1155            Client::new(),
1156            Method::GET,
1157            "http://127.0.0.1:1".to_string(),
1158            Duration::from_secs(30),
1159            10 * 1024 * 1024,
1160            None,
1161            None,
1162        )
1163        .retry(RetryConfig {
1164            max_retries: 11,
1165            ..RetryConfig::default()
1166        });
1167
1168        let err = match builder.send().await {
1169            Ok(_) => panic!("无效 retry 配置应在网络请求前被拒绝"),
1170            Err(err) => err,
1171        };
1172
1173        assert!(
1174            matches!(err, BaseError::ParamInvalid(field, _) if field == "http.retry.max_retries")
1175        );
1176    }
1177
1178    #[tokio::test]
1179    async fn test_send_rejects_zero_request_timeout_before_network() {
1180        let builder = RequestBuilder::new(
1181            Client::new(),
1182            Method::GET,
1183            "http://127.0.0.1:1".to_string(),
1184            Duration::from_secs(30),
1185            10 * 1024 * 1024,
1186            None,
1187            None,
1188        )
1189        .timeout(0);
1190
1191        let err = match builder.send().await {
1192            Ok(_) => panic!("0 秒请求超时应在网络请求前被拒绝"),
1193            Err(err) => err,
1194        };
1195
1196        assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "http.timeout_secs"));
1197    }
1198
1199    #[tokio::test]
1200    async fn test_send_rejects_blank_query_key_before_network() {
1201        let client = crate::http::HttpClient::new(30).expect("HTTP client should be valid");
1202        let result = client
1203            .get("https://api.example.com/users")
1204            .query("   ", "value")
1205            .send()
1206            .await;
1207
1208        let err = match result {
1209            Err(err) => err,
1210            Ok(_) => panic!("空白 query key 应在发送前被拒绝"),
1211        };
1212
1213        assert!(matches!(
1214            err,
1215            crate::error::BaseError::ParamInvalid(field, _) if field == "query"
1216        ));
1217    }
1218
1219    #[tokio::test]
1220    async fn test_send_rejects_invalid_bearer_token_before_network() {
1221        let builder = RequestBuilder::new(
1222            Client::new(),
1223            Method::GET,
1224            "http://127.0.0.1:1".to_string(),
1225            Duration::from_secs(30),
1226            10 * 1024 * 1024,
1227            Some("bad\r\ntoken".to_string()),
1228            None,
1229        );
1230
1231        let err = match builder.send().await {
1232            Ok(_) => panic!("非法 bearer token 应在网络请求前被拒绝"),
1233            Err(err) => err,
1234        };
1235
1236        assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "authorization"));
1237    }
1238
1239    #[tokio::test]
1240    async fn test_send_rejects_invalid_url_before_network() {
1241        let invalid_urls = ["not a url", "ftp://example.com/file"];
1242
1243        for url in invalid_urls {
1244            let builder = RequestBuilder::new(
1245                Client::new(),
1246                Method::GET,
1247                url.to_string(),
1248                Duration::from_secs(30),
1249                10 * 1024 * 1024,
1250                None,
1251                None,
1252            );
1253
1254            let err = match builder.send().await {
1255                Ok(_) => panic!("非法 URL 应在网络请求前被拒绝"),
1256                Err(err) => err,
1257            };
1258
1259            assert!(matches!(err, BaseError::ParamInvalid(field, _) if field == "url"));
1260        }
1261    }
1262
1263    #[test]
1264    fn test_is_idempotent_method_classification() {
1265        // 安全/幂等方法:默认允许重试
1266        for method in [
1267            Method::GET,
1268            Method::HEAD,
1269            Method::OPTIONS,
1270            Method::TRACE,
1271            Method::PUT,
1272            Method::DELETE,
1273        ] {
1274            assert!(
1275                is_idempotent_method(&method),
1276                "{method} 应被判定为幂等/安全方法"
1277            );
1278        }
1279
1280        // 非幂等方法:默认不参与重试
1281        for method in [Method::POST, Method::PATCH] {
1282            assert!(
1283                !is_idempotent_method(&method),
1284                "{method} 不应被判定为幂等方法"
1285            );
1286        }
1287    }
1288
1289    /// 起一个只计数、读完即断开的本地监听器,用于统计实际发起的请求次数。
1290    ///
1291    /// 返回 `(监听地址, 连接计数)`;监听线程随测试结束由进程回收。
1292    fn spawn_closing_listener() -> (
1293        std::net::SocketAddr,
1294        std::sync::Arc<std::sync::atomic::AtomicUsize>,
1295    ) {
1296        use std::io::Read;
1297        use std::sync::atomic::{AtomicUsize, Ordering};
1298        use std::sync::Arc;
1299
1300        let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("本地监听端口应可绑定");
1301        let addr = listener.local_addr().expect("应能取得监听地址");
1302        let counter = Arc::new(AtomicUsize::new(0));
1303        let counter_for_thread = Arc::clone(&counter);
1304
1305        std::thread::spawn(move || {
1306            for stream in listener.incoming() {
1307                let Ok(mut stream) = stream else { break };
1308                counter_for_thread.fetch_add(1, Ordering::SeqCst);
1309                // 读走请求后直接关闭连接,制造传输错误(而非可重试状态码)
1310                let mut buf = [0u8; 1024];
1311                let _ = stream.read(&mut buf);
1312            }
1313        });
1314
1315        (addr, counter)
1316    }
1317
1318    /// 非幂等的 POST 未 opt-in 时,即使启用了重试也只发送一次。
1319    /// 标记 ignore:发起真实连接,依赖网络栈行为,默认跳过。
1320    #[tokio::test]
1321    #[ignore = "依赖网络栈行为,发起真实连接;默认跳过"]
1322    async fn test_post_not_retried_without_opt_in() {
1323        let (addr, counter) = spawn_closing_listener();
1324        let client = crate::http::HttpClient::new(1).expect("HTTP client should be valid");
1325
1326        let result = client
1327            .post(&format!("http://{addr}/never"))
1328            .retry(RetryConfig {
1329                max_retries: 3,
1330                retry_on: vec![503],
1331                backoff_ms: 1,
1332                retry_non_idempotent: false,
1333                ..RetryConfig::default()
1334            })
1335            .send()
1336            .await;
1337
1338        assert!(result.is_err(), "监听器直接断开,应返回传输错误");
1339        // 给监听线程留出计数落定的时间
1340        tokio::time::sleep(Duration::from_millis(200)).await;
1341        assert_eq!(
1342            counter.load(Ordering::SeqCst),
1343            1,
1344            "非幂等 POST 未 opt-in 时只应发送一次"
1345        );
1346    }
1347
1348    /// 非幂等的 POST 显式 opt-in 后,重试仍然生效(耗尽 max_retries)。
1349    /// 标记 ignore:发起真实连接,依赖网络栈行为,默认跳过。
1350    #[tokio::test]
1351    #[ignore = "依赖网络栈行为,发起真实连接;默认跳过"]
1352    async fn test_post_retried_when_opted_in() {
1353        let (addr, counter) = spawn_closing_listener();
1354        let client = crate::http::HttpClient::new(1).expect("HTTP client should be valid");
1355
1356        let result = client
1357            .post(&format!("http://{addr}/never"))
1358            .retry(RetryConfig {
1359                max_retries: 3,
1360                retry_on: vec![503],
1361                backoff_ms: 1,
1362                retry_non_idempotent: true,
1363                ..RetryConfig::default()
1364            })
1365            .send()
1366            .await;
1367
1368        assert!(result.is_err(), "监听器直接断开,应返回传输错误");
1369        tokio::time::sleep(Duration::from_millis(200)).await;
1370        assert_eq!(
1371            counter.load(Ordering::SeqCst),
1372            4,
1373            "opt-in 后应发送 1 + max_retries 次"
1374        );
1375    }
1376}