单片机与物联网 / 系统课时

把解析结果转成结构化日志

把解析结果转成结构化日志

结构化日志的目标不是把收到的字节打印得更长,而是让一次 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 很适合串口联调,因为每行就是一个独立事件,既能直接阅读,也方便后续导入脚本处理。下面是一个完整记录示例,假设已经完成协议解析。

json
{"time":"2026-09-20T23:47:12.381+08:00","direction":"TX","raw":"aa04011020303a4c","address":1,"command":16,"payload":"2030","crc":"ok"}

预期结果

text
该行可作为一条独立日志事件读取;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,再结合串口驱动、线路状态和设备行为定位。结构化日志的价值就在于把排查顺序固定下来,而不是依赖肉眼翻终端输出。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

把解析结果转成结构化日志

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通