Skip to main content

yang_base/action/
request_id.rs

1//! 请求标识(request_id)
2//!
3//! 一次 Action 派发的运行期标识,用于串联日志、span、metrics、审计。放在
4//! [`ActionContext`](crate::action::ActionContext) 上(运行期上下文),而非
5//! [`Request`](crate::action::Request)(传输输入),避免污染请求数据模型。
6//!
7//! 类型刻意选 `u128` 轻量结构(时间高位 | 计数器低位),不引入 uuid 依赖:
8//! - 高 64 位:生成时刻的毫秒级 Unix 时间戳(粗略有序,便于按时间排查)
9//! - 低 64 位:进程内单调递增计数器(同一毫秒内去重)
10//!
11//! 注意:这是**进程内**唯一标识,不保证跨进程全局唯一。需要跨服务串联时,由
12//! 上游通过 `X-Request-Id` header 传入字符串,[`RequestIdMiddleware`] 会优先透传。
13
14use std::borrow::Cow;
15use std::fmt;
16use std::sync::atomic::{AtomicU64, Ordering};
17
18/// 进程内单调计数器(request_id 低位来源)。
19static COUNTER: AtomicU64 = AtomicU64::new(0);
20
21/// 一次 Action 派发的运行期标识。
22///
23/// `Display` 输出为 32 位十六进制(无分隔),便于日志检索:
24/// 形如 `0192f4a1c3d50000000000000000002a`。
25#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
26pub struct RequestId(u128);
27
28impl RequestId {
29    /// 生成一个新的 request_id(时间高位 | 计数器低位)。
30    ///
31    /// 单次整数运算 + 一次原子自增,无堆分配,满足热路径零分配要求。
32    pub fn generate() -> Self {
33        // chrono 毫秒时间戳作高位;为负(1970 前,理论不会)时按 0 处理
34        let millis = chrono::Utc::now().timestamp_millis().max(0) as u128;
35        let counter = COUNTER.fetch_add(1, Ordering::Relaxed) as u128;
36        RequestId((millis << 64) | counter)
37    }
38
39    /// 从已有 u128 构造(供从上游标识解析时使用)。
40    pub fn from_u128(v: u128) -> Self {
41        RequestId(v)
42    }
43
44    /// 取出底层 u128。
45    pub fn as_u128(&self) -> u128 {
46        self.0
47    }
48
49    /// 解析上游 `X-Request-Id` 为 RequestId(供透传跨服务标识)。
50    ///
51    /// 接受形式:
52    /// - 1..=32 位十六进制(无分隔),如 `2a`、`0192f4a1c3d5...`;
53    /// - 标准 UUID(带连字符,如 `550e8400-e29b-41d4-a716-446655440000`)——
54    ///   去连字符后恰为 32 位十六进制,覆盖最常见的上游标识与 W3C traceparent 的
55    ///   trace-id 段。
56    ///
57    /// 非十六进制、全零值或去连字符后超 32 位返回 `None`,调用方据此降级为新生成。
58    ///
59    /// **限制**:`RequestId` 底层是 `u128`,无法承载任意字符串标识(如纯字母 trace
60    /// id)。这类上游标识会被拒绝并降级——若需端到端透传任意字符串标识,应在传输层
61    /// 自行记录原始 header,本类型只负责进程内可排序的数值标识。
62    pub fn parse_hex(s: &str) -> Option<Self> {
63        let s = s.trim();
64        // PERF-15: 用 Cow 避免无连字符时的多余分配
65        let normalized = if s.contains('-') {
66            Cow::Owned(s.replace('-', ""))
67        } else {
68            Cow::Borrowed(s)
69        };
70        if normalized.is_empty() || normalized.len() > 32 {
71            return None;
72        }
73        u128::from_str_radix(&normalized, 16)
74            .ok()
75            .filter(|value| *value != 0)
76            .map(RequestId)
77    }
78}
79
80impl fmt::Display for RequestId {
81    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
82        // 32 位定宽十六进制,前导零补齐,便于对齐与检索
83        write!(f, "{:032x}", self.0)
84    }
85}
86
87impl Default for RequestId {
88    fn default() -> Self {
89        Self::generate()
90    }
91}
92
93#[cfg(test)]
94mod tests {
95    use super::*;
96
97    #[test]
98    fn generate_is_monotonic_within_process() {
99        let a = RequestId::generate();
100        let b = RequestId::generate();
101        // 低位计数器严格递增,故同进程内 b > a(即便同毫秒)
102        assert_ne!(a, b, "连续生成的 request_id 不应相同");
103        assert!(b.as_u128() > a.as_u128(), "request_id 应单调递增");
104    }
105
106    #[test]
107    fn display_is_32_hex_chars() {
108        let id = RequestId::from_u128(0x0192_f4a1_c3d5_0000_0000_0000_0000_002a);
109        let s = id.to_string();
110        assert_eq!(s.len(), 32, "应为 32 位定宽十六进制: {}", s);
111        assert!(s.chars().all(|c| c.is_ascii_hexdigit()));
112    }
113
114    #[test]
115    fn parse_hex_roundtrip() {
116        let id = RequestId::from_u128(0xdead_beef);
117        let parsed = RequestId::parse_hex(&id.to_string()).expect("应能解析");
118        assert_eq!(id, parsed);
119    }
120
121    #[test]
122    fn parse_hex_rejects_invalid() {
123        assert!(RequestId::parse_hex("").is_none());
124        assert!(RequestId::parse_hex("xyz").is_none());
125        // 超过 32 位
126        assert!(RequestId::parse_hex(&"f".repeat(33)).is_none());
127    }
128
129    #[test]
130    fn parse_hex_accepts_upstream_short_form() {
131        let parsed = RequestId::parse_hex("2a").expect("短十六进制应可解析");
132        assert_eq!(parsed.as_u128(), 0x2a);
133    }
134
135    /// NEW-7:标准带连字符 UUID 去连字符后应可解析(覆盖最常见上游标识)。
136    #[test]
137    fn parse_hex_accepts_hyphenated_uuid() {
138        let uuid = "550e8400-e29b-41d4-a716-446655440000";
139        let parsed = RequestId::parse_hex(uuid).expect("UUID 应可解析");
140        assert_eq!(parsed.as_u128(), 0x550e8400_e29b_41d4_a716_446655440000);
141        // 纯字母 trace id 仍拒绝(u128 无法承载),降级为新生成
142        assert!(RequestId::parse_hex("not-a-hex-id-zz").is_none());
143    }
144}