做过分布式服务的同学都知道，全局唯一ID看着不难，真做起来全是细节。数据库自增ID在单机时代很好使，一旦拆成多实例就乱了；UUID v4虽然全球唯一，但作为MySQL主键会让B+树频繁页分裂，日志里排查问题也看不出先后顺序。在这个背景下，我最后选了Twitter开源那套“雪花算法”（Snowflake）的思路，用Lua 5.3+在OpenResty环境里自己实现了一个ID生成器。这篇文章就把整条实现链路、踩过的坑、压测结论和生产落地经验完整写出来，给同样在Lua生态里做分布式ID的同学一个可以直接抄作业的参考。
纯Lua写雪花算法，在Lua 5.3之前其实挺别扭。早期Lua只有double一种数字类型，64位整数存不准，位运算还得靠bit32这种库来凑；到了Lua 5.3，原生引入了integer子类型和&、|、<<、>>这套位运算符，雪花算法的64位ID构造终于可以在纯Lua里干净利落地完成。这篇文章适合三类人：在Nginx/OpenResty里写Lua的业务开发者，想用Redis Lua脚本做发号器但没有头绪的人，以及纯粹对“一个语言特性如何决定一个算法实现方式”感兴趣的同学。
1. 先拆开雪花算法的64位：为什么这串数字能全局唯一还带时间信息
1.1 分布式ID的硬指标：唯一、有序、有含金量
在谈雪花算法之前，得先明确分布式ID要满足什么。最简单粗暴的理解就三条：第一，全局不重复；第二，最好趋势递增，让数据库索引友好、日志可读；第三，ID本身最好能看出一些业务信息，而不是一串无意义的随机数字。
UUID在这三个维度上全挂。UUID是128位，作为字符串占空间大，作为主键还是二进制形式也一样会让索引变得松散，而且完全无序——插入时B+树节点不断分裂，写性能会肉眼可见地下降。Redis自增ID解决了唯一性和顺序性，但它是中心化的，Redis一旦出问题，整个发号链路就断了。数据库号段模式（比如Leaf的segment方案）虽然没有中心化这么脆弱，但引入了一个额外的协调组件，架构复杂度上去了。
雪花算法的聪明之处在于：它把ID做成一个64位整数，通过位段划分让“时间”和“机器”各自占据固定的bit，再用一个序列号兜底。生成时不需要依赖中心服务器，每个节点独立计算，只要节点ID不冲突、系统时钟不回拨，生成的ID就是全局唯一的。而且因为高位是时间戳，ID在整体上是单调递增的，这正好命中了分布式ID的核心诉求。
1.2 位段设计：41位时间、10位节点、12位序列
经典雪花算法的64位长这样，第一位是符号位，固定为0（保证ID是正数），后面三段各自分工：
| 位段 | 占用bit | 作用 | 能表达的范围 |
|---|---|---|---|
| 符号位 | 1 | 恒为0，保证ID为正整数 | 固定值0 |
| 时间戳 | 41 | 从自定义纪元（epoch）开始的毫秒数 | 2^41毫秒，约69年 |
| 节点ID | 10 | 区分机器/进程/worker | 0~1023，最多1024个节点 |
| 序列号 | 12 | 同一毫秒内的自增值 | 0~4095，每毫秒4096个ID |
说几个容易被忽略的数字。41位时间戳如果用Unix epoch（1970年）算，现在已经走了超过一半，所以业界普遍会自定义一个较近的起始时间。比如以2020年1月1日零点为epoch，那么41位足够用到2089年，对绝大多数业务来说完全够用了。10位节点ID意味着最多1024个生成节点，如果你的实例超过这个数，要么拆成“5位机房+5位机器”，要么把位数比例调整成时间41、机器15、序号7。12位序列号意味着单个节点每毫秒最多生成4096个ID，每秒约409.6万，这个理论值在单进程Lua里几乎摸不到，但作为并发兜底是足够的。
位段设计还有一个好处：ID可解析。你在日志里看到一个雪花算法ID，可以直接从高位还原出它是什么时间生成的、由哪个节点生成的、同毫秒内的第几号，这对线上问题定位简直是救命级别的好处。后面我会给一个完整的解析函数。
1.3 为什么必须是Lua 5.3+：原生整数和位运算
这是很多人没想明白的地方。Lua 5.1和5.2时代的数字只有number一种类型，其实就是双精度浮点数。双精度能精确表达的整数范围是2^53以内，而雪花算法要把41位时间戳左移22位，峰值会超过2^53，直接做会丢精度。Lua 5.3引入了integer子类型，64位有符号整数可以完整表达雪花算法的ID范围，再加上原生位运算符，一行<<就能完成位段拼装。
另外还有一个非常隐蔽的坑：Lua 5.3的位运算要求操作数必须是整数，如果你拿一个带小数的浮点数去做<<，直接报错“attempt to perform ‘<<’ on a float value”。所以从时间源拿到的毫秒值必须先用math.floor或//转成整数，再参与位运算。这一点可以说是整个Lua实现里最容易翻车的位置，后面代码里我会刻意处理。
2. 一个能直接用的纯Lua雪花算法模块
2.1 时间源选型：os.time不够用，ngx与socket是两条主线
雪花算法对时间精度要求是毫秒级。Lua标准库的os.time()只能拿到秒级时间戳，直接拿来做雪花算法会造成严重碰撞——同一秒内大量ID都靠序列号硬撑，4096的余量瞬间打满。所以在纯Lua环境里，要解决“毫秒时间戳从哪来”的问题。
主流方案是这三个：
| 时间源 | 精度 | 适用场景 | 注意点 |
|---|---|---|---|
| os.time() | 秒 | 本地快速验证 | 精度太低，不能直接用于生产 |
| LuaSocket的socket.gettime() | 微秒级浮点 | 标准Lua环境 | 需要安装luasocket |
| OpenResty的ngx.now() | 毫秒/微秒级浮点 | OpenResty环境 | 返回的是浮点秒数，要乘1000取整 |
我的建议是：把时间源做成一格可注入的函数，而不是在模块里写死。这样既能适配不同运行环境，也能在单元测试里用mock时间戳去逼出序列号溢出、时钟回拨等边界情况。下面代码里的now()就是这个设计。
获取到浮点秒数后必须转成整数毫秒：math.floor(socket.gettime() * 1000)或者math.floor(ngx.now() * 1000)。千万别在没取整的情况下直接塞进位运算，这是Lua 5.3实现雪花算法最常见的报错现场。
2.2 完整模块代码与关键行注释
下面这个模块是我在实际项目中使用的精简版，去掉了无关的健壮性包装，保留核心逻辑和注释，方便你直接理解并复刻。
-- snowflake.lua -- Lua 5.3+ 雪花算法 ID 生成器 -- 结构：0 | 41bit 时间戳 | 10bit 节点ID | 12bit 序列号 local floor = math.floor local M = {} -- 位段参数 local NODE_BITS = 10 local SEQUENCE_BITS = 12 local MAX_NODE = (1 << NODE_BITS) - 1 -- 1023 local MAX_SEQUENCE = (1 << SEQUENCE_BITS) - 1 -- 4095 local NODE_SHIFT = SEQUENCE_BITS local TIMESTAMP_SHIFT = NODE_BITS + SEQUENCE_BITS -- 自定义纪元：2020-01-01 00:00:00 UTC，单位毫秒 local EPOCH_MS = 1577836800000 -- 时间源：默认用 LuaSocket，OpenResty 下会自动切换为 ngx.now() local function default_now() if ngx and ngx.now then return floor(ngx.now() * 1000) -- ngx.now() 返回秒的浮点数 end local socket = require("socket") if socket and socket.gettime then return floor(socket.gettime() * 1000) -- luasocket 返回秒的浮点数 end return os.time() * 1000 -- 保底方案，精度只有秒 end function M.new(node_id, opts) opts = opts or {} if type(node_id) ~= "number" or node_id < 0 or node_id > MAX_NODE then error("invalid node_id, must be 0~" .. MAX_NODE) end local now = opts.now or default_now return setmetatable({ node_id = node_id, now = now, last_ts = 0, seq = 0, }, { __index = M }) end -- 生成下一个ID function M:next_id() local ts = self:now() -- 时钟回拨保护 if ts < self.last_ts then error("clock moved backwards, refuse to generate id") end if ts == self.last_ts then -- 同一毫秒内，序列号自增，并用位与快速取模 self.seq = (self.seq + 1) & MAX_SEQUENCE if self.seq == 0 then -- 序列号用完了，自旋等待下一毫秒 while ts <= self.last_ts do ts = self:now() end end else -- 新的一毫秒，序列号归零 self.seq = 0 end self.last_ts = ts -- 核心拼装：时间戳左移22位，节点ID左移12位，序列号放最低位 return ((ts - EPOCH_MS) << TIMESTAMP_SHIFT) | (self.node_id << NODE_SHIFT) | self.seq end -- 反解ID：调试和日志排查时非常有用 function M.parse(id) local seq = id & MAX_SEQUENCE local node_id = (id >> NODE_SHIFT) & MAX_NODE local ts = (id >> TIMESTAMP_SHIFT) + EPOCH_MS return ts, node_id, seq end return M这个模块的核心逻辑不复杂，但每个细节都有讲究。seq = (self.seq + 1) & MAX_SEQUENCE代替了% 4096，位运算比取模要快，而且当序列号从4095回到0时，我们正好用seq == 0来判断“当前毫秒已耗尽”。while ts <= self.last_ts这个自旋循环是为了在毫秒边界上等出下一个时间戳，它保证了即使单节点每毫秒请求超过4096次，也不会产出重复ID。
2.3 ID的配方和反解：左移、掩码与一次解析函数
很多人看雪花算法代码，对“左移”和“或”这两步比较懵。我用一个简洁例子拆开讲。假设当前时间与epoch相差1000毫秒，节点ID是5，序列号是7，那么：
- 时间戳左移22位：
1000 << 22，在二进制里相当于把1000一直挪到最高位段，低22位全部补0。 - 节点ID左移12位：
5 << 12，节点信息落在中间段。 - 序列号
7直接放最低12位。 - 三段用按位或
|拼在一起，因为各自的bit区间互不重叠，所以或运算等价于直接拼接。
这是理解雪花算法代码的第一道坎。第二道坎是解析时为什么要用右移和与运算。id >> 22把时间戳从高位挪回低位，再用& MAX_NODE把节点段“截”出来，本质上就是按位段提取字段。这两个操作是互逆的：拼装用左移和或，拆解用右移和与。理解了这套规则，你甚至可以自定义位段分配比例，而不用被标准结构绑死。
我在生产环境里经常用M.parse(id)做日志对比。比如两条ID看起来都在短时间内生成，解析后发现时间戳差了十几毫秒，说明一个请求在排队；如果两条ID解析出来的节点ID相同，而业务层面请求来自两个不同实例，那就说明节点ID分配出问题了。这种排障效率是UUID完全给不了的。
3. 分布式环境下绕不开的三个大坑
3.1 时钟回拨：检测、容忍与等待策略
雪花算法最怕的就是系统时钟往回跳。回拨可能来自NTP时间同步、运维手动校时、虚拟机迁移后时钟漂移校准。一旦发生回拨，同一套“时间戳+节点ID+序列号”组合可能重复生成，直接破坏全局唯一性。
我的处理分三档，按回拨幅度决定策略：
| 回拨幅度 | 处理策略 | 适用场景 |
|---|---|---|
| 0，即未回拨 | 正常生成 | 99.9%的情况 |
| 小于阈值（如5ms） | 自旋等待时间追上来，不拒绝请求 | 轻微抖动，NTP频繁小幅校准 |
| 大于阈值 | 直接抛错，拒绝生成 | 明显手动改时间或严重漂移 |
代码里目前是“发现回拨就抛错”的最严策略，生产上可以改成：先判断回拨了多少，如果小于阈值就短等待，超过阈值才抛异常。网上还有一种基于“上次请求阻塞时间”来延迟补偿的做法，复杂度和收益不成正比，除非你的ID量级大到每秒百万以上，否则不建议一上来就上那套。
要补充的是，Lua应用层能做的是检测和降级，并不能阻止操作系统层面回拨。想要真正“免疫”回拨，只能在判断到回拨时换一个备用序列段或让节点短暂下线，这些都属于对基础算法的大改造，小团队慎用。
3.2 同一毫秒序列号耗尽：自旋等待的代价和优化
单节点在极高峰值下，同一毫秒内会超过4096个ID请求。我们的方案是序列号归零后自旋等待下一毫秒，代价是这一毫秒内的额外请求会阻塞。这个阻塞通常只有不到1ms，对大多数业务无感。
但要注意的是：标准Lua是单线程的，如果在这个模块的运行环境里还有其他逻辑在同一线程执行，那么自旋等待会阻塞整个线程。在OpenResty中，Lua代码跑在event loop里，阻塞一毫秒虽然短，但在高并发下会拖累同进程其他请求，所以“等待下一毫秒”这个设计在OpenResty里要谨慎——它不是不能等，而是要让这个等发生的概率尽可能低。我的做法是把序列号位数从12提升到更高的分配方案，或者干脆把请求分散到不同worker节点，让每个节点承载的QPS降到4096/ms以下。
3.3 worker_id从哪来：静态配置、Redis分配与OpenResty的worker_id
雪花算法要求每个节点有唯一ID。最简单的是配置文件静态写死，适合服务实例数量固定的小规模集群。缺点是扩缩容要改配置，而且人手工配置容易重复，重复节点ID会导致同ms内产生重复ID。
第二个方案是用Redis分配：每个服务启动时执行INCR，把结果对1024取模得到节点ID，再写入本地配置文件。这个方案的好处是自动化和唯一性有保障，坏处是如果实例频繁重启，节点ID会不断轮换，日志里同一服务的节点ID显得很“飘”，排查问题时要额外换算。
在OpenResty环境里其实有一个更优雅的玩法：直接用ngx.worker.id()。每个Nginx worker进程有一个从0开始的编号，天然唯一且稳定。只要worker数量不超过1024，直接用这个编号作为节点ID即可，零额外依赖。多实例部署时再叠加一层机器标识，比如“机房ID=0~3，workerID=ngx.worker.id()%256”，形成5+5的拆分布局。
4. 压测、去重与解析验证：不是能跑就行，要能证明
4.1 mock时间源把边界条件测一遍
算法实现完，第一件事不是压测，而是先把边界条件打一遍。因为真实时钟没法控制，我写测试时用mock时间源替代，验证这三个场景：
- 同一毫秒连续生成4096个ID，第4097个会阻塞到下一毫秒，且不重复。
- 时间戳回拨1ms时，模块是否抛错；回拨5ms内配置了容忍策略时，是否正常生成。
- 生成ID后立即解析，时间、节点ID、序列号是否和输入一致。
mock方式很简单：给new(node_id, {now = function() return mock_ts end})传一个可控函数即可。我在测试里用mock_ts变量不断调整值，把边界情况逐一逼出来。这个“依赖注入时间源”的设计，强烈建议保留，否则你很难在本地验证回拨逻辑。
4.2 百万级唯一性与趋势性验证
边界测通后，再做大数据量验证。我的做法是循环生成100万个ID，分别塞进三个结构验证：
| 验证项 | 方法 | 预期结果 |
|---|---|---|
| 唯一性 | 写入Lua table，重复会覆盖 | 无覆盖，table长度=1000000 |
| 趋势性 | 记录相邻ID差值 | 差值为正，且通常≤NODE段偏移量 |
| 可解析性 | 随机抽1000个ID做parse反向计算 | 时间戳与生成时一致 |
实际跑下来，唯一性和趋势性都OK。唯一要注意的是内存：100万个ID的table在Lua里占的内存不小，测试完及时置nil，别在压测环境里反复跑不释放。
4.3 性能参考数据和瓶颈在哪
我在本地一台普通笔记本上用PUC-Lua 5.3跑，循环生成百万级ID，顺带做了去重和解析，整体耗时约2到3秒。这个数字仅供参考，因为瓶颈主要是Lua解释执行和系统时间调用本身的成本。在LuaJIT环境下，纯Lua位运算的开销会再低一个量级，但JIT对浮点到整数的转换也可能有微妙影响，你要是用LuaJIT，建议单独压一遍。
还有一个很容易被忽视的性能点：时间源调用的开销。ngx.now()和socket.gettime()都是系统调用级别，在高频调用下会对每秒生成量产生明显影响。如果你只需要在本进程中保证唯一性，可以把时间源缓存几毫秒，用一个进程内计数器在缓存窗口内自增生成多个ID，减少时间调用次数，但这会牺牲ID的“高精度时间排序性”，取舍要看业务。
5. 生产落地：OpenResty场景改造与Redis中心化发号的取舍
5.1 OpenResty多worker的互不干扰方案
OpenResty每个worker进程是独立的Lua VM，全局变量不共享。如果多个worker都从node_id=0启动，同一毫秒内就可能撞车。我在落地时采用了“worker_id即节点ID”的思路：
-- init_worker_by_lua_block 里给每个进程分配独立实例 local snowflake = require("snowflake") local worker_id = ngx.worker.id() -- 0,1,2... local id_gen = snowflake.new(worker_id) -- 进程内单例配合lua_shared_dict，还可以做一个全局的周期状态检查，确保没有两个worker拿到相同ID。实际上ngx.worker.id()在Nginx worker数不超过1024时天然唯一，所以这个方案最简单也最可靠。如果你的OpenResty有多个Nginx实例，则在init阶段把机器维度也拼进节点ID号段。
5.2 Redis Lua脚本为什么看起来很美但通常不如本地生成
很多团队想用Redis Lua脚本做中心化发号器，因为Redis的EVAL脚本原子执行，不需要在业务侧考虑并发锁。想法很好，但这里有两个硬伤。
第一个硬伤是Redis内置的Lua是5.1版本，没有原生位运算符，得用bit或bit32库来模拟<<和|，代码写起来丑，而且难以复用Lua 5.3上面那套模块。第二个硬伤更致命：Redis单机QPS一般在10万量级，而雪花算法单节点理论每秒生成400多万个ID，把发号能力押在Redis上等于把一个本地无锁算法降级成中心化瓶颈。
我的建议很明确：Redis只用来做节点ID分配，别用来逐条发号。即在启动时通过INCR取号，每个实例拿到自己的节点ID后，后续生成完全走本地Lua模块。这样既解决了节点唯一性问题，又不损失本地生成的性能。
5.3 日志排查建议：ID里都藏着哪几块信息
最后分享一个生产中的实用技巧。业务日志里遇到的雪花算法ID，别只顾着看整体字符串，把它拆开看：
- 高41位对应毫秒时间戳，可以直接换算成可读时间，用来判断请求发生在哪个时间窗口。
- 中间10位是节点ID，如果同一请求的ID被解析出两个不同节点ID，说明负载均衡转发到了不同实例。
- 低12位序列号在同一毫秒内会连续递增，如果发现大量ID的序列号都紧挨着，说明这一毫秒发生了明显突发流量。
我在日志链路里加了一个辅助函数，负责把ID解析后的时间、节点、序列号直接拼到结构化日志字段里。出问题时，一眼就能看出是不是某一台机器时钟漂移、是不是某一段时间的流量冲高、是不是某个节点ID分配冲突。这种“自解释ID”的价值，在使用UUID的时候是完全体会不到的。
这个生成器在我这边的几个服务里稳定跑了两三个月，最深刻的体会是：很多问题不是因为算法复杂，而是因为环境细节没处理好。比如浮点时间没取整、worker_id忘记区分、NTP回拨没兜底。把这些边界都磨平之后，纯Lua的雪花算法在OpenResty环境下完全能扛住业务压力，而且代码量小、无额外依赖，比想象中省心得多。
