单片机与物联网 / 系统课时
设计消息载荷和版本字段
设计消息载荷和版本字段
Topic 能告诉应用一条消息属于遥测还是命令,却不能保证载荷里的温度始终用相同字段和单位表示。这里为设备消息建立统一 JSON 信封,再用一个可运行的兼容性测试,验证设备新增字段后旧应用仍能读取原有数据,并拒绝不兼容改动。
学习目标
- 区分消息信封字段与
data中的业务字段,明确标识和时间语义。 - 为版本号制定可执行的兼容规则,识别新增字段与破坏性变更。
- 编写接收端校验示例,验证旧版消费者如何处理不同版本。
给载荷定义固定信封
以 tenants/acme/devices/motor-07/telemetry 为例,Topic 负责路由,消息正文采用 UTF-8 JSON。以下字段是应用层约定,并非 MQTT 协议自动生成的属性;发送方与接收方必须使用同一份字段契约。
| 字段 | 类型及示例 | 用途与规则 |
|---|---|---|
schemaVersion |
字符串 1.0 |
标识载荷结构版本,勿与 MQTT 3.1.1/5.0 协议版本混淆 |
messageType |
字符串 telemetry |
可约定 telemetry、state、command、response;必须与 Topic 类别一致 |
messageId |
唯一字符串 | 标识本次业务消息,便于日志追踪与重复识别 |
deviceId |
字符串 motor-07 |
与 Topic 中的设备标识一致,防止错投与冒名 |
sentAt |
UTC 时间字符串 | 使用 RFC 3339 格式,例如带 Z 的秒级时间 |
data |
JSON 对象 | 业务字段,如 temperatureC、running |
requestId |
字符串,按需出现 | 只在命令及其响应中传递同一个关联标识 |
命名时将单位写入字段名:temperatureC 是摄氏度数值,不要今天发 27.4、明天发字符串 "27.4℃"。running 应为 JSON 布尔值,而不是 "true" 字符串。对于可选字段,还要事先约定缺失表示“未提供”,null 是否允许表示“未知”。
sentAt 表示设备生成消息的时刻,不等于 Broker 接收或应用入库的时刻。设备时钟可能不准,服务器应另记接收时间,不能只凭设备时间戳判定消息先后。不要在载荷中放密码、访问令牌等敏感信息。
把版本变化写成兼容规则
这里采用项目自定义的 主版本.次版本 字符串约定。1.0 的消费者只依赖 deviceId 与 data.temperatureC 等必需字段;设备发布 1.1 时可以新增可选的 data.humidityPct,旧消费者忽略不认识的字段仍能工作。
反之,若将 temperatureC 改名为 temperatureF,或者把数值改成字符串,即使 JSON 能正常解码,旧程序也会读错或读不到。这种改动需要新主版本 2.0、明确的转换逻辑,或在升级期间同时提供旧字段。不能仅修改版本号就认为兼容。

这套主次版本是团队约定,不是 MQTT 内建的 Schema Registry。是否兼容仍取决于数据类型、必需字段、单位和消费者实现;对不支持的主版本必须明确拒绝或交给适配层处理。
用程序检验旧消费者
以下 Python 3 示例完整生成三个 JSON 载荷:1.0 只有温度、1.1 增加湿度、2.0 改变字段及单位。旧版读取函数只接收主版本 1,检查消息类别和温度类型,并忽略新增的可选字段。无需额外安装第三方库。
import json
from datetime import datetime, timezone
from uuid import uuid4
def make_message(version: str, data: dict) -> str:
packet = {
"schemaVersion": version,
"messageType": "telemetry",
"messageId": str(uuid4()),
"deviceId": "motor-07",
"sentAt": datetime.now(timezone.utc).isoformat(
timespec="seconds"
).replace("+00:00", "Z"),
"data": data,
}
# 防止 NaN、Infinity 混入非标准 JSON
return json.dumps(packet, ensure_ascii=False, allow_nan=False)
def read_v1(raw: str) -> str:
packet = json.loads(raw)
if packet.get("messageType") != "telemetry":
raise ValueError("消息类型不匹配")
version = packet.get("schemaVersion")
parts = version.split(".") if isinstance(version, str) else []
if len(parts) != 2 or parts[0] != "1" or not parts[1].isdigit():
raise ValueError("不兼容的主版本")
data = packet.get("data")
if not isinstance(data, dict):
raise ValueError("data 缺失")
temperature = data.get("temperatureC")
# bool 在 Python 中属于 int 的子类,需要单独排除
if isinstance(temperature, bool) or not isinstance(
temperature, (int, float)
):
raise ValueError("温度字段无效")
return f"{packet['deviceId']} 温度 {temperature:.1f}°C"
if __name__ == "__main__":
samples = [
("1.0", {"temperatureC": 27.4}),
("1.1", {"temperatureC": 27.4, "humidityPct": 46}),
("2.0", {"temperatureF": 81.3}),
]
for version, data in samples:
try:
result = read_v1(make_message(version, data))
print(f"v{version}:{result}")
except ValueError as exc:
print(f"v{version}:拒绝({exc})")预期输出:
v1.0:motor-07 温度 27.4°C
v1.1:motor-07 温度 27.4°C
v2.0:拒绝(不兼容的主版本)messageId 与 sentAt 在每次运行时动态生成,实际值分别相当于 <ID>、<TIME>;示例只打印稳定的校验结论。将 1.1 的 temperatureC 改成字符串后再运行,读取端应报告“温度字段无效”,而不是默默将错误类型写入数据库。
明确异常处理和请求关联
接入真实 Broker 后,消费者应先按 Topic 校验设备来源,再解析 JSON,检查必填字段、版本、类型、范围和时间格式。解析失败的消息需记录设备、messageId、错误原因及接收时间,并进入隔离或重试策略;不能把无效温度当成零值。
对命令与响应,requestId 标识同一个业务请求,而 messageId 标识单条消息。应用重试 set-rate 命令时应保持 requestId 不变,设备按该编号避免重复执行;响应再回传此编号和明确的执行状态。accepted 只能表示已接收,不能冒充 applied 已完成。
正式上线前用 1.0、新增可选字段的 1.1、不兼容的 2.0、缺字段、错类型五组载荷做回归测试。只要旧端能稳定读取所有合法的 1.x 消息,并明确拒绝它无法理解的字段语义变更,版本策略才真正生效。