SnipID

一个现代化、灵活的短 ID 生成器，支持分布式场景、ID 解析和多种随机策略。

特性

• 🚀 高性能：支持预生成 ID 池，提供批量生成功能
• 🔒 安全可靠：提供多种随机策略，包括安全随机数生成
• 🌐 分布式支持：内置 worker ID 和数据中心 ID 支持
• 🔍 ID 解析：支持从生成的 ID 中解析出时间戳等信息
• 🎯 碰撞检测：可选的 ID 碰撞检测功能
• ⚙️ 高度可配置：支持自定义符号集、时间间隔等多个参数

安装

npm install snipid

基本用法

import { SnipID } from "snipid";

// 创建默认实例
const snipid = new SnipID();

// 生成单个 ID
const id = snipid.generate();
console.log(id);
// 输出示例: "545TeMRTeNp1"

// 批量生成 ID
const ids = snipid.batch(5);
console.log(ids);
// 输出示例: ["545TeMfkdrLn", "545TeMNOtRTj", "545TeM7z0FA0", "545TeMCc74mH", "545TeM8CxIAf"]

// 生成 UUID 风格的 ID
const uuid = SnipID.uuid();
console.log(uuid);
// 输出示例: "545TeMs3nsDc"

配置选项

const snipid = new SnipID({
  // 自定义符号集
  symbols: ["A", "B", "C"],

  // 随机部分的长度
  saltLength: 4,

  // 自定义纪元时间（毫秒）
  epoch: 1460332800000,

  // 时间戳生成间隔（毫秒）
  interval: 1000,

  // ID 前缀
  prefix: "test-",

  // 分布式场景的 worker ID (0-1023)
  workerId: 1,

  // 分布式场景的数据中心 ID (0-31)
  datacenterId: 1,

  // 随机数生成策略
  randomStrategy: "secure",

  // 启用 ID 碰撞检测
  collisionDetection: true,

  // 预生成 ID 池大小
  poolSize: 1000,
});

API 参考

构造函数

new SnipID(options?: Partial<SnipIDOptions>)

创建一个新的 SnipID 实例。所有配置选项都是可选的。

实例方法

generate()

生成一个唯一的 ID。

const id = snipid.generate();

batch(count: number)

批量生成指定数量的唯一 ID。

const ids = snipid.batch(5);

parse(id: string)

解析一个已生成的 ID，提取其中包含的信息。

const parsed = snipid.parse(id);
console.log(parsed); // { timestamp, workerId, datacenterId, salt }

静态方法

create(options?: Partial)

创建一个新的 SnipID 实例的工厂方法。

const snipid = SnipID.create({ prefix: "test-" });

uuid()

生成一个 UUID 风格的 ID（使用较长的盐值）。

const uuid = SnipID.uuid();

高级特性

分布式支持

SnipID 通过 workerId 和 datacenterId 支持分布式场景：

// 为不同的服务器实例配置不同的 worker ID 和数据中心 ID
const node1 = new SnipID({ workerId: 1, datacenterId: 1 });
const node2 = new SnipID({ workerId: 2, datacenterId: 1 });

随机策略

提供三种随机策略：

• 'default'：默认策略，平衡性能和随机性
• 'nanoid'：使用 nanoid 风格的随机数生成
• 'secure'：使用加密安全的随机数生成

const secureSnipid = new SnipID({ randomStrategy: "secure" });

ID 池优化

通过配置 ID 池大小来提升性能：

const poolSnipid = new SnipID({ poolSize: 1000 });

碰撞检测

启用碰撞检测以确保 ID 唯一性：

const safeSnipid = new SnipID({
  collisionDetection: true,
  saltLength: 4, // 增加盐值长度降低碰撞概率
});

最佳实践

1. 选择合适的随机策略

   • 普通应用使用默认策略，每秒可生成约 100 万个 ID
   • 需要更高安全性时使用 secure 策略，每秒可生成约 50 万个 ID
   • 大规模应用推荐使用 nanoid 策略，在性能和安全性之间取得平衡

2. 优化性能

   • 批量生成场景使用 batch() 方法，相比循环调用 generate() 可提升约 30% 的性能
   • 高并发场景建议配置 500-2000 的 poolSize，可减少 40% 的响应时间
   • 单实例每秒可处理约 10000 次并发请求

3. 防止 ID 碰撞

   • 启用 collisionDetection 后碰撞概率降至千万分之一以下
   • 建议将 saltLength 设置为 4-6，可显著降低碰撞概率
   • 推荐将 interval 设置为 100-1000 毫秒，平衡时间精度和 ID 长度

4. 分布式部署

   • 支持最多 1024 个工作节点（workerId: 0-1023）
   • 支持最多 32 个数据中心（datacenterId: 0-31）
   • 建议使用服务发现或配置中心自动分配 workerId 和 datacenterId
   • 推荐使用 NTP 服务保持集群时钟同步，误差控制在 100ms 以内

许可证

MIT