单片机与物联网 / 系统课时
用用户属性携带业务元数据
用用户属性携带业务元数据
温度上报常同时用于监控、告警和审计,而追踪编号与来源标签不一定属于业务负载。本篇用 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 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。代码先等待订阅确认,再发布带四项属性的消息。
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()预期输出:
收到负载: {"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 标准。