Go ksuid 怎样生成并解析KSUID文本

我在接口需要一个可直接放进 URL、日志和消息体的唯一标识时，会先看 github.com/segmentio/ksuid。它的 Go API 足够短：用 NewRandom 创建 KSUID，用 String 得到 27 个字符的文本，再用 Parse 把外部文本还原成可读取时间和负载的值。

先把 KSUID 文本和内部结构分开

KSUID 是一种带时间成分的全局唯一标识。官方文档把它定义为 20 字节值：前 4 字节是大端序的 UTC 时间戳，后 16 字节是随机负载；对外使用的文本形式则是固定 27 个字符的 Base62 编码。文本和二进制都具备按字典序接近按生成时间排序的特性，但这依赖墙上时钟，不能把它当成严格的全局时序或安全授权凭证。

因此，文章中的“生成文本”其实分成两步：先得到 KSUID 值，再把值编码为字符串。下面的关系图只标出数据形态和 API 职责，不代表真实运行截图。

最小配方：生成 KSUID 并拿到文本

安装依赖时把模块加入当前项目，然后在生成函数里保留错误分支。NewRandom 返回 (KSUID, error)，适合需要显式处理随机源失败的业务；如果确实希望使用库提供的 panic 语义，才考虑 New，不要在两者之间无意识切换。

# 在当前 Go module 中加入 ksuid 依赖
go get github.com/segmentio/ksuid

package main

import (
    "fmt"
    "log"

    "github.com/segmentio/ksuid"
)

func newKSUIDText() (string, error) {
    // 显式接收 error，避免把随机源异常伪装成普通业务结果。
    id, err := ksuid.NewRandom()
    if err != nil {
        return "", fmt.Errorf("generate ksuid: %w", err)
    }

    // String 返回固定 27 字符的 Base62 文本，适合日志和消息字段。
    return id.String(), nil
}

func main() {
    text, err := newKSUIDText()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(text)
}

这里不要把生成出的具体字符串写死在测试以外的业务代码中。每次调用都会得到一个新的 KSUID；如果只是要把标识放入 JSON、URL 或日志，保存 String() 的结果即可。文本不含分隔符，适合需要单字段传输的场景，但仍应按普通外部输入处理。

解析文本后再读取时间和负载

解析的关键是把“不可信字符串”和“已确认的 KSUID 值”分开。Parse 失败时不要继续调用字段方法，也不要用字符串长度判断代替解析；长度正确并不等于字符集、编码和整体值都正确。

func inspectKSUIDText(text string) error {
    // Parse 同时完成文本格式和内容解码，失败时立即返回。
    id, err := ksuid.Parse(text)
    if err != nil {
        return fmt.Errorf("parse ksuid %q: %w", text, err)
    }

    // 解析成功后再读取时间戳、时间和 16 字节负载。
    fmt.Printf("id=%s time=%s timestamp=%d payload=%x\n",
        id.String(),
        id.Time().UTC().Format(time.RFC3339),
        id.Timestamp(),
        id.Payload(),
    )
    return nil
}

完整示例需要补上 time 包，并在调用处决定错误是返回给上层、记录日志还是转成请求参数错误：

package main

import (
    "fmt"
    "time"

    "github.com/segmentio/ksuid"
)

func parseKSUIDText(text string) error {
    // 外部文本先解析，失败就停止，避免读取无效对象的字段。
    id, err := ksuid.Parse(text)
    if err != nil {
        return fmt.Errorf("invalid ksuid: %w", err)
    }

    // 时间用于展示或粗略分组，Payload 只在确有字段化需求时读取。
    fmt.Printf("text=%s\n", id.String())
    fmt.Printf("time=%s\n", id.Time().UTC().Format(time.RFC3339))
    fmt.Printf("timestamp=%d\n", id.Timestamp())
    fmt.Printf("payload-bytes=%d\n", len(id.Payload()))
    return nil
}

文本、二进制和字段读取怎样取舍

我通常把文本形态留给 URL、日志、JSON 和人工排查，把 Bytes() 留给明确需要二进制存储的边界。不要为了“看起来更专业”在每一层都来回转换；转换越多，越容易把字符串错误、空值和数据库字段类型混在一起。

尤其要注意：KSUID 的时间部分适合排序和排查线索，但官方说明也指出它不是严格排序不变量，墙上时钟会影响结果。若业务需要严格递增序列、幂等约束或权限校验，应在数据库约束、服务端状态或签名机制上补足，不能把一个可排序 ID 当成完整的业务协议。

常见问题

为什么不直接用 New 而用 NewRandom？

NewRandom 把随机源失败作为 error 返回，调用方可以决定如何处理；New 在无法读取随机字节的异常情况下会 panic。工程代码应按故障边界选择，而不是只看调用长度。

解析成功后能不能把 KSUID 当作时间戳？

不能。KSUID 同时包含自定义纪元时间戳和随机负载；Time() 只能取出其中的时间成分，不能证明业务事件一定在该时刻发生。

只保存 27 字符文本可以吗？

可以，前提是接收端接受字符串并在边界处调用 Parse。如果存储层已经约定二进制列，再统一使用 Bytes、MarshalBinary 或数据库接口，避免同一字段一部分存文本、一部分存二进制。