Go 自定义二进制类型怎样处理复制与解码

Go 自定义二进制类型实现 encoding.BinaryMarshaler 和 encoding.BinaryUnmarshaler 时，要先约定切片归谁所有：解码方法若在返回后保留输入内容，必须复制；编码方法则可以主动承诺每次返回独立缓冲。遇到错误，推荐先在临时变量里完成检查和构造，最后一次性更新接收者，避免留下半个新对象。

假设我要把一段短备注封装成缓存记录，我会优先选择“多一次复制、少一条隐含约定”的接口。这个场景是设计示例，并非声称经历过某次线上事故。最让我警惕的不是编码代码有多长，而是调用方复用了缓冲后，对象内容悄悄变化。

Go 官方接口文档：https://pkg.go.dev/encoding

二进制接口解决什么，不保证什么

BinaryMarshaler 的方法签名是 MarshalBinary() ([]byte, error)，BinaryUnmarshaler 对应 UnmarshalBinary([]byte) error。接口提供编码能力约定，不替应用定义字段顺序、版本号、最大长度或失败后的对象状态。想在返回后继续使用输入字节，解码器必须建立自己的副本；不能直接保存 data 的子切片。

编码输出的独立性需要另行写入类型文档。我倾向于每次分配返回值，让调用方可以保留它，也允许修改它而不影响原对象。这是下面 Packet 的设计承诺，不把它冒充所有 BinaryMarshaler 实现都具备的额外保证。

接口也不意味着所有序列化库都会调用这两个方法。接入第三方库前应看对应库的分派规则。直接调用方法当然可行；不要因为一个类型具备二进制接口，就推断 JSON 或任意网络框架会自动使用该格式。

把复制策略放进一个最小类型

这里自定义一个演示格式：版本占 1 字节，载荷长度占 2 字节并使用大端序，余下是原样字节。最大载荷为 4096 字节，空载荷合法，多余尾部数据不接受。它不是现成标准协议，也不包含校验和、压缩或身份认证。

为了让所有权约定从入口开始成立，构造函数复制入参；读取载荷时也返回副本。结构体普通赋值仍可能共享内部切片，但由于这里没有原地修改载荷的公开方法，UnmarshalBinary 又总是换成新存储，这种共享不会通过所示公开 API 产生写入联动。

package packet

import (
    "encoding"
    "encoding/binary"
    "errors"
    "fmt"
)

const maxPayload = 4096

var (
    ErrLength = errors.New("数据长度不合法")
    ErrVersion = errors.New("不支持的格式版本")
    ErrNilReceiver = errors.New("接收者为空")
)

// Packet 的字段不导出；构造、编码和读取载荷都复制，避免共享底层数组。
type Packet struct {
    payload []byte
}

var _ encoding.BinaryMarshaler = Packet{}
var _ encoding.BinaryUnmarshaler = (*Packet)(nil)

func NewPacket(payload []byte) (Packet, error) {
    if len(payload) > maxPayload {
        return Packet{}, fmt.Errorf("%w: 最多 %d 字节", ErrLength, maxPayload)
    }
    owned := make([]byte, len(payload))
    copy(owned, payload)
    return Packet{payload: owned}, nil
}

func (p Packet) Payload() []byte {
    // 调用者修改返回内容时，不影响 Packet 内部保存的数据。
    out := make([]byte, len(p.payload))
    copy(out, p.payload)
    return out
}

func (p Packet) MarshalBinary() ([]byte, error) {
    if len(p.payload) > maxPayload {
        return nil, fmt.Errorf("%w: 载荷过大", ErrLength)
    }
    // 演示协议：1 字节版本、2 字节大端长度、剩余部分为载荷。
    out := make([]byte, 3+len(p.payload))
    out[0] = 1
    binary.BigEndian.PutUint16(out[1:3], uint16(len(p.payload)))
    copy(out[3:], p.payload)
    return out, nil
}

func (p *Packet) UnmarshalBinary(data []byte) error {
    if p == nil {
        return ErrNilReceiver
    }
    // 先检查头部长度，再读取长度字段，避免短输入引发越界。
    if len(data)  maxPayload || len(data)-3 != n {
        return fmt.Errorf("%w: 声明 %d 字节，实际 %d 字节",
            ErrLength, n, len(data)-3)
    }

    // 不复用旧载荷；输入可能与旧数据重叠，且失败不应污染旧对象。
    owned := make([]byte, n)
    copy(owned, data[3:])
    next := Packet{payload: owned}
    *p = next
    return nil
}

MarshalBinary 使用值接收者，是因为它不需要修改字段；UnmarshalBinary 使用指针接收者，是因为它必须替换接收者。值接收者本身不等于深复制：复制结构体只会复制切片描述符。真正隔离数据的是 make 与 copy，而不是方法签名里的值传递。

解码失败时为什么不直接复用旧切片

一个很短却脆弱的写法，是先把接收者的载荷替换成 data[3:]，再检查其他字段。这样既保留了外部输入，也让失败可能修改对象。即便使用 append(p.payload[:0], data[3:]...)，仍可能原地覆盖旧数组，影响持有同一旧载荷的其他值。

示例的选择是将长度、版本、实际大小全部检查完，再建立 owned 副本，组成 next，最后执行 *p = next。于是普通返回 error 的路径不会修改接收者。这是本类型主动提供的错误原子性，不是接口自动赋予的事务能力，也不意味着多个 goroutine 可以无锁并发调用。

调用方怎样使用结果和错误

调用方首先处理 error，成功后才使用字节结果。不要把同时返回的非空数据与错误理解为完整可持久化记录；本例在编码失败时统一返回 nil。解码失败时可以继续使用原对象，但仍需修复输入，而不是无条件吞掉错误。

// 本片段放在使用方函数内；packet 是示例包的实际导入名。
original := []byte("note")
p, err := packet.NewPacket(original)
if err != nil {
    return err
}
wire, err := p.MarshalBinary()
if err != nil {
    return err
}
var decoded packet.Packet
if err := decoded.UnmarshalBinary(wire); err != nil {
    return err
}

// 编码和解码都持有独立存储；修改传入缓冲不应改变解码对象。
wire[3] = 'X'
payload := decoded.Payload()
_ = payload // 按示例协议，这里应仍表示 note，而非 Xote。

上面是使用片段而不是完整独立程序。将示例包放进自己的模块，并使用模块内实际导入路径；片段的 return err 需要位于返回 error 的函数中。预期语义来自独立复制的代码结构，这里不提供未执行的控制台输出或性能成绩。

如果需要按错误类别处理，可用 errors.Is(err, packet.ErrLength) 或 errors.Is(err, packet.ErrVersion)；fmt.Errorf 中的 %w 保留了错误链。对外提示可以简洁，日志则保留类别和长度信息，无需打印整个原始载荷。

兼容和性能应当在哪一层决定

新增字段时不要悄悄改写版本 1 的含义。本例对未知版本返回 ErrVersion，如果未来需要版本 2，应明确设计另一套字段定义。对尾部数据，本文选择严格拒绝；想要支持流中多个记录，需要外层按头部长度分帧，而不是把 len(data)-3 != n 简单删除。

我接受这套实现的代价是：构造、编码、解码、读取都可能分配。对于短小且需要长期持有的记录，这种成本换来了清楚的生命周期。若载荷很大、调用极密，应先按真实负载度量分配开销，再设计独立的追加编码或借用视图 API，并把失效条件写清；不能为了少一次复制而违反 UnmarshalBinary 的保留输入要求。

4096 字节限制只约束本例解码时复制的载荷，不会自动限制外层读取整条网络消息时已分配的内存。应用应在读入层限制消息大小。复制也不是并发同步措施，多个 goroutine 对同一 Packet 的读写仍需要外部同步。

空载荷能表示 nil 和空切片的区别吗

不能。本例统一把零长度编码为同一形式；如果业务必须区分“没有值”和“有一个空值”，应增加明确标志，不能依靠切片是否为 nil 推断线上格式。

为什么不直接用 encoding/binary 写整个结构体

此处需要自定义版本和变长载荷，以及清楚的错误策略。binary.BigEndian 仅负责长度整数与字节之间的转换，不会替 Packet 管理输入副本或错误原子性。官方说明：https://pkg.go.dev/encoding/binary。

结构体赋值是不是已经深复制

不是。带切片的结构体赋值可能共享底层存储。本文让公开方法不原地写旧载荷，若以后增加可变方法，就必须重新处理这些共享关系，不能沿用现在的假设。

我的结论是：先让存储归属、失败状态和格式版本可以用一句话解释，再考虑复用缓冲。Binary 接口方法写出来很容易，长期可维护的约定才是类型真正需要交付的能力。