- envelope: 补 impl IntoResponse(状态码恒 200,业务成败只由 body.code 表达) - config: 认规格名 TDC_LOCAL_STANDALONE(TDC_STANDALONE 保留为别名); 抽 env_or_default 统一处理空串/纯空白回落 - ids: 改毫秒+12位序列打包 + CAS 循环,序列用满时拒绝产出而非回绕出重复 id; 修正纪元注释(1_600_000_000_000 = 2020-09-13) Co-Authored-By: Claude Code <[email protected]>
184 lines
7.3 KiB
Rust
184 lines
7.3 KiB
Rust
//! 实例 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<u64> {
|
||
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 不得倒退");
|
||
}
|
||
}
|