Files
tdc-rs/src/ids.rs
T
adminandClaude Code 43fcefc6ab fix(contract): 补 ActionResult 的 IntoResponse;修配置变量名与雪花号回绕
- 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]>
2026-10-24 14:36:17 +08:00

184 lines
7.3 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! 实例 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 不得倒退");
}
}