Class SafeJsSnowflakeGenerator

java.lang.Object
cloud.opencode.base.id.snowflake.SafeJsSnowflakeGenerator
All Implemented Interfaces:
IdGenerator<Long>
public final class SafeJsSnowflakeGenerator extends Object implements IdGenerator<Long>
JavaScript-Safe Snowflake ID Generator - IDs guaranteed to fit in JS Number.MAX_SAFE_INTEGER JavaScript安全雪花ID生成器 - ID保证在JS Number.MAX_SAFE_INTEGER范围内

Generates time-ordered 64-bit IDs whose value is always ≤ 2^53−1 (9,007,199,254,740,991), the maximum integer that JavaScript can represent exactly as a Number. This avoids the well-known silent rounding issue when large Snowflake IDs are serialized as JSON numbers and consumed by JavaScript frontends.

生成时间有序的64位ID，其值始终≤ 2^53−1（9,007,199,254,740,991）， 即JavaScript能精确表示为Number的最大整数。 避免大Snowflake ID序列化为JSON数字被JavaScript前端消费时的静默四舍五入问题。

Bit Layout | 位布局 (53 bits total):

[ 41-bit timestamp | 6-bit workerId | 6-bit sequence ]
  ms since epoch     0-63             0-63/ms

Capacity | 容量:

  • Timestamp: ~69 years from epoch (same as standard Snowflake) | 时间戳: 约69年
  • Worker nodes: 64 (0-63) | 工作节点: 64个（0-63）
  • Throughput: 64 IDs/ms per node = ~64,000/s | 吞吐量: 每节点每毫秒64个
  • Max value: 9,007,199,254,740,991 ≤ Number.MAX_SAFE_INTEGER | 最大值在JS安全整数范围内

Trade-offs vs. Standard Snowflake | 与标准雪花ID的取舍:

  • Fewer worker nodes (64 vs 1024) - 工作节点较少（64 vs 1024）
  • Lower throughput (64 vs 4096/ms) - 吞吐量较低（64 vs 4096/ms）
  • No datacenter ID bits - 无数据中心ID位
  • JSON-safe without string serialization workarounds - 无需字符串序列化绕过即可JSON安全

Usage Examples | 使用示例:

// Default (workerId=0)
SafeJsSnowflakeGenerator gen = SafeJsSnowflakeGenerator.create();
long id = gen.generate();
assert SafeJsSnowflakeGenerator.isJsSafe(id); // always true

// With workerId
SafeJsSnowflakeGenerator gen2 = SafeJsSnowflakeGenerator.create(7);
long id2 = gen2.generate(); // always <= 2^53-1

Security | 安全性:

  • Thread-safe: Yes (ReentrantLock) - 线程安全: 是（可重入锁）
  • Clock rollback: throws OpenIdGenerationException - 时钟回拨: 抛出异常
Since:
JDK 25, opencode-base-id V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final long
    JS_MAX_SAFE_INT
    JavaScript Number.MAX_SAFE_INTEGER = 2^53 - 1 | JavaScript最大安全整数

  • Method Summary

    Modifier and Type
    Method
    Description
    static SafeJsSnowflakeGenerator
    create()
    Creates a generator with workerId=0 and the default epoch 使用workerId=0和默认起始时间创建生成器
    static SafeJsSnowflakeGenerator
    create(long workerId)
    Creates a generator with the specified workerId 使用指定workerId创建生成器
    static SafeJsSnowflakeGenerator
    create(long workerId, long epochMillis)
    Creates a generator with specified workerId and epoch 使用指定workerId和起始时间创建生成器
    Long
    generate()
    Generates a JavaScript-safe Snowflake ID 生成JavaScript安全的雪花ID
    String
    generateStr()
    Generates the ID as a decimal string (always safe to pass to JavaScript as-is) 生成ID的十进制字符串（可直接安全传递给JavaScript）
    long
    getEpoch()
    Returns the epoch used by this generator 返回此生成器使用的起始时间
    String
    getType()
    Gets the generator type name 获取生成器类型名称
    long
    getWorkerId()
    Returns the worker node ID configured for this generator 返回此生成器配置的工作节点ID
    static boolean
    isJsSafe(long id)
    Checks whether a long value is within JavaScript's safe integer range 检查long值是否在JavaScript安全整数范围内

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface IdGenerator

    generateBatch

  • Field Details

    • JS_MAX_SAFE_INT

      public static final long JS_MAX_SAFE_INT
      JavaScript Number.MAX_SAFE_INTEGER = 2^53 - 1 | JavaScript最大安全整数
      See Also:

  • Method Details

    • create

      public static SafeJsSnowflakeGenerator create()
      Creates a generator with workerId=0 and the default epoch 使用workerId=0和默认起始时间创建生成器
      Returns:
      generator | 生成器

    • create

      public static SafeJsSnowflakeGenerator create(long workerId)
      Creates a generator with the specified workerId 使用指定workerId创建生成器

      Examples | 示例:

      SafeJsSnowflakeGenerator.create(0)   // node 0 (default)
SafeJsSnowflakeGenerator.create(63)  // node 63 (max)
      Parameters:
      workerId - the worker node ID (0-63) | 工作节点ID（0-63）
      Returns:
      generator | 生成器
      Throws:
      OpenIdGenerationException - if workerId is out of range | workerId越界时抛出

    • create

      public static SafeJsSnowflakeGenerator create(long workerId, long epochMillis)
      Creates a generator with specified workerId and epoch 使用指定workerId和起始时间创建生成器
      Parameters:
      workerId - the worker node ID (0-63) | 工作节点ID（0-63）
      epochMillis - the epoch in milliseconds | 起始时间（毫秒）
      Returns:
      generator | 生成器
      Throws:
      OpenIdGenerationException - if workerId is out of range | workerId越界时抛出

    • generate

      public Long generate()
      Generates a JavaScript-safe Snowflake ID 生成JavaScript安全的雪花ID

      Performance | 性能:

      Time: O(1) amortized, Space: O(1)

      时间: O(1) 均摊, 空间: O(1)

      Specified by:
      generate in interface IdGenerator<Long>
      Returns:
      ID ≤ 2^53-1 | ID值 ≤ 2^53-1
      Throws:
      OpenIdGenerationException - on clock backward | 时钟回拨时抛出

    • generateStr

      public String generateStr()
      Generates the ID as a decimal string (always safe to pass to JavaScript as-is) 生成ID的十进制字符串（可直接安全传递给JavaScript）
      Returns:
      decimal ID string | 十进制ID字符串

    • getWorkerId

      public long getWorkerId()
      Returns the worker node ID configured for this generator 返回此生成器配置的工作节点ID
      Returns:
      worker ID | 工作节点ID

    • getEpoch

      public long getEpoch()
      Returns the epoch used by this generator 返回此生成器使用的起始时间
      Returns:
      epoch in milliseconds | 起始时间（毫秒）

    • isJsSafe

      public static boolean isJsSafe(long id)
      Checks whether a long value is within JavaScript's safe integer range 检查long值是否在JavaScript安全整数范围内

      Examples | 示例:

      isJsSafe(9007199254740991L) = true   // JS_MAX_SAFE_INT
isJsSafe(9007199254740992L) = false  // JS_MAX_SAFE_INT + 1
isJsSafe(-1L)               = false  // negative
      Parameters:
      id - the ID to check | 要检查的ID
      Returns:
      true if safe for JavaScript | 对JavaScript安全则返回true

    • getType

      public String getType()
      Description copied from interface: IdGenerator
      Gets the generator type name 获取生成器类型名称
      Specified by:
      getType in interface IdGenerator<Long>
      Returns:
      type name | 类型名称