简介这是一套面向 TypeScript 与 JavaScript 开发者的轻量级 UUID v4 生成模块源码源自 npm 包 freeasin/uuid同时支持浏览器与 Node.js 环境并原生提供 ES6 模块入口。压缩包内共 13 个文件以 JSON 配置、TypeScript 源码、JavaScript 构建产物为主另含许可证、npm 配置、Git 忽略规则等工程化配套配置类文件负责构建链路与包信息源码和产物则覆盖实际生成逻辑与多格式引用整包仅 17KB结构清晰易读。已有 2264 人学习/下载适合前端或全栈工程师作为小型开源工具库的参考范例。除核心生成逻辑外还附带类型声明文件、CommonJS 与 ES6 两套构建结果以及 tsconfig 构建链路读者既能直接调用方法生成 v4 通用唯一标识符也能学习如何将 TypeScript 源码打包为多种模块格式对封装轻量 npm 包有直接借鉴意义。该模块无运行时依赖代码量小且注释与格式规范既适合初学者阅读也适合正式项目作为公共工具库复用。1. 第一次在分布式日志里看到两条一模一样的 UUID我才意识到UUID 的核心难题从来不是“生成”而是“不撞车”UUID通用唯一标识符几乎是每个开发者迟早要遇上的基础工具一张表的主键、一次文件上传的命名、一条消息的 traceId都可能落到它头上。标题里的“简单”确实成立——三行代码就能生成一个 128 位的随机串但真正接手项目时你会发现选哪个版本、怎么存、怎么建索引、怎么防止并发下的重复才是决定这套 ID 方案能不能扛住线上压力的关键。这篇文章我会从 UUID 的版本选型讲到三种常见语言的落地写法再带到数据库使用和那些让你排查半夜的坑。适合所有正在做表结构设计、接口联调或分布式任务开发的同学。2. 先搞清楚 UUID 的四个主流版本再谈生成v4 和 v7 才是你日常的主力2.1 UUID 是什么一段 128 位的字符串拆开看每一段都有讲究UUID 的格式是一串 32 个十六进制字符按 8-4-4-4-12 的规则用连字符分成五段比如550e8400-e29b-41d4-a716-446655440000。这中间不是随意排列的第 3 段开头那个数字代表版本号第 4 段开头代表变体。你看到41d4里的4就知道这是一个 v4 版本的 UUID——纯随机生成。看到a716里的a说明它遵循 RFC 4122 标准变体。理解这个结构是有用的因为你在排查字符串异常、做版本识别时一眼就能判断线上用的是哪种生成策略。2.2 v4、v7、v1 怎么选随机性、可排序性和时钟依赖的取舍选版本是第一个决策点。三个版本各有各的脾气v4纯随机。生成最快实现最简单但完全无序。在海量插入场景下B 树索引会因为随机主键产生大量页分裂写入性能会随数据量增长明显下滑。v7时间戳 随机量。前 48 位是毫秒级时间戳后面跟上随机数。有序性比 v4 好得多索引友好同时不需要像 v1 那样依赖 MAC 地址隐私上也更安全。这是我最推荐的新项目方案。v1时间戳 MAC 地址。能保证全局唯一但会泄露机器信息现在新项目已经很少用它。选型逻辑很直接如果你做的是客户端离线生成、数据不需要按时间聚合v4 足够只要主键要进数据库且写入频繁直接上 v7如果系统里还跑着老代码依赖 v1 的排序特性那保持兼容就好别去折腾迁移。2.3 标识位的校验拿到一串 UUID 怎么判断它是哪个版本你可能会在排查数据时遇到这种疑问这条 UUID 到底怎么生成的看第 3 段的第一个字符就行。1开头是 v14开头是 v47开头是 v7。写一段简单的 Python 校验逻辑就可以批量判断import re def detect_uuid_version(uuid_str: str) - int: 通过第3段的第一个字符判断UUID版本 pattern re.compile(r^[0-9a-f]{8}-[0-9a-f]{4}-([0-9a-f]{4})-[0-9a-f]{4}-[0-9a-f]{12}$) match pattern.match(uuid_str.lower()) if not match: return 0 # 非合法UUID格式 version_hex match.group(1)[0] return int(version_hex, 16) # 用法 print(detect_uuid_version(550e8400-e29b-41d4-a716-446655440000)) # 输出 4这段代码的核心是把第 3 段的第一个十六进制字符提取出来再转成整数。注意这里必须先做完整格式校验否则g这类非法字符会让int()抛异常。线上日志清理脚本或数据对账任务里挂一个这样的函数能快速识别出异常数据来源——比如上游系统是不是拿随机数拼了个假 UUID 传过来。3. 动手生成从 Python、JavaScript 到 SQL三种场景的最小实现3.1 Python 生成 UUIDuuid 库是标准答案但有个细节要注意Python 标准库自带uuid模块v4 和 v7 都能直接生成v7 需要 3.12 版本import uuid # v4纯随机 uid4 uuid.uuid4() print(fv4: {uid4}) # v7时间戳有序 uid7 uuid.uuid7() # Python 3.12 及以上 print(fv7: {uid7}) # 从字符串解析UUID用于反序列化 parsed uuid.UUID(550e8400-e29b-41d4-a716-446655440000) print(parsed.version) # 4逻辑很简单uuid4()使用操作系统提供的随机源/dev/urandom或 Windows 的 CryptGenRandom而不是 Python 的random模块这一点很关键——它的随机性够强多进程并发调用也不怕重复。uuid7()的时间戳部分来自系统时钟配合随机部分保证同一毫秒内多量生成不冲突。参数上没什么可调的唯一要提醒的是如果你的生产环境 Python 版本低于 3.12又想要 v7 的有序性建议引入三方库来实现而不是自己拼时间戳——手搓的话很容易在边界条件下翻车比如闰秒或时钟回拨时生成重复 ID。3.2 JavaScript 端生成 UUIDcrypto.randomUUID 是原生首选但注意浏览器兼容前端生成 UUID 最常用的场景是临时 ID 或离线数据的主键。现代浏览器和 Node.js 都内置了crypto.randomUUID()无需引包// 浏览器环境 const uid crypto.randomUUID(); console.log(uid); // 例如: 3f4c9b2e-7f2a-4f5a-9b1c-8e6d5c4b3a21 // Node.js 环境 const { randomUUID } require(crypto); const uid2 randomUUID(); console.log(uid2);这里有个前提crypto.randomUUID要求 secure contextHTTPS 或 localhost如果你在 HTTP 明文环境下调试它会直接抛TypeError。生产环境一般没问题但内网测试环境经常踩这个坑。解决方式是降级方案用crypto.getRandomValues手动填充 16 个字节来拼function fallbackUUID() { const bytes crypto.getRandomValues(new Uint8Array(16)); bytes[6] (bytes[6] 0x0f) | 0x40; // 版本设为 4 bytes[8] (bytes[8] 0x3f) | 0x80; // 变体设为 RFC 4122 const hex [...bytes].map(b b.toString(16).padStart(2, 0)).join(); return ${hex.slice(0,8)}-${hex.slice(8,12)}-${hex.slice(12,16)}-${hex.slice(16,20)}-${hex.slice(20)}; }这两行位运算就是整个 UUID v4 生成的核心逻辑第 7 个字节的高四位设为0100表示 v4第 9 个字节的最高两位设为10表示标准变体。如果你在维护一个需要兼容 IE 的老系统这个函数就是你的后悔药。3.3 直接用 SQL 生成 UUID数据库内置函数与注意点写 SQL 时你不需要在应用层生成再传给数据库主流的几个数据库都有内置函数-- PostgreSQL SELECT gen_random_uuid(); -- 返回 v4 格式 -- MySQL 8.0 SELECT UUID(); -- 返回 v1 格式 SELECT UUID_TO_BIN(UUID(), 1); -- 转为二进制存储并交换时间戳位 -- SQLite需要扩展 SELECT lower(hex(randomblob(4)) || - || hex(randomblob(2)) || -4 || substr(hex(randomblob(2)),2) || - || substr(hex(randomblob(2)),2) || - || hex(randomblob(6)));PostgreSQL 的gen_random_uuid()是 v4开箱即用。MySQL 的UUID()返回的是 v1 格式带 MAC 地址和时钟序列直接做字符串主键没问题但如果你在意隐私建议改成应用层生成 v4 再入库。SQLite 那段拼接属于“自制 v4”我的建议是除非项目规定零依赖否则别这么干——randomblob生成的随机字节分布没问题但拼错一个substr参数就可能产出格式非法的字符串这种硬编码很容易变成黑匣子。4. 把 UUID 落进数据库存储类型、索引策略与分库分表的三层考量4.1 存字符串还是存二进制BINARY(16) 比 CHAR(36) 省一半空间很多新手会把 UUID 直接存成CHAR(36)这是最直觉的做法但要知道代价36 字符的 UTF-8 在 InnoDB 里占 108 字节utf8mb4 下每个字符最多 3 字节而 UUID 本质上就是 16 字节的二进制数据。用BINARY(16)存储后配合UUID_TO_BIN()/BIN_TO_UUID()做转换索引体积直接缩小三倍以上缓存命中率更高写入性能也更好。我的一般做法是在应用层保持字符串格式只在持久化层做转换-- 建表时用二进制列 CREATE TABLE orders ( id BINARY(16) PRIMARY KEY, created_at DATETIME NOT NULL, -- 其他字段... ); -- 插入时转换 INSERT INTO orders (id, created_at) VALUES (UUID_TO_BIN(?), NOW()); -- 查询时转回字符串 SELECT BIN_TO_UUID(id) AS id, created_at FROM orders WHERE id UUID_TO_BIN(?);这里有个很重要的细节MySQL 的UUID_TO_BIN(uuid, 1)第二个参数传1表示把时间戳部分交换到最前面让 UUID 在 B 树里按时间大致有序地插入减少页分裂。如果你用的是 v4 纯随机 UUID这个交换参数没有意义但 v7 或 v1 格式配合这个参数高并发写入下的性能提升会非常明显。4.2 UUID 做主键 vs 自增主键别再一刀切说 UUID 慢从 MySQL 8.0 和 PostgreSQL 15 之后“UUID 做主键慢”这个说法越来越站不住脚。自增 ID 的优势是顺序写入、索引紧凑但劣势是暴露业务量、分库分表后需要全局发号器才能保证不冲突。UUID 主键则天然适合分布式场景各节点独立生成、无需协调合并数据时不会撞车。用 UUID 做主键要接受的代价有两方面一是 16 字节比 4 字节或 8 字节的整数更大索引占用空间高二是如果你选了无序的 v4写入会出现大量随机 I/O。但这两个问题都有解——v7 或调整存储格式后顺序问题基本消失空间问题在 SSD 普及和内存容量翻倍的今天影响远小于团队为了维护发号器付出的沟通成本。4.3 分库分表下的 UUID业务标识里该不该带分表位当你做订单号或用户 ID 这类业务标识时直接暴露一个纯 UUID 给前端并不友好太长、无序、不好念。更常见的方案是“UUID 打底 业务前缀 分表位”的组合。比如OD 两位分表号 UUID 后 8 位 时间戳。这种设计的好处是分表位让网关能直接路由到正确的物理表时间戳段让排查问题时能直觉判断产生时间完整的 UUID 尾段保证全局唯一。但注意这里说的是“业务标识”不是数据库主键。我的建议是数据库主键和业务标识分离。主键用 UUID 保证唯一性业务标识用组合字段满足可读性和路由需求。两者混用会陷入一个尴尬境地——为了短而截断 UUID最后碰撞排查变成玄学。5. UUID 使用中绕不开的坑五个高频翻车现场与排查思路5.1 无序 UUID 引发的插入性能雪崩页分裂与缓存命中率现象一张订单表数据量到千万级后写入耗时从 5ms 涨到 50ms磁盘 IO 飙升。原因主键是 v4 随机 UUID每次插入都要触发 B 树节点分裂且新数据大概率不在缓存页中导致大量随机读。解决优先把主键改成 v7有序或使用UUID_TO_BIN(uuid, 1)调整字节序。如果无法改表可以增加一个自增的sort_id列做聚簇索引UUID 列降级为普通唯一索引。这种改动不需要业务层配合DBA 就能操作。5.2 大小写和连字符不一致导致的数据对不上现象两套系统联调A 系统存的是小写带连字符B 系统存的是大写不带连字符关联查询时匹配不上。原因UUID 的字符串表示有两种风格RFC 4122 标准要求小写带连字符但不少老系统习惯大写且自行去掉了连字符。解决在应用层统一规范化调用uuid.UUID(uid).hexPython或uuid.toLowerCase()JS后再存储。更稳妥的做法是入库时全部转成BINARY(16)从根上消除字符大小写和连字符差异。5.3 Python 3.12 以下没有 uuid7别拿随机字符串硬拼现象在 Python 3.10 环境调uuid.uuid7()直接报AttributeError。原因v7 是 Python 3.12 才进标准库的老版本没有。解决要么升级运行时要么用三方库uuid6来兼容。这里尤其提醒不要手动把时间戳和随机数拼成“假 v7”——你拼出来的字符串第 3 段开头大概率不是7格式校验工具会认为是版本损坏而且你自己的拼接逻辑在并发场景下容易出现同一毫秒生成相同随机部分的极端情况。5.4 把 UUID 当文件名导致路径过长或 URL 不友好现象文件上传服务用 UUID 命名图片嵌套多级目录后路径超 255 字节部分系统写不进去。原因UUID 字符串是 36 字符多个目录层级叠加后很容易突破文件系统的路径长度限制。解决文件存储命名使用去连字符的 32 位十六进制.hex格式或者只取前 16 位做文件名完整的 UUID 存数据库字段。前 16 位理论上 64 位随机量碰撞概率在单业务规模内可忽略如果你实在不放心加一层日期目录/2025/04/进一步隔离。5.5 前端生成 UUID 时明文 HTTP 环境下 crypto.randomUUID 不可用现象内网测试站点的页面控制台报TypeError: crypto.randomUUID is not a function。原因randomUUID只在安全上下文可见http://192.168.x.x这类地址会被浏览器判定为不安全。解决按前面 3.2 的 fallback 函数用getRandomValues替代或者统一改为后端下发 ID。这个问题只在开发环境出现但线上如果用了 CDN 回源到 HTTP也会偶发——排查时第一个先看页面是不是 HTTPS。6. 进阶从 UUID 到有序 ID 的平滑迁移以及用脚本验证全局唯一性很多人用上 UUID 之后就不再管了但 ID 方案是需要持续验证的尤其是高并发写入的场景。我习惯在压测环境跑一轮“批量生成 唯一性校验”脚本用几百个并发协程同时生成 UUID 再全量比对确保生成器在高竞争下没有重复import uuid from concurrent.futures import ThreadPoolExecutor def generate_batch(_): return [uuid.uuid7() for _ in range(1000)] pool ThreadPoolExecutor(max_workers32) futures [pool.submit(generate_batch, i) for i in range(32)] all_ids [] for f in futures: all_ids.extend(f.result()) unique_count len(set(all_ids)) print(f生成总数: {len(all_ids)}, 唯一数: {unique_count}) if unique_count ! len(all_ids): print(存在重复) else: print(唯一性验证通过)这个脚本的价值在于把你的 UUID 生成器推到“多线程 × 多次”的边界上去set 去重能直接暴露碰撞。如果你换了三方库或自己写过生成函数跑一遍它心里就有底了。验证通过之后再考虑是否要让系统的有序性更强。v7 在单机内已经能保证毫秒级有序但跨进程跨机器时不同节点的时间戳存在时钟偏差排序只能保证大致趋势而不是全局严格递增。如果你们有强顺序需求比如金融流水要严格按时间排列那就要在应用层加一个序号位或换用专门的序列方案而不是靠 UUID 本身。我通常会在系统里保留一个created_at字段做最终排序兜底UUID 只负责唯一性两者各司其职这样无论生成器怎么演进数据的时序语义都不会丢。这套组合拳我用了好几个项目唯一性的兜底验证和排序职责分离帮我避开过不少“ID 看起来没问题但一到数据对账就露馅”的尴尬。希望这篇关于 UUID 的落地笔记能帮到你——生成很简单但用好需要想清楚版本、存储和边界。本文还有配套的精品资源点击获取