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

设计消息载荷和版本字段

设计消息载荷和版本字段

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 设备载荷版本的兼容与拒绝关系

这套主次版本是团队约定,不是 MQTT 内建的 Schema Registry。是否兼容仍取决于数据类型、必需字段、单位和消费者实现;对不支持的主版本必须明确拒绝或交给适配层处理。

用程序检验旧消费者

以下 Python 3 示例完整生成三个 JSON 载荷:1.0 只有温度、1.1 增加湿度、2.0 改变字段及单位。旧版读取函数只接收主版本 1,检查消息类别和温度类型,并忽略新增的可选字段。无需额外安装第三方库。

python
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})")

预期输出:

text
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 消息,并明确拒绝它无法理解的字段语义变更,版本策略才真正生效。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计消息载荷和版本字段

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

登录哪都通