# 收到固定宽度二进制报文怎么核对：用 struct 声明字段布局并定位长度、字节序和取值越界

## 文档明确的机制

Python 标准库 `struct` 的定位很直接：在 Python 值与“按 C struct 表示的 packed binary data”之间转换。格式字符串由可选前缀和类型码组成，用来描述字节布局。面对外部系统给出的 bytes 记录，核心不是先猜字段，而是把字段表翻译成格式字符串，再用库函数核对缓冲区长度、逐条解包并捕获异常。

长度应先交给 `calcsize(format)`。文档明确：`unpack(format, buffer)` 的缓冲区字节数必须正好等于格式要求的大小；`unpack_from` 从偏移位置开始也必须至少有这么多字节；`iter_unpack(format, buffer)` 会读取等长块，直到缓冲区耗尽，因此总长度必须是单条记录大小的倍数。若一批记录等长，`iter_unpack` 可直接迭代；若长度不匹配，应先报告记录长度或整批长度问题，避免把截断字节误当字段。

字节序、大小和对齐由格式首字符决定。文档列出的前缀包括：

- `@`：native 字节序、native 大小、native 对齐；
- `=`：native 字节序、标准大小、无对齐；
- `<`：小端、标准大小、无对齐；
- `>`：大端、标准大小、无对齐；
- `!`：network，即大端、标准大小、无对齐。

没有前缀时默认是 native mode。文档也说明，native 结果依赖构建解释器的平台和编译器，打包 C struct 时可能包含用于对齐的 pad bytes；而与外部来源通信时，程序员需要负责定义元素之间的字节序和 padding。标准格式下，`<`、`>`、`=`、`!` 不自动添加 padding；需要空位时应显式使用 `x`。文档还明确，native 模式只在连续成员之间自动添加 padding，不在编码结果的开头或结尾添加。

字段类型则按类型码声明。文档的标准大小表列出：`b/B` 为 1 字节，`h/H` 为 2 字节，`i/I/l/L` 为 4 字节，`q/Q` 为 8 字节；`?` 是 1 字节布尔；`f` 为 4 字节 float，`d` 为 8 字节 double；`x` 是 pad byte；`c` 是长度为 1 的 bytes；`s` 按计数表示固定长度 bytes，例如 `10s` 是一个 10 字节字符串，而不是 10 个独立字段。整数类型在打包超出合法范围时会抛出 `struct.error`，文档示例中 `pack(">h", 99999)` 的错误信息说明 `h` 要求 `-32768 <= number <= 32767`。

## 团队自行约定的接手建议

**以下是团队接手约定，不是 `struct` 文档声称提供的产品能力。**

第一，外部交换格式与 C 本机内存布局分开维护。字段表若是网络文件或外部系统协议，优先让格式字符串显式以 `<`、`>` 或 `!` 开头；不要依赖当前机器默认值，也不要用无前缀格式碰运气。只有在与同一编译器、同一本机 ABI 相关的 C 层数据传递中，才使用 `@` 或默认 native 行为，并把平台条件写入交接说明。

第二，把“字段定义”和“业务验收”分成两层。可先用字段名、类型码、字节序、填充说明生成格式字符串，再通过 `calcsize` 得到单条记录长度；解包后按字段名组装字典。长度不满足 `unpack`、`unpack_from` 或 `iter_unpack` 条件时，归入布局错误并保留字节偏移；捕获到 `struct.error` 时，保留异常字符串与当前记录序号。对字段表中的合法取值范围，应在解包成功后另行检查，因为文档只说明整数打包超出该格式的合法范围会触发 `struct.error`，并未说明 `struct` 会校验业务枚举、状态码或跨字段关系。

第三，padding 责任要落在协议表中。标准格式需要空位时，用明确的 `x` 数量表示；不要把 native 模式自动产生的对齐当成外部协议的一部分。字段表最好同时记录每个字段的偏移和大小，方便定位“总长正确但某字段错位”的问题。

第四，批量固定宽度记录可先用总长度除以 `calcsize` 的结果检查整除，再调用 `iter_unpack`；每条记录解包后执行业务范围检查，输出字段字典、记录长度校验结果以及 `struct.error` 或越界字段清单。这里的“清单”是团队自定义输出，不表示 `struct` 会自动生成业务诊断报告。

## 边界与总结

`struct` 适合固定、扁平、可由格式字符串表达的二进制记录，但它不替代完整协议解析器。文档承诺的是按格式字符串在 Python 值和 bytes 之间转换；长度由相关函数约束，整数打包越界会触发 `struct.error`。至于业务枚举、字段间依赖和语义合法性，文档没有把它们列为 `struct` 的校验范围，仍需程序自行判断。

对于变长结构、条件分支以及超出固定布局的协议，单凭一个 `struct` 格式不能覆盖；应在外层按协议规则分段，再对确定宽度的片段使用 `unpack` 或 `unpack_from`。核对外部报文时，建议采用这个顺序：显式字节序、按字段表构造格式、用 `calcsize` 验证长度、解包并捕获 `struct.error`、最后独立检查业务取值范围。这样能把“布局错误”和“语义错误”分开，也能避免把本机对齐、当前机器端序或未声明 padding 误当作协议事实。

## 相关工具

[AI 工作流 ROI 诊断器](/demos/ai-workflow-roi-diagnostic/index.html) · 查看工具的输入要求、输出说明与适用范围。


来源：[收到固定宽度二进制报文怎么核对：用 struct 声明字段布局并定位长度、字节序和取值越界](https://docs.python.org/3/library/struct.html)
