Go encoding/binary.Decode 怎样把字节切片解析到结构体

如果手里已经有一段完整的二进制字节切片，想把它读成 Go 结构体，优先考虑 encoding/binary.Decode。它接收字节切片、字节序和目标数据指针，成功时返回消耗的字节数；输入太短或目标类型不适合固定布局时返回错误。

官方文档：https://pkg.go.dev/encoding/binary#Decode

它适合协议头、文件头、定长记录等场景。关键前提是目标值必须由固定大小的字段组成，不能把字符串、切片或指针字段直接当成协议正文来解析。下面用一个小型协议头说明选择方法。

先确认数据适合 Decode

Decode 解决的是“从已有的 []byte 读取固定布局”的问题。目标结构体中的整数、浮点数、布尔值、数组以及由这些类型组成的结构体，都可以纳入固定大小布局；字段的实际含义仍由协议约定决定。

package main

import (
    "encoding/binary"
    "fmt"
)

// Header 只保留固定大小字段，便于按协议头布局解析。
type Header struct {
    Version   uint16
    Flags     uint16
    BodySize  uint32
    RequestID uint64
}

func decodeHeader(buf []byte) (Header, error) {
    var header Header

    // 协议约定使用大端序；真实项目必须以协议文档为准。
    n, err := binary.Decode(buf, binary.BigEndian, &header)
    if err != nil {
        return Header{}, fmt.Errorf("解析协议头失败，已消费 %d 字节: %w", n, err)
    }
    return header, nil
}

这里传入的是 &header，因为函数需要把解码结果写入目标值。binary.BigEndian 只表示多字节数值的排列方式，不会替你判断协议中的版本号或长度字段。

按协议选择 LittleEndian 或 BigEndian

同一组字节，在不同字节序下可能得到完全不同的整数。不要根据机器的 CPU 或开发环境猜测字节序，而要跟着协议、文件格式或对端实现的约定选择。

func decodeByOrder(buf []byte, little bool) (Header, error) {
    var header Header
    order := binary.BigEndian
    if little {
        // 只有协议明确规定小端时才切换，避免把配置误当成猜测。
        order = binary.LittleEndian
    }

    // Decode 读取已有切片，不负责从网络连接继续补齐数据。
    _, err := binary.Decode(buf, order, &header)
    if err != nil {
        return Header{}, err
    }
    return header, nil
}

如果协议头前面还有魔数或版本字段，可以先切出协议头范围再调用 Decode。这样做能把“切片边界”和“结构体布局”分开，后续遇到长度错误时更容易定位。

先算尺寸，再处理 n 和 err

正式代码不要只看 err == nil。可以先用 binary.Size 得到目标固定布局需要的字节数，再决定是否调用；调用后仍保留 n 和 err，方便区分输入不完整和其它类型错误。

func decodeComplete(buf []byte) (Header, error) {
    var header Header
    need := binary.Size(header)
    if need 

Decode 成功时返回消耗的字节数；如果缓冲区太短，文档定义为返回错误。预先按 binary.Size 截取一个完整记录，也能避免后面的字节被误当成当前结构体的一部分。

Decode、Read、Encode 怎么选

这三个函数都处理固定大小数据，但入口和目标不同。已有完整字节切片时用 Decode；数据还在 io.Reader 中时用 Read；要把结构体写入字节切片时用 Encode。

func chooseAPI(buf []byte, reader io.Reader, out []byte) error {
    var header Header

    // 已经拥有字节切片时，不需要为了 Decode 额外包一层 Reader。
    if len(buf) > 0 {
        _, err := binary.Decode(buf, binary.LittleEndian, &header)
        return err
    }

    // 输入仍是流时交给 Read；它会自行从 reader 读取固定布局。
    if reader != nil {
        return binary.Read(reader, binary.LittleEndian, &header)
    }

    // out 代表编码目标；这里只演示 API 方向，不混用解码目标。
    _, err := binary.Encode(out, binary.LittleEndian, header)
    return err
}

上例的三个分支只是选型示意：实际项目中通常会把解码和编码拆成不同函数，避免调用方同时传入互相矛盾的输入。尤其不要把 Read 当成“自动解决网络半包”的万能函数，流的读取边界仍应由协议层设计。

字段布局和常见边界

最容易被忽略的是结构体字段并不只是“看起来像数字”。未导出字段、指针、字符串、切片等非固定大小内容会让二进制布局失去确定性；如果协议中确实存在填充字节，可以使用空白字段表达它，但要把协议布局写清楚。

type FileHeader struct {
    Magic   [4]byte
    Version uint16
    _       [2]byte // 协议预留的固定填充，不映射到业务字段。
    Length  uint32
}

func decodeFileHeader(buf []byte) (FileHeader, error) {
    var header FileHeader
    need := binary.Size(header)
    if need 

如果一条记录包含变长字符串或切片，建议先用 Decode 读取固定头，再根据长度字段切出正文，正文由业务规则单独解析。这样能避免把“固定头”和“变长内容”硬塞进一个结构体。

速查结论

• 已有完整字节切片：选择 binary.Decode，目标传指针。
• 字节序必须来自协议约定，不能按当前机器环境猜。
• 目标结构体应由固定大小字段组成；变长正文拆到下一层处理。
• 用 binary.Size 做长度预判，同时保留 n 和 err。
• 数据来自流用 Read，要生成字节用 Encode，不要为了统一 API 强行套用 Decode。

相关问题

binary.Decode 和 binary.Read 有什么区别？

Decode 面向已有的字节切片，Read 面向 io.Reader。如果数据已经在内存中，直接使用 Decode 更能表达边界；如果还要从文件或连接读取，使用 Read。

为什么 Decode 解析出来的数字很大或很小？

优先检查字节序、字段类型和切片起始位置。相同的字节按大端和小端解释会得到不同数值，切片多一字节或少一字节也会让后续字段整体错位。

结构体里能不能直接放 string？

不建议把变长 string 当作固定二进制字段交给 Decode。先读取长度和字节范围，再按协议规定的编码把正文转换成字符串。