//! 实例 id 生成:雪花号十进制串。 //! //! 上游 `RandomUtil.uuId()` = Yitter `nextId()` 的**十进制字符串**形态(≤19 位数字), //! **不是 UUID**。这里用「毫秒时间戳 | 12 位序列」的经典雪花口径, //! 保证同毫秒内单调递增、跨毫秒递增,量级与上游一致。 //! //! ⚠️ **同毫秒内序列用满(4096 个)时不得回绕** —— id 是主键,重复即插入失败。 //! 序列回绕且毫秒未前进时,状态机返回 `None`(必须等下一毫秒),绝不上吐重复 id。 use std::sync::atomic::{AtomicU64, Ordering}; use std::time::{SystemTime, UNIX_EPOCH}; /// 纪元:2020-09-13T12:26:40Z(毫秒)。只影响 id 的绝对值,不影响唯一性。 const EPOCH_MS: u64 = 1_600_000_000_000; /// 序列占 12 位(0..=4095)。 const SEQ_MASK: u64 = 0xFFF; /// 序列占 12 位 ⇒ 时间戳左移 12 位。 const TS_SHIFT: u32 = 12; /// 最近一次发出的 id:高 52 位是毫秒时间戳,低 12 位是序列。 static LAST: AtomicU64 = AtomicU64::new(0); /// 当前 Unix 毫秒(纪元偏移后)。 fn now_ms() -> u64 { SystemTime::now() .duration_since(UNIX_EPOCH) .map(|d| d.as_millis() as u64) .unwrap_or(0) .saturating_sub(EPOCH_MS) } /// 状态机:依据「已发出的 id」与「当前毫秒」算出下一个 id。 /// /// **纯函数**(不碰全局状态、不读时钟)⇒ 边界行为可被确定性地单测。 /// /// - `wall_ms > last_ts`:毫秒前进 ⇒ 序列归零; /// - `wall_ms == last_ts`:同毫秒 ⇒ 序列递增; /// - `wall_ms < last_ts`:**时钟回拨** ⇒ 沿用已记录的毫秒继续递增序列 /// (宁可让 id 的时间部分暂时停在过去,也绝不产出比已发出 id 更小的值)。 /// /// 返回 `None` = **序列已用满且毫秒未前进** ⇒ 必须等下一毫秒,不得回绕出重复 id。 fn advance(last: u64, wall_ms: u64) -> Option { let last_ts = last >> TS_SHIFT; let last_seq = last & SEQ_MASK; let ts = if wall_ms > last_ts { wall_ms } else { last_ts }; let seq = if wall_ms > last_ts { 0 } else { last_seq.wrapping_add(1) & SEQ_MASK }; // 序列回绕到 0 且毫秒未前进 ⇒ 本毫秒的 4096 个 id 已用尽,必须等下一毫秒。 if seq == 0 && last_seq == SEQ_MASK && ts == last_ts { return None; } Some((ts << TS_SHIFT) | seq) } /// 生成下一个 id(十进制字符串)。 /// /// **打包口径**:`id = (毫秒时间戳 << 12) | 序列`,序列 12 位 ⇒ 同毫秒最多 4096 个。 /// 打包后约 16 位十进制数字串,落在上游 `RandomUtil.uuId()` 同量级(≤19 位)。 pub fn next_id() -> String { loop { let last = LAST.load(Ordering::Relaxed); let Some(candidate) = advance(last, now_ms()) else { // 本毫秒序列已满 ⇒ 自旋等下一毫秒(不产出重复 id)。 std::thread::yield_now(); continue; }; match LAST.compare_exchange_weak(last, candidate, Ordering::Relaxed, Ordering::Relaxed) { Ok(_) => return candidate.to_string(), // 别的线程抢先了 ⇒ 重读重算。 Err(_) => continue, } } } #[cfg(test)] mod tests { use super::*; #[test] fn id_is_a_decimal_string_not_a_uuid() { let id = next_id(); assert!(!id.contains('-'), "id 不得是 UUID:{}", id); assert!( id.chars().all(|c| c.is_ascii_digit()), "id 必须是十进制数字串:{}", id ); assert!( (10..=19).contains(&id.len()), "id 长度应与上游同量级(≤19 位):{}", id ); } #[test] fn consecutive_ids_differ() { let a = next_id(); let b = next_id(); assert_ne!(a, b); } /// 5000 个 id 全部互不相同(覆盖同毫秒内序列递增的边界)、全数字、长度合法、严格递增。 #[test] fn many_ids_are_unique_and_strictly_increasing() { const N: usize = 5000; let mut prev: u64 = 0; let mut seen = std::collections::HashSet::with_capacity(N); for _ in 0..N { let id = next_id(); assert!( id.chars().all(|c| c.is_ascii_digit()), "id 必须是十进制数字串:{}", id ); assert!( (10..=19).contains(&id.len()), "id 长度应与上游同量级(≤19 位):{}", id ); let n: u64 = id.parse().expect("id 必可解析为 u64"); assert!(seen.insert(n), "id 重复:{}", id); assert!(n > prev, "id 必须严格递增:{} 之后是 {}", prev, n); prev = n; } assert_eq!(seen.len(), N); } /// 🔴 **回归**:同一毫秒内第 4097 个 id 不得与本毫秒的第一个 id 相同。 /// /// 旧实现用进程级全局 `SEQ`(从不在毫秒边界重置)+ 12 位掩码, /// 于是同毫秒内第 4097 个 id 会回绕到 seq=0,产出与本毫秒第一个 id **完全相同**的字符串 /// —— id 是主键,撞了就是插入失败。 /// /// 这里直接驱动纯状态机 `advance()`,把时钟钉死在同一个毫秒 ⇒ 确定性地覆盖该边界。 #[test] fn sequence_must_not_wrap_within_the_same_millisecond() { const MS: u64 = 1000; let mut last = advance(0, MS).expect("首个 id"); let first = last; // 本毫秒共 4096 个 id(seq 0..=4095)。 for i in 1..=(SEQ_MASK as u64) { last = advance(last, MS).expect("同毫秒内应仍有可用序列"); assert_eq!(last & SEQ_MASK, i, "序列应递增到 {}", i); assert_eq!(last >> TS_SHIFT, MS, "毫秒部分应不变"); } // 第 4097 个:序列已满 ⇒ 必须拒绝(None),而不是回绕成重复值。 assert_eq!( advance(last, MS), None, "同毫秒内序列用满时必须拒绝产出,不得回绕出重复 id" ); // 且回绕值 **恰好等于** 本毫秒首个 id —— 这就是旧实现会产出重复 id 的实证。 let wrapped = (MS << TS_SHIFT) | 0; assert_eq!( wrapped, first, "回绕值与首个 id 相同 ⇒ 旧实现会产出重复 id(本次改动已阻止该路径)" ); // 毫秒前进 ⇒ 序列归零,新值与本毫秒的所有 id 都不同。 let next_ms = advance(last, MS + 1).expect("新毫秒应可用"); assert_eq!(next_ms >> TS_SHIFT, MS + 1); assert_eq!(next_ms & SEQ_MASK, 0); assert_ne!(next_ms, first); } /// 时钟回拨:沿用已记录的毫秒继续递增序列,id 不倒退。 #[test] fn clock_rollback_keeps_ids_monotonic() { let mut last = advance(0, 1000).expect("首个 id"); let first = last; last = advance(last, 1000).expect("同毫秒"); // 墙钟往回拨到 500(< 已记录的 1000)⇒ 沿用 1000。 let rolled = advance(last, 500).expect("回拨不应拒绝"); assert_eq!(rolled >> TS_SHIFT, 1000, "应沿用已记录的毫秒"); assert!(rolled > first, "回拨时 id 不得倒退"); } }