Go encoding.BinaryAppender 怎样避免修改已有缓冲区

实现 encoding.BinaryAppender 时，核心不是把对象“写进一个新的切片”，而是把二进制表示追加到调用方传入的 []byte 后面，同时保护调用前已有的字节。实现还不能保存调用方的切片引用；如果同一个类型也实现 encoding.BinaryMarshaler，两者的结果语义应保持一致。

官方文档：https://pkg.go.dev/encoding@go1.27.2#BinaryAppender

记住三条规则：只追加，不改写 b[:len(b)]；方法返回新的切片，不保留 b；需要独立编码时用 AppendBinary(nil) 作为统一出口。

• 已有前缀属于调用方，方法只能在切片尾部追加自己的表示。
• dst 只是本次调用的输入，不应存进对象字段、全局变量或异步任务。
• 返回值必须接住，因为扩容后底层数组可能已经变化。

先拆开 BinaryAppender 的三条契约

BinaryAppender 只有一个关键方法：AppendBinary(b []byte) ([]byte, error)。传入的 b 可以已经包含别的字段，返回值则是在它后面追加当前对象二进制表示后的切片。这里的“不能修改已有缓冲区”指的是不能改写调用前的 b[:len(b)]，而不是禁止 append 在容量范围内写入新增尾部。

接口文档还要求实现不能保留 b，也不能修改已有长度范围内的字节。换句话说，调用者可以把一个带有协议头、前置标记或其他对象数据的切片传进来，调用返回后这些前缀仍应保持原样。

这也是它和“返回一份全新编码结果”的思路不同之处：追加式 API 允许调用方把多个二进制片段组合到同一缓冲区中。具体是否复用底层容量由 append 决定，调用方不应该依赖某一次调用一定不分配。

用 append 写一个不会覆盖前缀的类型

下面定义一个很小的 Packet 类型。它把一个字节类型码和一个大端序的两字节长度追加到已有缓冲区。数值只是示例协议字段，不代表任何真实协议。

package packet

import (
    "encoding/binary"
)

// Packet 只演示追加式二进制编码，不代表完整网络协议。
type Packet struct {
    Code  byte
    Size  uint16
}

// AppendBinary 保留 dst 中已有的前缀，只在尾部追加 Packet 的表示。
func (p Packet) AppendBinary(dst []byte) ([]byte, error) {
    dst = append(dst, p.Code)
    // 返回值必须接住，扩容后可能已经换了底层数组。
    dst = binary.BigEndian.AppendUint16(dst, p.Size)
    return dst, nil
}

// MarshalBinary 与 AppendBinary(nil) 共用同一套编码语义。
func (p Packet) MarshalBinary() ([]byte, error) {
    return p.AppendBinary(nil)
}

这个实现没有用下标写入已有位置，也没有把 dst 赋给 Packet 的字段。两次 append 都从切片尾部开始，因此调用者传入的前缀不会被覆盖；如果底层容量不足，返回的新切片也会通过返回值交给调用方。

错误返回位在这个简单类型中始终是 nil，但仍保留接口形状。更复杂的编码可能需要检查字段是否满足范围或调用下层编码器是否失败，此时应返回原始错误或带上下文包装后的错误，而不是静默截断。

BinaryMarshaler 怎样与追加编码保持一致

如果类型同时实现 BinaryMarshaler，最容易出问题的是维护两套几乎相同但细节不同的编码逻辑。例如 AppendBinary 写入了类型码，而 MarshalBinary 忘了写；或者一边使用大端序，另一边使用小端序。这样的差异会让调用方根据接口类型得到不同字节表示。

更稳妥的方式是让 MarshalBinary 直接调用 AppendBinary(nil)。官方契约要求两者在这种情况下语义一致，而 nil 只表示从空缓冲区开始，不改变追加方法对已有缓冲区的处理规则。

按边界定位错误实现

排查一个自定义实现时，可以先问四个问题：它有没有改写调用前的字节？有没有把传入切片保存到对象或闭包？有没有接住每次 append 的返回值？MarshalBinary 是否与空缓冲区上的追加结果一致？这四个问题比单看最终十六进制字符串更容易定位契约错误。

// 这是错误示意：它把当前对象写进调用方已有区域。
func (p Packet) badAppend(dst []byte) ([]byte, error) {
    if len(dst) == 0 {
        dst = make([]byte, 0, 3)
    }
    // 下标写入会覆盖调用者原有的第一个字节，违反 BinaryAppender 契约。
    dst[0] = p.Code
    return dst, nil
}

// 这是错误示意：保存 dst 会让对象在返回后继续持有调用方缓冲区。
type BadEncoder struct {
    retained []byte
}

func (e *BadEncoder) AppendBinary(dst []byte) ([]byte, error) {
    // 只应在本次调用中使用 dst，不能把它存进字段或异步闭包。
    e.retained = dst
    return append(dst, 1), nil
}

上面的片段只用于说明错误边界，不应作为生产实现。第一段还存在长度与容量混淆的问题：即使容量足够，直接下标写入也没有把长度推进到可见数据范围；真正的追加应使用 append 并接住返回值。

第二段的问题不在于当场输出是否正确，而在于方法返回后 retained 仍然指向调用方的存储。调用方可能复用、修改或释放相关对象的生命周期，编码器不应把这个切片当作自己的长期缓存。需要缓存时，应复制明确需要的字节，而不是保留整个输入切片。

常见问题

传入 nil 和传入空切片有什么区别？

对追加编码来说，两者都表示没有已有前缀，返回结果通常从追加内容开始；如果业务关心 nil 与非 nil 的切片形态，应在接口之外单独约定，不要把它当作 BinaryAppender 的追加契约。

AppendBinary 一定不会分配吗？

不一定。底层容量足够时可能复用，容量不足时会分配新的数组。调用者必须使用返回值，也不能把“不分配”当作接口保证。

为什么不能把 dst 保存起来做缓存？

因为它属于调用方，可能在方法返回后被复用或改变。BinaryAppender 的实现只在当前调用中读取和追加，若需要长期保存，应创建自己的副本并明确其成本。

把 AppendBinary 写对，关键是把它当成“向调用方缓冲区追加”的接口，而不是“借用一块内存随意改写”。保护已有前缀、接住返回值、不保存输入切片，再让 MarshalBinary 复用空缓冲区路径，通常就能避免最常见的兼容问题。