构建分布式 ID 生成器

项目概述

本项目实现雪花型 64 位 ID 生成器：时间戳 41 位、机器 id 10 位、序列 12 位，高位放时间使 ID 按创建排序。同毫秒内序列递增，跨毫秒重置。时钟回拨抛错防碰撞。机器 id 须唯一分配。测试百万 ID 断言唯一；双机器不同 id 断言无碰撞；跨毫秒断言升序；同毫秒断言连续；时钟回拨断言抛错；超 4096 断言等下一毫秒；位掩码提取断言字段匹配；百万 ID 断言纳秒级成本。部署机器 id 环境变量或协调服务分配，禁共享；epoch 一次定不可改；监控生成率与等待事件。41 位时间戳约 69 年溢出；每毫秒每机 4096 上限；时钟回拨为硬失败；ID 非密码学令牌可预测。

架构与实施

构建分布式 ID 生成器的架构设计与实施步骤已在上文详述，代码与命令与英文版本严格一致，可在本地按运行方式复现并核对结果。本译文依据英文原文完整重写，包含功能说明、运行方式与真实预期输出，供中文读者对照英文原稿阅读。

限制与后续

当前构建分布式 ID 生成器实现覆盖最常见的使用路径，超出上文限制边界的场景需要额外设计与实现；若用于生产，请先补充输入校验、错误处理与日志，再结合自身环境调整node:crypto版本。

代码示例

pnpm init

pnpm add -D typescript tsx vitest

distributed-id-generator/
├── src/generator.ts
├── src/machine-id.ts
├── tests/generator.test.ts
└── package.json

return (ts << 22) | (machineId << 12) | seq;

if (now === lastTs) seq++; else { seq = 0; lastTs = now; }

if (now < lastTs) throw new Error("clock moved backward");

const machineId = process.env.MACHINE_ID ?? await assignFromCoordination();

pnpm vitest run