单片机与物联网 / 系统课时
把解析结果转成结构化日志
把解析结果转成结构化日志
结构化日志的目标不是把收到的字节打印得更长,而是让一次 TX/RX 通信可以被机器检索、人工复盘和自动比对。固定时间、方向、原始帧与解析字段后,同一类协议问题才能稳定复现。
学习目标
- 能设计统一的 TX/RX 日志字段
- 能同时保留原始帧和结构化解析结果
- 能根据日志判断地址、命令、负载和 CRC 是否一致
日志至少保留两层信息
串口问题排查时,结构化字段非常方便,但它不能替代原始字节。推荐同时记录“原始事实”和“解析结论”:原始事实用于重新解码,解析结论用于快速筛选。
常用字段包括时间、方向、原始帧、地址、命令、负载、CRC 结果。还可以加入串口标识、波特率或请求关联 ID,但字段应保持稳定,不要每条日志临时增减。
| 字段 | 作用 | 示例 |
|---|---|---|
time |
关联请求与响应时间顺序 | 2026-09-20T23:47:12.381+08:00 |
direction |
区分发送和接收 | TX / RX |
raw |
保留完整原始帧 | aa04011020303a4c |
address |
记录目标或来源地址 | 1 |
command |
快速筛选协议命令 | 16 |
payload |
记录解析后的负载 | 2030 |
crc |
记录校验判断 | ok |
让日志格式固定
JSON Lines 很适合串口联调,因为每行就是一个独立事件,既能直接阅读,也方便后续导入脚本处理。下面是一个完整记录示例,假设已经完成协议解析。
{"time":"2026-09-20T23:47:12.381+08:00","direction":"TX","raw":"aa04011020303a4c","address":1,"command":16,"payload":"2030","crc":"ok"}预期结果
该行可作为一条独立日志事件读取;direction 为 TX,address 为 1,command 为 16,payload 为 2030,crc 为 ok。实际记录程序应在得到完整帧后一次性写出日志,而不是先打印十六进制、再打印地址、最后单独打印 CRC。分散输出会让多线程或高频串口场景中的事件难以重新对应。
原始帧和解析结果必须可互相验证
例如日志写出 address=1、command=16、payload=2030,就应能从 raw 中找到相同字节。这样解析器升级后,可以直接拿历史 raw 重新执行解析,而不用依赖旧日志里的字段。
CRC 建议至少区分 ok、failed 和 not_checked。不要把校验失败简单写成一个布尔值后丢掉实际状态,因为排障时需要知道到底是校验失败,还是当前工具没有执行校验。
避免日志反而制造噪声
时间戳应统一时区或统一记录偏移量,并保证精度足以区分连续帧。方向字段只使用固定枚举值,例如 TX 和 RX,不要同时出现 send、out、write 等多个别名。
另外,不要默认把所有设备原始负载都当成文本。二进制负载应保持十六进制表示,必要时再增加经过业务解释的字段。这样即使负载中包含 00、不可打印字节或控制字符,也不会破坏日志格式。
用日志复现一次通信问题
发生“设备偶发不响应”时,先按时间找到对应的 TX 记录,再确认是否存在紧邻的 RX。如果有 RX,继续比较地址、命令、长度和 CRC;如果只有 TX,再结合串口驱动、线路状态和设备行为定位。结构化日志的价值就在于把排查顺序固定下来,而不是依赖肉眼翻终端输出。