Go encoding/binary.Append 如何承接返回值：编码追加与切片容量边界

如果你已经有一段协议头，想继续把整数或固定大小的结构编码到后面，Go 里可以用 encoding/binary.Append。它的关键不是“把数据写进去”这么简单：调用方必须接住返回的 []byte，因为追加过程中可能复用原切片，也可能得到一块新的底层数组。

记住一句话：把 binary.Append(buf, order, data) 的返回值重新赋给 buf，再检查 error；不要假定原切片变量会自动变长。

先看清 Append 的返回值和数据边界

binary.Append 的签名是 func Append(buf []byte, order ByteOrder, data any) ([]byte, error)。它把 data 的二进制表示追加到 buf 尾部，返回“可能扩展后的 buf”以及错误。buf 可以是 nil，字节序可以使用 binary.BigEndian 或 binary.LittleEndian。

这里的“固定大小”有明确边界：基础数值类型，以及只由固定大小字段组成的数组或结构体可以编码；带有字符串、切片等动态字段的结构体不属于这条路径。官方文档也提醒，想编码复杂数据结构时，应考虑更适合的高级序列化方案。

package main

import (
    "encoding/binary"
    "fmt"
)

func main() {
    buf := []byte{0x7f}
    var err error
    buf, err = binary.Append(buf, binary.BigEndian, uint16(0x1234))
    if err != nil {
        panic(err)
    }
    fmt.Printf("% x\n", buf) // 7f 12 34
}

这段代码里，buf 是输入，也是输出；data 是待追加的 uint16；error 则决定后续是否还能继续组装消息。三个节点的关系可以概括为：buf 进入 binary.Append，携带 data，再由返回值覆盖 buf。

容量足够和容量不足，都会改变你的判断

切片有长度和容量两个边界。假设 buf := make([]byte, 1, 8)，当前只有一个有效字节，但后面还有容量，追加 uint16 时通常可以在同一底层数组中写入；如果容量不够，追加操作会分配更大的数组。无论哪种情况，调用方都只能把返回值当作新的有效切片。

buf := make([]byte, 1, 8)
buf[0] = 0x7f

next, err := binary.Append(buf, binary.BigEndian, uint32(42))
if err != nil {
    return err
}
buf = next
fmt.Printf("len=%d cap=%d data=% x\n", len(buf), cap(buf), buf)

buf 和 next 可能共享底层数组，也可能不共享；这不是应该依赖的业务事实。可依赖的是 next 的长度代表追加后的有效范围，而 cap(next) 只是后续追加的空间提示。

因此，下面这种写法容易留下隐蔽问题：调用了 binary.Append 却丢掉返回值。即使容量刚好足够，后续逻辑仍然只会看到旧的 len(buf)；一旦发生扩容，新增字节甚至不在旧切片的可见范围内。

错误返回时，消息拼装应该在哪里停下

binary.Append 对不支持的 data 类型返回错误。比如把包含字符串字段的结构体直接传进去，就不能把它当成固定大小值处理。实际协议编码中，最稳妥的顺序是每次追加都立即检查 error，失败就返回，不继续向一个不完整的消息尾部追加字段。

type Header struct {
    Version uint8
    Length  uint16
}

func encodeHeader(buf []byte, h Header) ([]byte, error) {
    next, err := binary.Append(buf, binary.BigEndian, h)
    if err != nil {
        return buf, err
    }
    return next, nil
}

这个例子把 Header 作为固定大小结构体；若后来给它加上 string 或 []byte 字段，调用仍可能编译通过，但运行时的返回错误就会成为兼容性信号。接口层要把这个错误传回调用方，而不是悄悄返回半截字节流。

把选择落到三个检查点

• 检查承接：每次调用都写成 buf, err = binary.Append(...)，或先用 next 接住再覆盖。
• 检查类型：确认传入值是固定大小类型、数组或固定大小结构体；动态字段要先单独编码。
• 检查失败：追加返回错误时立即停止，并明确这段 buf 是否允许作为部分结果继续使用。

如果只是编码一个简单的数值，binary.AppendUvarint 和 binary.AppendVarint 也会返回追加后的切片，但它们采用变长整数编码，不能和固定宽度的 Append 结果混为一谈。

相关问题

为什么不能只看 cap(buf) 判断追加是否成功？

cap 只能描述容量，不代表数据已经写入有效长度。判断追加结果要看返回切片的 len，并处理返回的 error。

binary.Append 会修改传入的 buf 吗？

容量足够时可能写入同一底层数组，容量不足时可能换数组。不要依赖是否共享；只使用返回切片作为后续数据路径。

什么时候不适合使用 binary.Append？

当数据包含字符串、切片或其他动态字段，或者协议需要自描述结构时，应先设计字段长度与布局，必要时选择专用序列化格式。

最后的判断

encoding/binary.Append 解决的是“把固定大小值追加到字节切片”这件事，但它把切片所有权交回给返回值。把返回值、容量变化和错误处理放在同一个检查点，才能避免消息尾部丢失、扩容后仍读旧切片，以及错误后继续发送半成品。