Go ksuid 怎样把KSUID保存为固定长度二进制

Go 的 segmentio/ksuid 可以用 id.Bytes() 获取完整20字节二进制，再用 ksuid.FromBytes(raw) 恢复。不要把 []byte(id.String()) 当成二进制编码：它仍是27字符Base62文本的字节。要保存固定长度记录，应在写入边界明确“完整20字节”，而不是截取字符串或仅保存随机载荷。

项目官方地址：https://github.com/segmentio/ksuid

本文以 v1.0.4 的文档与源码为依据，示例为原创存储辅助函数，不宣称该版本最新，也不提供伪造的运行输出。

先看写入的究竟是20字节还是27字符

设想一个服务原来把KSUID保存为文本，后来新增固定长度二进制字段，却仍沿用字符串参数：字段定义变了，应用写入内容并没有跟着变。这时先看参数的类型与长度，比立刻更改字段大小更有用。

KSUID的二进制结构包含4字节大端时间戳和16字节载荷。保存时直接保留完整表示，不需要自行重排时间戳字节，也不应套用16字节UUID的长度。截断27字符文本既不会完成Base62解码，还会破坏原标识。

保存完整字节，恢复时拒绝错误长度

下面将每条记录固定为20字节，写出时处理短写，读入时使用 io.ReadFull 填满一条记录。辅助函数不接管传入流的生命周期；调用方若打开文件，应负责关闭并按持久化要求处理同步、事务或临时文件替换。

package idstore

import (
    "fmt"
    "io"

    "github.com/segmentio/ksuid"
)

const RecordSize = 20

// EncodeRecord用固定数组表达存储尺寸，不依赖文本长度。
func EncodeRecord(id ksuid.KSUID) ([RecordSize]byte, error) {
    var record [RecordSize]byte
    if id.IsNil() {
        // 本例业务不接受空标识；这不是二进制格式本身的限制。
        return record, fmt.Errorf("不允许保存空KSUID")
    }
    copy(record[:], id.Bytes())
    return record, nil
}

// DecodeRecord拒绝长度错误，不截断或补零修复输入。
func DecodeRecord(raw []byte) (ksuid.KSUID, error) {
    id, err := ksuid.FromBytes(raw)
    if err != nil {
        return ksuid.Nil, fmt.Errorf("读取KSUID记录: %w", err)
    }
    if id.IsNil() {
        return ksuid.Nil, fmt.Errorf("记录中包含空KSUID")
    }
    return id, nil
}

// WriteRecord不拥有w，文件句柄由调用方创建和关闭。
func WriteRecord(w io.Writer, id ksuid.KSUID) error {
    record, err := EncodeRecord(id)
    if err != nil {
        return err
    }
    n, err := w.Write(record[:])
    if err != nil {
        return fmt.Errorf("写入KSUID记录: %w", err)
    }
    if n != len(record) {
        // 短写可能已经留下部分数据，调用方需要处理存储事务。
        return io.ErrShortWrite
    }
    return nil
}

// ReadRecord只读取一个20字节记录，错误原样保留供上层分类。
func ReadRecord(r io.Reader) (ksuid.KSUID, error) {
    var record [RecordSize]byte
    if _, err := io.ReadFull(r, record[:]); err != nil {
        return ksuid.Nil, err
    }
    return DecodeRecord(record[:])
}

EncodeRecord返回固定数组，便于在协议层表达尺寸。恢复入口保持切片参数并交给FromBytes检查长度，不做“多了截掉、少了补零”的猜测修复。示例额外拒绝空KSUID，是业务约定；若业务允许零值，应单独定义它与缺失值的区别。

连续记录文件可以逐次调用ReadRecord。到达新记录边界且没有读到任何字节时，io.ReadFull返回io.EOF；读到部分记录后结束则返回io.ErrUnexpectedEOF。后者应作为截断数据处理，不能当作正常文件结尾悄悄忽略。这些是接口语义说明，不是已执行的结果。

WriteRecord失败并不保证底层没有留下数据。它也不能自动回滚一个已经写入部分字节的流。调用方要保存记录边界或使用适合自身介质的事务策略，不要在原位置不明时盲目追加重试。

数据库参数为什么要显式传字节

v1.0.4 的KSUID实现了SQL值接口：非空值返回文本字符串，空KSUID返回nil。因此，直接把id作为SQL参数，不等价于把20字节二进制传给驱动。二进制列应显式使用 id.Bytes()，或者从EncodeRecord获得数组后以 record[:] 传入。

这不意味着所有数据库或驱动都采用同一种字段声明。应让字段、参数绑定和扫描目标都支持完整字节，不进行字符集转换、文本截断或隐式补齐。取回字节后使用DecodeRecord，才能在应用边界发现尺寸不符。本文不假设某个具体数据库已经创建或写入成功。

若数据库允许NULL，要先区分NULL、零长度字节和20字节全零记录。它们不应因为业务都显示“空”就共用一条不明确的恢复逻辑。上面的辅助函数只接受业务允许的非空完整标识。

旧数据怎样迁移和回退

从文本迁移时，解析旧文本应使用ksuid.Parse；成功得到KSUID对象后，再取完整二进制写入新位置。不要使用通用Base64解码，也不要把原字符串前20字节直接复制过去。

1. 保留旧文本字段或旧文件，新增明确的二进制存储位置，并记录表示版本。
2. 分批读取旧记录，遇到Parse错误时保留该条原值与错误，停止或隔离当前批，不生成新ID替换。
3. 在迁移程序中定义往返比较：新字节恢复后的KSUID应与旧文本解析结果相同；这属于读者实施迁移时的检查条件。
4. 双写过渡期间明确失败处理与补偿责任，完成应用读路径切换前不删除旧表示。

回退读路径需要旧数据仍然完整且持续更新。如果新版本已经只写二进制，旧文本副本可能落后，不能仅切回旧程序就假定数据无损。应事先确定双写截止点、补写方式及迁移批次边界，而不是故障后再猜。

接入后记录哪些信号

适合记录的信号包括序列化类型、字节长度、解析错误数、短写数和迁移批次号。日志里用“binary20”或“base62text”这类明确名称，比统一写“id bytes”更容易排查。20与27的差异只是表示长度差异，不代表索引、行存储或网络开销一定按同样比例下降。

MarshalBinary也可以使用吗？可以，该版本方法返回二进制表示；调用方仍应按它的签名处理返回错误。Bytes更适合本例直接构造固定数组的写法。

恢复成功能证明这个ID真实存在吗？不能。FromBytes主要确认长度并构造标识，并不查询业务数据，也不证明其来源。是否属于当前对象，需要应用自己的业务关系判断。

从文本转为二进制需要重新生成ID吗？不需要。同一标识只是表示方式改变。迁移时重新生成ID会改变引用关系，不能作为处理解析错误的快捷方式。

参考资料：KSUID接口文档；v1.0.4类型与序列化实现；KSUID项目说明；Go io.ReadFull文档。