uuid: LuaJIT FFI 绑定的 libuuid，一个与 DCE 兼容的通用唯一标识符库

安装

如果您尚未设置 RPM 仓库订阅，请注册。然后您可以继续以下步骤。

CentOS/RHEL 7 或 Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-uuid

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-uuid

要在 NGINX 中使用此 Lua 库，请确保已安装 nginx-module-lua。

本文档描述了 lua-resty-uuid v1.2.0，于 2026 年 5 月 07 日发布。

LuaJIT FFI 绑定的 libuuid — 一个与 DCE 兼容的通用唯一标识符 (UUID/GUID) 库。生成 v1（时间）、v4（随机）、v6（重新排序的时间）和 v7（Unix 纪元）UUID，并解析和检查现有的 UUID 字符串。

快速开始

local uuid = require "resty.uuid"

uuid.generate()         --> "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
uuid.generate_random()  --> "550e8400-e29b-41d4-a716-446655440000"  (v4)
uuid.generate_time()    --> "..."                                   (v1)
uuid.generate_time_v6() --> "..."                                   (v6)
uuid.generate_time_v7() --> "..."                                   (v7)

uuid()                  --> uuid.generate() 的快捷方式

uuid.is_valid("not-a-uuid")  --> false
uuid.type(some_v4_id)        --> 4
uuid.variant(some_id)        --> 1   (DCE)
uuid.time(some_v1_id)        --> 1714867200, 123456

API

该模块是一个表，同时也是可调用的。调用 uuid() 是 uuid.generate() 的快捷方式。

生成器

函数	返回值	描述
`uuid.generate()`	`string`	主机上可用的最佳生成器（尽可能随机，否则基于时间）。
`uuid.generate_random()`	`string`	版本 4（随机）UUID。
`uuid.generate_time()`	`string`	版本 1（时间戳 + 节点 ID）UUID。
`uuid.generate_time_safe()`	`string, boolean`	版本 1 UUID 和一个标志，指示生成是否为唯一性同步。
`uuid.generate_time_v6()`	`string`	版本 6 UUID — v1 字段重新排序以便于词法排序。
`uuid.generate_time_v7()`	`string`	版本 7 UUID — 毫秒 Unix 时间戳 + 随机尾部。

所有生成器返回标准的 36 字符 8-4-4-4-12 小写十六进制形式，例如 "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"。

检查

函数	返回值	描述
`uuid.is_valid(id)`	`boolean`	`id` 是否能解析为 UUID。
`uuid.type(id)`	`int` 或 `nil`	UUID 版本（`UUID_TYPE_*` 常量），如果无效则为 `nil`。
`uuid.variant(id)`	`int` 或 `nil`	UUID 变体（`UUID_VARIANT_*` 常量），如果无效则为 `nil`。
`uuid.time(id)`	`number, number` 或 `nil`	自 Unix 纪元以来的秒数和该秒内的微秒数；如果 `id` 不是有效的 UUID，则为 `nil`。仅对 v1、v6 和 v7 有意义。

常量参考

uuid.type 返回以下之一：

值	常量	含义
`1`	`UUID_TYPE_DCE_TIME`	基于时间（v1）
`2`	`UUID_TYPE_DCE_SECURITY`	DCE 安全（v2）
`3`	`UUID_TYPE_DCE_MD5`	基于名称的 MD5（v3）
`4`	`UUID_TYPE_DCE_RANDOM`	随机（v4）
`5`	`UUID_TYPE_DCE_SHA1`	基于名称的 SHA-1（v5）
`6`	`UUID_TYPE_DCE_TIME_V6`	重新排序的时间（v6）
`7`	`UUID_TYPE_DCE_TIME_V7`	Unix 纪元时间（v7）

uuid.variant 返回以下之一：

值	常量	含义
`0`	`UUID_VARIANT_NCS`	NCS / Apollo 传统
`1`	`UUID_VARIANT_DCE`	DCE 1.1 / RFC 4122
`2`	`UUID_VARIANT_MICROSOFT`	Microsoft GUID
`3`	`UUID_VARIANT_OTHER`	保留

测试

make test          # 完整流程：安装 rock，运行 busted，覆盖率，代码检查
make unit          # 仅 busted
make coverage      # busted + luacov 报告
make lint          # luacheck

测试位于 spec/ 中，并测试每个公共函数以及 __call 元方法。

文档

API 参考使用 LDoc 构建，并位于 docs/ 下：

make docs

GitHub

您可以在 nginx-module-uuid 的 GitHub 仓库中找到有关此模块的其他配置提示和文档。