Go encoding/binary.Append 怎样把整数追加到已有字节切片

在 Go 1.27 的 encoding/binary 中，binary.Append 适合把一个固定大小的整数或固定大小结构追加到已有的 []byte。调用时要同时传入字节序和数据，结果必须接回原变量：buf, err = binary.Append(buf, binary.BigEndian, value)。它可能复用原有容量，也可能分配新的底层数组；真正应该继续使用的是返回的切片。

如果字段采用变长整数编码，则使用 AppendUvarint 或 AppendVarint，不要把它们和固定宽度的 uint32 编码混为一谈。下面只围绕追加、字节序、容量和错误边界展开。

binary.Append 的返回值就是新的字节切片

Append 的形态是 Append(buf []byte, order ByteOrder, data any) ([]byte, error)。第一个参数是已有前缀，第二个参数决定多字节整数如何排列，第三个参数是要追加的固定大小数据。成功时返回包含新字段的切片，失败时返回错误；不要只看原来的 buf。

package main

import (
	"encoding/binary"
	"fmt"
)

func main() {
	// 预留少量容量，前缀代表协议中已经写入的版本字节。
	buf := make([]byte, 0, 8)
	buf = append(buf, 0x01)

	// 使用大端序追加固定宽度的 uint32，必须接住返回的切片。
	var err error
	buf, err = binary.Append(buf, binary.BigEndian, uint32(0x01020304))
	if err != nil {
		// 真实协议中应把错误交给上层，不要继续发送不完整字段。
		panic(err)
	}

	// 这里只展示已追加的数据长度，避免把底层数组当成协议结果。
	fmt.Println(len(buf), buf)
}

这段代码的重点不是打印结果，而是赋值关系：binary.Append 返回的 []byte 与 error 必须一起处理。对于 uint32 这样的固定大小类型，字节序会影响四个字节的排列；协议的读写两端必须约定同一个 ByteOrder。

字节序决定固定宽度整数的字节排列

binary.BigEndian 把高位字节放在前面，binary.LittleEndian 把低位字节放在前面。选择哪一个不是性能偏好，而是协议字段定义的一部分。比如同一个 uint32(0x01020304)，在两种字节序下会得到不同的四字节表示。

func appendHeader(buf []byte, version uint16, flags uint16) ([]byte, error) {
	// Header 约定为两个大端 uint16，调用方继续使用返回切片。
	buf, err := binary.Append(buf, binary.BigEndian, version)
	if err != nil {
		return nil, fmt.Errorf("append version: %w", err)
	}
	buf, err = binary.Append(buf, binary.BigEndian, flags)
	if err != nil {
		return nil, fmt.Errorf("append flags: %w", err)
	}
	return buf, nil
}

示例把每个字段单独追加，便于与解码端的字段顺序对应。若一次传入由固定大小字段组成的结构体，也要确保结构体只包含支持的固定大小成员；可变长度字符串、切片和 map 不应直接塞进这个接口。

容量复用与变长整数要分开判断

切片的 len 表示当前有效字节数，cap 表示底层数组还能容纳的范围。Append 会在可行时复用容量，不足时返回指向新数组的切片。因此不要根据“这次一定没有分配”来保存别的别名，也不要忽略函数返回值。

定长字段使用 Append；无符号或有符号整数采用变长编码时，分别使用 AppendUvarint 或 AppendVarint：

func appendLength(buf []byte, length uint64) []byte {
	// 长度字段采用 Uvarint，数值越小通常占用的字节越少。
	return binary.AppendUvarint(buf, length)
}

func appendSignedDelta(buf []byte, delta int64) []byte {
	// 有符号值使用 Varint，不能拿固定宽度的 Append 结果来解码。
	return binary.AppendVarint(buf, delta)
}

变长编码的字节数取决于数值，适合长度、计数或稀疏小整数；固定宽度编码则更容易按偏移直接读取。协议字段一旦选定编码方式，解码端必须使用相同的函数族和字段顺序。

工程集成时记住三个检查点

• 先检查返回值：所有 Append 调用都使用 buf = ... 或同时接收 buf, err。
• 再固定字节序：写入和读取使用同一个 ByteOrder，不要让默认值或平台端序替代协议约定。
• 最后核对编码族：定长字段对应 Append，无符号变长字段对应 AppendUvarint，有符号变长字段对应 AppendVarint。

如果追加失败，应该把错误包装后返回上层，不能继续把当前缓冲区当作完整报文。若要减少分配，可以提前估算容量，但这只是容量策略，不会改变字节序和编码格式。

常见问题

binary.Append 能直接追加字符串吗？

不能把任意字符串或切片当作固定大小数据直接追加。应先明确字符串的长度字段、字符编码和字节内容，再通过 append 或单独的字段编码写入协议。

为什么追加后原来的切片变量没有变化？

切片是描述符，追加可能返回新的描述符。调用方若没有接住返回值，后续仍使用旧变量，就可能看不到新字段；这是返回值使用错误，不是字节序问题。

参考：https://pkg.go.dev/encoding/binary#Append、https://pkg.go.dev/encoding/binary#AppendUvarint、https://go.dev/doc/go1.27。