Class SnowflakeFriendlyId

java.lang.Object
cloud.opencode.base.id.snowflake.SnowflakeFriendlyId
public final class SnowflakeFriendlyId extends Object
Snowflake Friendly ID - Human-readable representation for debugging and logging 雪花ID友好格式 - 用于调试和日志记录的人类可读表示

Converts opaque Snowflake long values to and from a human-readable string format that makes it trivial to extract the timestamp, datacenter, worker, and sequence components without a separate tool. Inspired by CosId's SnowflakeFriendlyId.

在不透明的雪花long值和人类可读字符串格式之间相互转换， 无需额外工具即可轻松提取时间戳、数据中心、工作节点和序列号组件。 灵感来自CosId的SnowflakeFriendlyId。

Format | 格式:

{ISO-8601-timestamp}#{datacenterId}-{workerId}-{sequence}

Examples:
  "2024-01-15T10:30:00.123Z#3-7-42"
  "2024-06-01T00:00:00.000Z#0-0-0"

Features | 主要功能:

  • Convert Snowflake long to human-readable string - 雪花long转人类可读字符串
  • Parse back to original Snowflake long - 解析还原原始雪花long
  • Configurable bit layout via SnowflakeConfig - 通过SnowflakeConfig配置位布局
  • Useful in logs, monitoring, and support tickets - 适用于日志、监控和技术支持

Usage Examples | 使用示例:

SnowflakeFriendlyId friendly = SnowflakeFriendlyId.ofDefault();

long id = snowflakeGenerator.generate();
String readable = friendly.toFriendly(id);
// e.g. "2024-01-15T10:30:00.123Z#3-7-42"

long recovered = friendly.fromFriendly(readable);
assert recovered == id;

boolean ok = friendly.isFriendlyFormat("2024-01-15T10:30:00.123Z#3-7-42"); // true

Security | 安全性:

  • Thread-safe: Yes (stateless after construction) - 线程安全: 是（构造后无状态）
  • Null-safe: No - 空值安全: 否
Since:
JDK 25, opencode-base-id V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • of

      public static SnowflakeFriendlyId of(SnowflakeConfig config)
      Creates a SnowflakeFriendlyId with the given configuration 使用给定配置创建SnowflakeFriendlyId
      Parameters:
      config - the Snowflake configuration | 雪花配置
      Returns:
      instance | 实例

    • ofDefault

      public static SnowflakeFriendlyId ofDefault()
      Creates a SnowflakeFriendlyId with the default configuration 使用默认配置创建SnowflakeFriendlyId
      Returns:
      instance | 实例

    • toFriendly

      public String toFriendly(long snowflakeId)
      Converts a Snowflake ID to its human-readable friendly format 将雪花ID转换为人类可读的友好格式

      Examples | 示例:

      toFriendly(1705312200123049003L) = "2024-01-15T10:30:00.123Z#3-7-42"
toFriendly(0L)                  = "2021-01-01T00:00:00.000Z#0-0-0"

      Performance | 性能:

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

      Parameters:
      snowflakeId - the Snowflake ID | 雪花ID
      Returns:
      human-readable string | 人类可读字符串

    • fromFriendly

      public long fromFriendly(String friendly)
      Parses a friendly format string back to a Snowflake ID long 将友好格式字符串解析还原为雪花ID的long值

      Examples | 示例:

      fromFriendly("2024-01-15T10:30:00.123Z#3-7-42") = 1705312200123049003L (config-dependent)

      Performance | 性能:

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

      Parameters:
      friendly - the friendly format string | 友好格式字符串
      Returns:
      Snowflake ID | 雪花ID
      Throws:
      OpenIdGenerationException - if the format is invalid | 格式无效时抛出

    • isFriendlyFormat

      public boolean isFriendlyFormat(String s)
      Checks whether a string is in the expected friendly format 检查字符串是否符合预期的友好格式
      Parameters:
      s - the string to check | 要检查的字符串
      Returns:
      true if the format is valid | 如果格式有效返回true

    • getConfig

      public SnowflakeConfig getConfig()
      Returns the configuration used by this instance 返回此实例使用的配置
      Returns:
      Snowflake configuration | 雪花配置