wordval-utils 1.0.8

Wordval utilities: string manipulation, date handling, masking, ID generation, validation, crypto, web helpers, collection tools, retry utilities
Documentation
//! 短 ID 生成器:基于 UUID v4/v7 或雪花算法

use rand::Rng;
use std::sync::Mutex;
use std::sync::OnceLock;
use std::time::{SystemTime, UNIX_EPOCH};

use crate::Crypto;

/// 短 ID 生成器
///
/// 提供 UUID v4/v7、雪花 ID、TSID、短 ID、微型 ID 等分布式唯一标识生成。
///
/// # 雪花 ID 用法
///
/// ```ignore
/// Sid::init_snowflake(1);       // 应用启动时初始化 worker_id
/// let id: u64 = Sid::snowflake(); // 生成雪花 ID
/// ```
pub struct Sid;

// ═══════════════════════════════════════════════════════
// 雪花 ID(Snowflake)—— 线程安全,无并发重复
// ═══════════════════════════════════════════════════════

/// 雪花 ID 生成器内部结构(Mutex 保护,防并发重复)
#[derive(Debug)]
struct Snowflake {
    epoch: u64,
    worker_id: u64,
    /// 最后生成的毫秒时间戳
    last_timestamp: u64,
    /// 当前毫秒内的序列号(0-4095)
    sequence: u16,
}

impl Snowflake {
    fn new(worker_id: u64) -> Self {
        let epoch = 1704067200000u64; // 2024-01-01 00:00:00 UTC
        Self {
            epoch,
            worker_id,
            last_timestamp: 0,
            sequence: 0,
        }
    }

    /// 生成下一个唯一 ID(Mutex 保护,线程安全)
    fn next_id(&mut self) -> u64 {
        let mut ts = Self::now_ms();

        // 时钟回拨保护
        if ts < self.last_timestamp {
            // 最多等待时钟追上
            for _ in 0..10 {
                ts = Self::now_ms();
                if ts >= self.last_timestamp {
                    break;
                }
                std::thread::sleep(std::time::Duration::from_millis(1));
            }
            if ts < self.last_timestamp {
                // 时钟严重回拨,使用最后时间戳继续(可能导致序列号溢出但保证不重复)
                ts = self.last_timestamp;
            }
        }

        if ts == self.last_timestamp {
            // 同一毫秒:递增序列号
            self.sequence += 1;
            if self.sequence >= 4096 {
                // 当前毫秒序列号用尽,等待下一毫秒
                loop {
                    ts = Self::now_ms();
                    if ts != self.last_timestamp {
                        break;
                    }
                    std::thread::sleep(std::time::Duration::from_millis(1));
                }
                self.sequence = 0;
                self.last_timestamp = ts;
            }
        } else {
            // 新毫秒:重置序列号
            self.sequence = 0;
            self.last_timestamp = ts;
        }

        ((ts - self.epoch) << 22) | (self.worker_id << 12) | self.sequence as u64
    }

    fn now_ms() -> u64 {
        SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap_or_default()
            .as_millis() as u64
    }
}

static SNOWFLAKE: OnceLock<Mutex<Snowflake>> = OnceLock::new();

impl Sid {
    /// 初始化雪花 ID 生成器(应用启动时调用一次)
    pub fn init_snowflake(worker_id: u64) {
        assert!(worker_id < 1024, "worker_id must be less than 1024");
        SNOWFLAKE
            .set(Mutex::new(Snowflake::new(worker_id)))
            .expect("Snowflake already initialized");
    }

    /// 生成雪花 ID(64 位整数,线程安全,无并发重复)
    pub fn snowflake() -> u64 {
        SNOWFLAKE
            .get()
            .expect("Snowflake not initialized — call Sid::init_snowflake(worker_id) first")
            .lock()
            .unwrap_or_else(|e| e.into_inner()) // 中毒恢复:内部状态仍一致
            .next_id()
    }

    // ═══════════════════════════════════════════════════════
    // UUID / 短 ID
    // ═══════════════════════════════════════════════════════

    /// 生成 UUID v4 原始字节(版本 4 + variant 10,自研实现,替代 uuid crate)
    fn uuid_v4_bytes() -> [u8; 16] {
        let mut b = [0u8; 16];
        rand::thread_rng().fill(&mut b);
        b[6] = (b[6] & 0x0f) | 0x40; // version = 4
        b[8] = (b[8] & 0x3f) | 0x80; // variant = 10
        b
    }

    /// 32 位 UUID v4(无连字符)
    pub fn uuid() -> String {
        Crypto::encode_hex(&Self::uuid_v4_bytes())
    }

    /// 标准 UUID v4(36 字符带连字符格式,等价 `Uuid::new_v4().to_string()`)
    pub fn uuid_v4() -> String {
        let b = Self::uuid_v4_bytes();
        format!(
            "{:02x}{:02x}{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}-{:02x}{:02x}{:02x}{:02x}{:02x}{:02x}",
            b[0], b[1], b[2], b[3], b[4], b[5], b[6], b[7], b[8], b[9], b[10], b[11], b[12], b[13], b[14], b[15],
        )
    }

    /// 短 ID(16 位 hex)
    pub fn short() -> String {
        Crypto::encode_hex(&Self::uuid_v4_bytes()[..8])
    }

    /// 极短 ID(8 位 hex)——用于临时标识
    pub fn tiny() -> String {
        Crypto::encode_hex(&Self::uuid_v4_bytes()[..4])
    }

    /// 基于时间戳的 20 位短 ID(毫秒级唯一)
    pub fn tsid() -> String {
        let ts = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap_or_default()
            .as_millis();
        let rand: u32 = rand::random();
        format!("{:013x}{:07x}", ts, rand & 0x0FFFFFFF)
    }

    /// UUID v7(时间有序,更适合数据库主键;自研实现,替代 uuid crate)
    pub fn uuid7() -> String {
        let mut b = [0u8; 16];
        let ms = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap_or_default()
            .as_millis();
        b[..6].copy_from_slice(&ms.to_be_bytes()[10..16]); // 48 位毫秒时间戳(u128 大端的低 6 字节)
        // 10 字节随机数:12 位 rand_a(b[6] 低 4 位 + b[7])+ 62 位 rand_b(b[8] 低 6 位 + b[9..16])
        let mut r = [0u8; 10];
        rand::thread_rng().fill(&mut r);
        b[6] = 0x70 | (r[0] >> 4); // version = 7 + rand_a 高 4 位
        b[7] = (r[0] << 4) | (r[1] >> 4); // rand_a 低 8 位
        b[8] = 0x80 | (r[2] >> 2); // variant = 10 + rand_b 高 6 位
        b[9..].copy_from_slice(&r[3..10]); // rand_b 低 56 位
        Crypto::encode_hex(&b)
    }

    /// 带前缀的业务 ID,如 "ORD" + uuid7 → "ORD_0192331a..."
    pub fn biz_id(prefix: &str) -> String {
        format!("{}_{}", prefix, Self::uuid7())
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::HashSet;

    #[test]
    fn test_snowflake_monotonic() {
        // 直接实例化,避免并行测试竞争全局 OnceLock
        let mut sf = Snowflake::new(1);
        let a = sf.next_id();
        let b = sf.next_id();
        assert!(b > a);
    }

    #[test]
    fn test_snowflake_no_duplicates() {
        let mut sf = Snowflake::new(42);
        let mut set = HashSet::new();
        for _ in 0..10_000 {
            let id = sf.next_id();
            assert!(set.insert(id), "Duplicate snowflake ID: {}", id);
        }
    }

    #[test]
    fn test_short() {
        assert_eq!(Sid::short().len(), 16);
    }

    #[test]
    fn test_tiny() {
        assert_eq!(Sid::tiny().len(), 8);
    }

    #[test]
    fn test_uuid() {
        assert_eq!(Sid::uuid().len(), 32);
    }

    #[test]
    fn test_uuid_v4_hyphenated() {
        let id = Sid::uuid_v4();
        assert_eq!(id.len(), 36);
        let segs: Vec<usize> = id.split('-').map(|s| s.len()).collect();
        assert_eq!(segs, vec![8, 4, 4, 4, 12]);
        // 版本位应为 4(第 15 个字符),变体位应为 8/9/a/b(第 20 个字符)
        assert_eq!(&id[14..15], "4");
        assert!(matches!(&id[19..20], "8" | "9" | "a" | "b"));
        assert!(id.chars().all(|c| c.is_ascii_hexdigit() || c == '-'));
    }

    #[test]
    fn test_uuid7() {
        let id = Sid::uuid7();
        assert_eq!(id.len(), 32);
        // 版本位应为 7(第 13 个 hex 字符)
        assert_eq!(&id[12..13], "7");
    }

    #[test]
    fn test_biz_id() {
        let id = Sid::biz_id("ORD");
        assert!(id.starts_with("ORD_"));
        assert_eq!(id.len(), 4 + 32); // 前缀 + 下划线 + uuid7
    }
}