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

用用户属性携带业务元数据

用用户属性携带业务元数据

温度上报常同时用于监控、告警和审计,而追踪编号与来源标签不一定属于业务负载。本篇用 MQTT 5 的 User Property 附加键值元数据,验证重复键的读取方式,并计算额外字节成本。

学习目标

  • 区分用户属性、主题和 Payload 的职责。
  • 用 MQTT 5 发布、接收并保留同名的多个 User Property。
  • 估算属性的字节开销,制定适合高频设备消息的使用约束。

哪些字段适合放在用户属性里

User Property 是 MQTT 5 的属性,单项由一个 UTF-8 字符串键和一个 UTF-8 字符串值组成。PUBLISH 可以携带多项,甚至允许同名键重复;它不是 JSON 对象,也不要求键唯一。

例如,温度消息的 Payload 是 {"tempC":4.1},而 trace-id=trace-001、source=sensor-07 以及两个 tag 可以放在属性区。消费者无需改动温度数据结构,就能读取与本条消息一起传递的上下文。

主题 lab/telemetry/temperature 仍决定订阅匹配;User Property 不会让标准 Broker 按 source 或 tag 自动过滤路由。不要把温度数值、设备控制参数等必需业务字段移到可被旧版客户端忽略的属性中。MQTT 3.1.1 没有 User Property,混用版本时应先确认兼容要求。

属性与负载经过 Broker 的关系

MQTT 5 PUBLISH 用户属性与负载的转发关系

MQTT 5 Broker 转发 PUBLISH 时必须保留用户属性的值和顺序。它们跟随这一条应用消息转发,不是持久保存在某个设备名下的全局元数据,也不能替代主题分层设计。

接收端应把属性按有序键值对列表读取:若直接转为普通字典,第二个 tag 会覆盖第一个,审计标签就会丢失。生产系统可约定固定字段名,例如 trace-id、source,并把可重复字段明确列为多值类型。

Python 验证透传与重复键

先启动支持 MQTT 5 的本地 Broker(示例为 127.0.0.1:1883),安装 paho-mqtt(执行 python -m pip install paho-mqtt)。将下面的程序保存为 mqtt_user_property_demo.py,执行 python mqtt_user_property_demo.py。代码先等待订阅确认,再发布带四项属性的消息。

python
import threading

import paho.mqtt.client as mqtt
from paho.mqtt.packettypes import PacketTypes
from paho.mqtt.properties import Properties

TOPIC = "lab/telemetry/temperature"
subscribed = threading.Event()
received = threading.Event()
pairs = [
    ("trace-id", "trace-001"),
    ("source", "sensor-07"),
    ("tag", "cold-chain"),
    ("tag", "critical"),
]

def on_connect(client, userdata, flags, reason_code, properties):
    if not reason_code.is_failure:
        client.subscribe(TOPIC, qos=1)

def on_subscribe(client, userdata, mid, reason_codes, properties):
    if all(not code.is_failure for code in reason_codes):
        subscribed.set()

def on_message(client, userdata, msg):
    print("收到负载:", msg.payload.decode("utf-8"))
    # 按列表读取,避免丢失重复的 tag
    for key, value in getattr(msg.properties, "UserProperty", []) or []:
        print(f"{key}={value}")
    received.set()

subscriber = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="meta-sub-demo",
    protocol=mqtt.MQTTv5,
)
subscriber.on_connect = on_connect
subscriber.on_subscribe = on_subscribe
subscriber.on_message = on_message

publisher = mqtt.Client(
    mqtt.CallbackAPIVersion.VERSION2,
    client_id="meta-pub-demo",
    protocol=mqtt.MQTTv5,
)

try:
    subscriber.connect("127.0.0.1", 1883, 60)
    subscriber.loop_start()
    # 等到 SUBACK 再发布,防止消息先于订阅到达
    if not subscribed.wait(5):
        raise TimeoutError("订阅未确认")

    publisher.connect("127.0.0.1", 1883, 60)
    publisher.loop_start()
    props = Properties(PacketTypes.PUBLISH)
    props.UserProperty = pairs
    publisher.publish(
        TOPIC, '{"tempC":4.1}', qos=1, properties=props
    ).wait_for_publish()

    if not received.wait(5):
        raise TimeoutError("消息未到达")
    # 单项属性:标识符1字节 + 两个长度字段各2字节 + 键值UTF-8字节
    overhead = sum(5 + len(k.encode("utf-8")) + len(v.encode("utf-8")) for k, v in pairs)
    print("用户属性字段字节数:", overhead)
finally:
    publisher.disconnect()
    publisher.loop_stop()
    subscriber.disconnect()
    subscriber.loop_stop()

预期输出:

text
收到负载: {"tempC":4.1}
trace-id=trace-001
source=sensor-07
tag=cold-chain
tag=critical
用户属性字段字节数: 76

运行结果中两行 tag 都应存在,且顺序与发布时相同;若没有收到消息,先确认 Broker 支持 MQTT 5、监听端口正确且订阅已得到 SUBACK。示例的本地端口是固定实验值,实际部署以 <PORT> 为准。

计算额外字节和限制使用范围

每一项 User Property 都有 1 字节属性标识符、两个各占 2 字节的字符串长度,以及键和值的 UTF-8 数据。因此一项的成本是 5 + 键字节数 + 值字节数。四项示例分别占 22、20、18、16 字节,共 76 字节;这还不包括整个属性区长度编码、主题、报文头或负载。

若设备每秒发布 1000 条同样消息,仅这些键值对就在发布端到 Broker 的链路额外增加 76,000 字节/秒;Broker 向各订阅方转发还会再次产生相应流量。汉字按 UTF-8 编码常占多字节,不能按字符个数估算。属性总量也受最大报文大小等限制影响。

实际项目可把 trace-id 与 source 设为可选标准键,为每条消息的用户属性制定例如 256 字节的团队预算,并在高频遥测中只发送必要字段。不要通过属性传递密码、访问令牌或大量 JSON:接收方日志与链路诊断可能暴露这些内容。User Property 适合轻量、非机密的业务上下文,不代替 Payload 的业务数据,也不代替请求应答中的二进制 Correlation Data。规范见 MQTT 5.0 标准。

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

目录与阅读设置

阅读设置

17

记录一个想法

用用户属性携带业务元数据

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

登录哪都通