Class TsidGenerator

java.lang.Object
cloud.opencode.base.id.tsid.TsidGenerator
All Implemented Interfaces:
IdGenerator<Long>
public final class TsidGenerator extends Object implements IdGenerator<Long>
TSID (Time-Sorted ID) Generator TSID（时间排序ID）生成器

Generates 64-bit time-sorted unique identifiers. TSID is simpler than Snowflake and recommended by Vlad Mihalcea for database primary keys.

生成64位时间排序的唯一标识符。TSID比Snowflake更简单， 被Vlad Mihalcea推荐用于数据库主键。

TSID Structure | TSID结构 (64-bit):

|------------------------------------------|-----------------|
|          42 bits timestamp               | 22 bits random  |
|------------------------------------------|-----------------|

Features | 主要功能:

  • Time-sorted - 时间排序
  • 64-bit compact size - 64位紧凑大小
  • No node configuration required - 无需节点配置
  • Database index friendly - 数据库索引友好
  • Crockford's Base32 encoding - Crockford Base32编码

Capacity | 容量:

  • ~139 years from epoch - 从起始时间算起约139年
  • ~4 million IDs per millisecond - 每毫秒约400万个ID

Usage Examples | 使用示例:

TsidGenerator gen = TsidGenerator.create();
long tsid = gen.generate();

// As string (13 characters, Crockford's Base32)
String tsidStr = gen.generateStr();
// -> "0ARYZ1J8P0X0R"

// With node configuration
TsidGenerator nodeGen = TsidGenerator.create(10, 1);

Security | 安全性:

  • Thread-safe: Yes - 线程安全: 是
Since:
JDK 25, opencode-base-id V1.1.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final long
    DEFAULT_EPOCH
    Default epoch: 2020-01-01 00:00:00 UTC 默认起始时间：2020-01-01 00:00:00 UTC

  • Method Summary

    Modifier and Type
    Method
    Description
    static TsidGenerator
    create()
    Creates a TSID generator with default settings 使用默认设置创建TSID生成器
    static TsidGenerator
    create(int nodeBits, long nodeId)
    Creates a TSID generator with node configuration 使用节点配置创建TSID生成器
    static TsidGenerator
    create(long epoch, int nodeBits, long nodeId)
    Creates a TSID generator with full configuration 使用完整配置创建TSID生成器
    static long
    decode(String tsidStr)
    Decodes a TSID string to long value 将TSID字符串解码为长整型值
    static String
    encode(long tsid)
    Encodes a TSID to Crockford's Base32 string 将TSID编码为Crockford Base32字符串
    Instant
    extractTimestamp(long tsid)
    Extracts the timestamp from a TSID 从TSID提取时间戳
    static Instant
    extractTimestampStatic(long tsid)
    Extracts the timestamp from a TSID with default epoch 使用默认起始时间从TSID提取时间戳
    Long
    generate()
    Generates the next ID 生成下一个ID
    String
    generateStr()
    Generates a TSID as Crockford's Base32 string 生成Crockford Base32编码的TSID字符串
    long
    getEpoch()
    Gets the epoch 获取起始时间
    int
    getNodeBits()
    Gets the node bits 获取节点位数
    long
    getNodeId()
    Gets the node ID 获取节点ID
    String
    getType()
    Gets the generator type name 获取生成器类型名称
    static boolean
    isValid(String tsidStr)
    Validates a TSID string 验证TSID字符串

    Methods inherited from class Object

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

    Methods inherited from interface IdGenerator

    generateBatch

  • Field Details

    • DEFAULT_EPOCH

      public static final long DEFAULT_EPOCH
      Default epoch: 2020-01-01 00:00:00 UTC 默认起始时间：2020-01-01 00:00:00 UTC
      See Also:

  • Method Details

    • create

      public static TsidGenerator create()
      Creates a TSID generator with default settings 使用默认设置创建TSID生成器
      Returns:
      generator | 生成器

    • create

      public static TsidGenerator create(int nodeBits, long nodeId)
      Creates a TSID generator with node configuration 使用节点配置创建TSID生成器
      Parameters:
      nodeBits - the number of bits for node ID (0-22) | 节点ID位数（0-22）
      nodeId - the node ID | 节点ID
      Returns:
      generator | 生成器

    • create

      public static TsidGenerator create(long epoch, int nodeBits, long nodeId)
      Creates a TSID generator with full configuration 使用完整配置创建TSID生成器
      Parameters:
      epoch - the custom epoch in milliseconds | 自定义起始时间（毫秒）
      nodeBits - the number of bits for node ID (0-22) | 节点ID位数（0-22）
      nodeId - the node ID | 节点ID
      Returns:
      generator | 生成器

    • generate

      public Long generate()
      Description copied from interface: IdGenerator
      Generates the next ID 生成下一个ID
      Specified by:
      generate in interface IdGenerator<Long>
      Returns:
      generated ID | 生成的ID

    • generateStr

      public String generateStr()
      Generates a TSID as Crockford's Base32 string 生成Crockford Base32编码的TSID字符串
      Returns:
      13-character TSID string | 13字符TSID字符串

    • encode

      public static String encode(long tsid)
      Encodes a TSID to Crockford's Base32 string 将TSID编码为Crockford Base32字符串
      Parameters:
      tsid - the TSID value | TSID值
      Returns:
      13-character string | 13字符字符串

    • decode

      public static long decode(String tsidStr)
      Decodes a TSID string to long value 将TSID字符串解码为长整型值
      Parameters:
      tsidStr - the TSID string | TSID字符串
      Returns:
      TSID value | TSID值
      Throws:
      IllegalArgumentException - if the string is invalid

    • extractTimestamp

      public Instant extractTimestamp(long tsid)
      Extracts the timestamp from a TSID 从TSID提取时间戳
      Parameters:
      tsid - the TSID value | TSID值
      Returns:
      the timestamp instant | 时间戳

    • extractTimestampStatic

      public static Instant extractTimestampStatic(long tsid)
      Extracts the timestamp from a TSID with default epoch 使用默认起始时间从TSID提取时间戳
      Parameters:
      tsid - the TSID value | TSID值
      Returns:
      the timestamp instant | 时间戳

    • isValid

      public static boolean isValid(String tsidStr)
      Validates a TSID string 验证TSID字符串
      Parameters:
      tsidStr - the TSID string | TSID字符串
      Returns:
      true if valid | 如果有效返回true

    • getEpoch

      public long getEpoch()
      Gets the epoch 获取起始时间
      Returns:
      epoch in milliseconds | 起始时间（毫秒）

    • getNodeBits

      public int getNodeBits()
      Gets the node bits 获取节点位数
      Returns:
      node bits | 节点位数

    • getNodeId

      public long getNodeId()
      Gets the node ID 获取节点ID
      Returns:
      node ID | 节点ID

    • getType

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