LibEcto.Ksuid (lib_ecto v0.4.0)

View Source

KSUID (K-Sortable Unique Identifier) 生成和解析模块

KSUID 是一种可排序的唯一标识符，由时间戳和随机数据组成。 结构：4字节时间戳 + 16字节随机数据，Base62编码后27字符。

特点

  • 时间排序：基于时间戳的排序能力
  • 高唯一性：使用随机数据确保唯一性
  • URL安全：使用Base62编码，可在URL中安全使用
  • 高效存储：二进制表示高效紧凑

使用示例

# 生成KSUID
ksuid = LibEcto.Ksuid.generate()

# 使用自定义时间戳生成KSUID
timestamp = System.system_time(:second)
ksuid = LibEcto.Ksuid.generate(timestamp)

# 解析KSUID
{:ok, timestamp, random_bytes} = LibEcto.Ksuid.parse(ksuid)

Summary

Types

parse_result()

解析结果，成功返回时间戳和随机数据，失败返回错误信息

t()

KSUID 字符串表示形式，Base62编码，27字符长度

timestamp()

表示自Unix纪元以来的秒数的非负整数

Functions

generate(ts \\ System.system_time(:second))

生成一个新的KSUID。

parse(ksuid)

解析KSUID字符串，提取时间戳和随机数据部分。

Types

parse_result()

@type parse_result() :: {:ok, NaiveDateTime.t(), binary()} | {:error, binary()}

解析结果，成功返回时间戳和随机数据，失败返回错误信息

t()

@type t() :: binary()

KSUID 字符串表示形式，Base62编码，27字符长度

timestamp()

@type timestamp() :: non_neg_integer()

表示自Unix纪元以来的秒数的非负整数

Functions

generate(ts \\ System.system_time(:second))

@spec generate(timestamp()) :: t()

生成一个新的KSUID。

可选参数允许提供自定义时间戳，默认使用当前系统时间。

参数

  • ts - 可选的时间戳（Unix秒数）。默认为当前系统时间。

返回值

返回生成的KSUID字符串，Base62编码，27字符长度。

示例

iex> ksuid = LibEcto.Ksuid.generate()
iex> is_binary(ksuid) and String.length(ksuid) == 27
true

iex> ksuid = LibEcto.Ksuid.generate(1632304869)
iex> is_binary(ksuid) and String.length(ksuid) == 27
true

parse(ksuid)

@spec parse(binary()) :: parse_result()

解析KSUID字符串，提取时间戳和随机数据部分。

参数

  • ksuid - 要解析的KSUID字符串

返回值

成功时返回 {:ok, timestamp, random_bytes}，其中：

  • timestamp - NaiveDateTime格式的时间戳
  • random_bytes - 16字节的随机数据

失败时返回 {:error, reason}

示例

iex> ksuid = LibEcto.Ksuid.generate()
iex> {:ok, timestamp, random_bytes} = LibEcto.Ksuid.parse(ksuid)
iex> is_struct(timestamp, NaiveDateTime) and byte_size(random_bytes) == 16
true