Python struct.iter_unpack怎样连续解析定长二进制记录

我第一次把一段设备导出的二进制日志交给 Python 解析时，最容易写出的代码是循环调用 struct.unpack。它能读一条记录，但当输入变成几十万条定长记录时，偏移量、切片长度和尾部残片很快就混在一起。这个场景更适合 struct.iter_unpack(format, buffer)：先定义一条记录的格式，再让迭代器按同样的大小连续产出元组。

官方地址：https://docs.python.org/3/library/struct.html#struct.iter_unpack

最关键的判断只有一个：len(buffer) 必须是 struct.calcsize(format) 的整数倍。不是整数倍时，先处理上游分帧或残片，不要把错误推给解析循环。

先把记录格式和边界定清楚

struct 用格式字符串描述字节顺序、字段类型和字段大小。比如 >Hf 表示大端字节序、一个无符号短整数和一个 4 字节浮点数，整条记录大小是 6 字节。对于文件或网络协议，建议显式写出 >、 或 =，不要依赖没有前缀时的本机对齐规则。

用 iter_unpack 连续读取多条记录

下面把三条记录拼在同一个 bytes 缓冲区中。代码先用 calcsize 得到单条记录大小，再在创建迭代器前确认输入完整，最后把元组转换成更容易交给业务层的字典。

import struct

RECORD_FORMAT = ">Hf"  # 明确使用大端：编号为 2 字节，数值为 4 字节
RECORD_SIZE = struct.calcsize(RECORD_FORMAT)  # 计算一条记录的固定长度

payload = b"".join([
    struct.pack(RECORD_FORMAT, 101, 21.5),  # 第一条记录
    struct.pack(RECORD_FORMAT, 102, 22.0),  # 第二条记录
    struct.pack(RECORD_FORMAT, 103, 22.75),  # 第三条记录
])

if len(payload) % RECORD_SIZE != 0:
    # 先拒绝不完整缓冲区，避免把尾部残片交给迭代器。
    raise ValueError("输入长度不是完整记录的整数倍")

records = [
    {"sensor_id": sensor_id, "value": value}
    for sensor_id, value in struct.iter_unpack(RECORD_FORMAT, payload)
]

print(records)

这里的返回值仍然是元组，只是列表推导把字段命名了。iter_unpack 本身不会替你补齐数据，也不会猜测字节序；格式字符串就是解析契约，生产者和消费者必须共享同一份约定。

把单条 unpack 和连续 iter_unpack 分开

如果只收到一条完整记录，struct.unpack 更直观；如果是连续的等长记录，iter_unpack 能把偏移推进交给迭代器。两者都要求输入满足格式大小，只是返回形态不同。

处理尾部不完整数据和 struct.error

文件读取和网络读取经常会遇到“前面是完整记录，最后只到了一半”的情况。此时不要直接捕获异常然后丢掉全部结果，更稳妥的做法是先把完整前缀交给 iter_unpack，把余数保存为下一次读取的前缀。

import struct

FORMAT = "

这段逻辑适合处理“记录本身固定长度，但读取动作可能被截断”的输入。若协议是变长帧，则应先根据帧头中的长度字段组装出一帧完整数据，之后再选择 unpack 或 iter_unpack，不要把变长边界硬套成固定记录。

几个容易忽略的工程边界

• 字节序要写进格式。没有前缀时是 native 模式，可能带来本机字节序和对齐差异；跨机器或跨语言交换时应使用明确的标准格式。
• 记录大小由格式决定。先调用 calcsize，不要根据字段数量猜字节数；尤其要留意标准模式与 native 模式的填充差异。
• 输入可以是支持缓冲区协议的对象。bytes、bytearray 等都可以作为缓冲区，但仍要保证内容和格式匹配。
• 迭代器不会验证业务范围。解析出整数不代表它就是合法的传感器编号；字段范围、校验和、版本号仍由协议层负责。

常见问题

为什么 iter_unpack 报缓冲区长度必须是倍数？

因为它只能按固定的 calcsize(format) 切出完整块，剩余字节无法组成一条记录。应先保存残片并等待后续数据，或确认文件确实被截断。

能不能用 iter_unpack 读取变长记录？

不能直接用。它的每次迭代大小固定；变长协议应先解析长度字段、切出完整帧，再对帧内固定区域使用对应格式解析。

为什么同一格式在不同机器上大小不同？

通常是使用了 native 模式，平台的字节序、C 类型大小或对齐规则参与了布局。需要稳定交换格式时，使用 、> 或 = 明确约定。

总结

• struct.iter_unpack 适合按固定格式连续读取定长二进制记录。
• 先用 calcsize 确认记录大小，再检查缓冲区长度是否为整数倍。
• 跨设备数据要显式指定字节序；尾部残片应保留、补齐或等待，不要静默丢弃。