`hutool.core.util.id`¶

Module Contents¶

Classes¶

`_SnowflakeWorkerPool`	模块级雪花算法工作池，跨调用维持状态
`IdUtil`	ID生成工具类，对应 Java cn.hutool.core.util.IdUtil
`_SnowflakeIdWorker`	雪花算法ID生成器内部实现
`MachineIdGenerator`	机器唯一 ID 生成器（32/64 位）。

Data¶

_machine_id_gen

API¶

class hutool.core.util.id._SnowflakeWorkerPool¶

模块级雪花算法工作池，跨调用维持状态

_workers: dict = None¶

_lock = 'Lock(...)'¶

classmethod get(worker_id: int, datacenter_id: int) → hutool.core.util.id._SnowflakeIdWorker¶

获取或创建指定 worker_id + datacenter_id 的雪花算法工作器（线程安全）。

参数:

worker_id – 工作机器ID
datacenter_id – 数据中心ID

返回:

对应的雪花算法ID生成器实例

class hutool.core.util.id.IdUtil¶

ID生成工具类，对应 Java cn.hutool.core.util.IdUtil

_snowflake_worker = None¶

static random_uuid() → str¶

生成随机UUID（带横线格式）。

返回:: UUID字符串，如 "550e8400-e29b-41d4-a716-446655440000"

static simple_uuid() → str¶

生成简单UUID（不带横线格式）。

返回:: 32位十六进制UUID字符串，如 "550e8400e29b41d4a716446655440000"

static fast_uuid() → str¶

快速生成UUID（带横线格式）。

返回:: UUID字符串

static fast_simple_uuid() → str¶

快速生成简单UUID（不带横线格式）。

返回:: 32位十六进制UUID字符串

static nano_id(size: int = 21) → str¶

生成NanoID（URL安全的短ID）

使用 secrets 模块实现，类似 nanoid 算法。

参数:: size – 生成的ID长度，默认为21
返回:: NanoID字符串

static snowflake_id(worker_id: int = 1, datacenter_id: int = 1) → int¶

生成雪花算法ID

参数:

worker_id – 工作机器ID
datacenter_id – 数据中心ID

返回:

雪花算法生成的ID

static unique_machine_id() → int¶

生成机器唯一 ID（64 位整数）。

基于当前时间戳（毫秒）、进程 ID 和原子计数器组合生成，在同一进程内保证唯一性。

返回:: 64 位整数 ID

static guid128(salt: Optional[str] = None) → str¶

生成 26 字符的全局唯一 ID。

使用 Base32 编码（Crockford 方案：0-9A-HJKMNP-TV-Z），由时间戳 + 随机字节 + 可选盐值哈希组成，保证全局唯一。

参数:: salt – 可选盐值字符串，相同盐值会增加差异性
返回:: 26 字符的全局唯一 ID 字符串

static object_id() → str¶

生成MongoDB ObjectId格式的24位十六进制字符串。

由 4字节时间戳 + 5字节随机值 + 3字节递增计数器组成。

返回:: 24位十六进制字符串

static create_snowflake(worker_id: int = 1, datacenter_id: int = 1)¶

创建雪花算法 ID 生成器。

参数:

worker_id – 工作机器 ID（0-31）
datacenter_id – 数据中心 ID（0-31）

返回:

_SnowflakeIdWorker 实例

static get_snowflake(worker_id: int = 1, datacenter_id: int = 1)¶

获取全局雪花算法 ID 生成器（单例）。

参数:

worker_id – 工作机器 ID（0-31）
datacenter_id – 数据中心 ID（0-31）

返回:

_SnowflakeIdWorker 实例

static get_snowflake_next_id(worker_id: int = 1, datacenter_id: int = 1) → int¶

获取下一个雪花 ID（int）。

参数:

worker_id – 工作机器 ID
datacenter_id – 数据中心 ID

返回:

64 位整数 ID

static get_snowflake_next_id_str(worker_id: int = 1, datacenter_id: int = 1) → str¶

获取下一个雪花 ID（字符串）。

参数:

worker_id – 工作机器 ID
datacenter_id – 数据中心 ID

返回:

字符串 ID

static unique_machine32() → int¶

生成 32 位机器唯一 ID。

基于 PID + 时间戳 + 计数器组合，在同一进程内唯一。

返回:: 32 位整数 ID

static unique_machine64() → int¶

生成 64 位机器唯一 ID。

基于 PID + 主机名哈希 + 时间戳 + 计数器组合，跨机器唯一。

返回:: 64 位整数 ID

static luid(separator: str = '-') → str¶

基于主机名的全局唯一 ID。

格式: HHHHHHHH-PIDPPPP-TTTTTTTT-CCCC

参数:: separator – 分隔符，默认 "-"
返回:: 全局唯一 ID 字符串

static is_snowflake_id(snowflake_id: int, worker_id: Optional[int] = None, datacenter_id: Optional[int] = None, check_timestamp: bool = True) → bool¶

判断一个数字是否为有效的雪花算法 ID，并可选验证 worker_id 和 datacenter_id 是否匹配。

验证逻辑：

必须是正整数且不超过 63 位
解析出的时间戳必须在合理范围内（EPOCH ~ 当前时间 + 1 天）
若指定 worker_id，则要求 ID 中的 worker_id 与之相等
若指定 datacenter_id，则要求 ID 中的 datacenter_id 与之相等

参数:

snowflake_id – 待判断的数字
worker_id – 期望的工作机器 ID（0-31），为 None 时不校验
datacenter_id – 期望的数据中心 ID（0-31），为 None 时不校验
check_timestamp – 是否校验时间戳合理性，默认 True

返回:

是否为有效的雪花 ID 且 worker/datacenter 匹配

class hutool.core.util.id._SnowflakeIdWorker(worker_id: int, datacenter_id: int)¶

雪花算法ID生成器内部实现

Initialization

初始化雪花算法ID生成器

参数:

worker_id – 工作机器ID，范围 [0, 31]
datacenter_id – 数据中心ID，范围 [0, 31]

EPOCH = 1577808000000¶

WORKER_ID_BITS = 5¶

DATACENTER_ID_BITS = 5¶

SEQUENCE_BITS = 12¶

MAX_WORKER_ID = None¶

MAX_DATACENTER_ID = None¶

SEQUENCE_MASK = None¶

WORKER_ID_SHIFT = None¶

DATACENTER_ID_SHIFT = None¶

TIMESTAMP_LEFT_SHIFT = None¶

next_id() → int¶

生成下一个雪花算法ID（线程安全）。

返回:: 唯一的64位整数ID
抛出:: RuntimeError – 发生时钟回拨时

_current_millis() → int¶: 获取当前时间戳（毫秒）

_wait_next_millis() → int¶: 自旋等待直到下一毫秒

class hutool.core.util.id.MachineIdGenerator¶

机器唯一 ID 生成器（32/64 位）。

基于 PID、主机名哈希、时间戳和计数器组合生成唯一 ID。

Initialization

generate32() → int¶

生成 32 位机器唯一 ID。

布局: 时间戳（毫秒，12位）+ PID（8位）+ 计数器（12位）

返回:: 32 位整数

generate64() → int¶

生成 64 位机器唯一 ID。

返回:: 64 位整数

hutool.core.util.id._machine_id_gen = 'MachineIdGenerator(...)'¶

hutool.core.util.id¶

Module Contents¶

Classes¶

Data¶

API¶

`hutool.core.util.id`¶