Go encoding.TextAppender 怎样减少文本格式化分配

如果你的代码已经有一个 []byte 缓冲区，却还要先把对象格式化成一块新的字节切片，再复制到缓冲区，可以看看 Go 1.24 新增的 encoding.TextAppender。它的核心不是改变文本内容，而是让类型通过 AppendText(b []byte) 把结果直接接在调用方已有的字节后面。

最小判断是：需要复用已有缓冲区时实现 TextAppender；仍要兼容只认识 encoding.TextMarshaler 的旧调用方时，再让 MarshalText 调用同一套追加逻辑。

TextAppender 解决的是“追加到已有缓冲区”

TextAppender 只有一个方法：AppendText(b []byte) ([]byte, error)。输入的 b 可能已经包含日志前缀、协议字段或分隔符，实现要把自己的文本追加到它的末尾，并返回更新后的切片。

接口契约还有两个容易忽略的边界：实现不能保留调用方传入的 b，也不能修改 b[:len(b)] 中已有的字节。也就是说，追加可以复用容量，但前缀的内容和所有权仍由调用方负责。

自定义类型怎样实现 AppendText

对于整数、布尔值和浮点数，优先使用 strconv.Append... 系列函数。它们直接接收目标切片，避免先生成临时字符串。下面的类型把一个构建编号追加成十进制文本：

package buildid

import (
    "encoding"
    "strconv"
)

type BuildID uint64

func (id BuildID) AppendText(b []byte) ([]byte, error) {
    // 直接在调用方切片后追加十进制文本，不改写 b[:len(b)]。
    return strconv.AppendUint(b, uint64(id), 10), nil
}

func (id BuildID) MarshalText() ([]byte, error) {
    // 旧调用方仍可通过 TextMarshaler 获得同一份文本语义。
    return id.AppendText(nil)
}

调用时可以把已有前缀传进去：

func formatBuild(id BuildID) ([]byte, error) {
    buf := make([]byte, 0, 32)
    buf = append(buf, "build="...)

    var appender encoding.TextAppender = id

    // 追加接口返回新切片，错误必须沿调用链返回。
    return appender.AppendText(buf)
}

这里的关键不是把接口变量写得多复杂，而是保留返回值。追加可能触发扩容，继续使用旧的 buf 变量会丢失新切片的地址。

和 TextMarshaler 一起实现时要守住语义

Go 1.24 的发布说明把 TextAppender 描述为 TextMarshaler 的追加版本：如果一个类型同时实现两者，那么 MarshalText() 的语义应当等同于 AppendText(nil)。因此，最稳妥的写法是只维护一份追加逻辑，让 MarshalText 负责兼容入口。

不要在 AppendText 中缓存传入的切片，也不要为了“复用”而修改前缀。例如调用方把同一个缓冲区交给多个字段时，每个实现都只能从 len(b) 之后开始写。若编码过程可能失败，返回部分结果和错误的约定也要在类型文档里说清楚，不能把错误静默吞掉。

什么时候该用它，什么时候继续 MarshalText

如果调用方本来就有不断增长的字节缓冲区，例如批量日志、协议帧或自定义文本编码器，TextAppender 更贴合数据流。它可以减少“先返回一块新切片、再复制”的中间步骤，但不保证每次调用都零分配：容量不足时仍可能扩容，具体成本还取决于实现。

如果你的公共接口只接受 TextMarshaler，或代码需要把完整结果交给一个独立的序列化边界，MarshalText 仍然够用。兼容旧版本 Go 时，也要注意 TextAppender 是 Go 1.24 新增接口，不能把它当成所有工具链都存在的基础能力。

常见问题

AppendText 一定比 MarshalText 快吗？

不一定。它减少的是追加场景中的中间结果和复制机会；如果缓冲区经常扩容，或者实现内部仍然先构造字符串，收益会被抵消。

为什么返回值必须重新接住？

因为追加可能改变切片的底层数组。调用方应始终使用 b, err = value.AppendText(b) 这样的形式，并立即处理错误。

记住三点：让追加从 len(b) 开始、不要保留或改写输入前缀、让 MarshalText 与 AppendText(nil) 保持同一文本语义。这样才能在复用缓冲区的同时，不破坏旧调用方的预期。