Go encoding.TextAppender 怎么减少临时字符串：追加接口、缓冲区复用与错误传播

日志字段、协议头和批量导出都经常需要把一个 Go 值转成文本。如果每个值都先执行 MarshalText()，再把返回的字节复制进总缓冲区，短字符串很多时就会积累出一批临时切片。Go 的 encoding.TextAppender 针对的就是这个边界：让类型把文本追加到调用方提供的缓冲区，并把编码错误原样交回调用方。

为什么 MarshalText 在批量格式化中会产生额外工作

encoding.TextMarshaler 的使用方式很直观：方法返回一段新文本，调用方再把它放进自己的输出缓冲区。对于低频调用，这种写法足够清楚；但在循环中格式化成百上千个字段时，中间字节切片的生命周期会变得明显。

type UserID uint64

func (id UserID) MarshalText() ([]byte, error) {
    return []byte(strconv.FormatUint(uint64(id), 10)), nil
}

func appendOld(dst []byte, id UserID) ([]byte, error) {
    text, err := id.MarshalText()
    if err != nil {
        return dst, err
    }
    return append(dst, text...), nil
}

这里的问题不是 append 不能复用 dst，而是编码器先制造了一个独立的 text。如果类型本来就能直接写入数字、日期或短标签，追加接口可以把这段中间结果省掉。

TextAppender 的最小实现应该长什么样

TextAppender 的方法接收已有的 []byte，返回追加后的切片和错误。下面的实现把数字直接追加到调用方缓冲区，成功时不创建中间文本。

type UserID uint64

func (id UserID) AppendText(dst []byte) ([]byte, error) {
    return strconv.AppendUint(dst, uint64(id), 10), nil
}

func appendRecord(dst []byte, id UserID) ([]byte, error) {
    dst = append(dst, "id="...)
    var err error
    if appender, ok := any(id).(encoding.TextAppender); ok {
        dst, err = appender.AppendText(dst)
    }
    if err != nil {
        return dst, err
    }
    return append(dst, ';'), nil
}

实际工程里可以把接口判断放在更稳定的编码层，而不是每个字段都用反射式路径。更重要的是，dst 的所有权仍然属于调用方：实现只能追加内容，不能把它保存到全局变量，也不能假设底层数组永远不会扩容。

成功和失败时都要保持缓冲区语义稳定

追加编码通常是多个字段串联执行的。某个字段失败时，调用方需要知道已经追加了多少内容，再决定丢弃整条记录还是保留错误前缀。因此实现不能把错误改成空结果，更不能返回一个与输入缓冲区无关的新切片来掩盖失败。

如果一个编码器会在中途追加多段内容，推荐先在局部切片上完成，再由上层一次性提交；如果必须流式输出，则要在错误日志中保留字段和阶段，而不是只记录“文本编码失败”。

用基准测试确认优化没有改变输出

只比较 ns/op 很容易误判。先写一个固定输入的基准，同时检查分配次数和最终字节内容；然后再增加一个会返回错误的类型，验证失败路径没有被吞掉。

func BenchmarkAppendText(b *testing.B) {
    id := UserID(20260826)
    b.ReportAllocs()
    for i := 0; i 

容量要按真实记录的大小设置一组合理基线，再比较零容量、预留容量和复用工作缓冲区的结果。复用缓冲区时不要跨请求共享；否则性能优化会变成数据串线问题。

常见问题

TextAppender 会自动替代所有 MarshalText 吗？

不会。它只适合调用方已经拥有输出缓冲区的路径；需要独立字节结果或兼容旧接口时，仍可以保留 MarshalText。

AppendText 返回错误后要不要清空 dst？

通常不要由底层实现擅自清空。由上层根据记录边界选择丢弃当前记录、回滚到检查点，或把部分输出交给诊断日志。

预留容量越大越好吗？

不是。容量应接近真实记录的常见大小；过度预留会抬高每个请求的内存占用，应该用基准和线上样本共同决定。

实现 TextAppender 后还需要测试 MarshalText 吗？

如果两个接口都保留，需要分别测试。它们的输出应一致，但分配行为、错误路径和调用方缓冲区语义并不相同。