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

读懂 MQTT 5 属性和原因码

读懂 MQTT 5 属性和原因码

MQTT 5 将可选的协议属性和用于反馈操作结果的原因码分开表达。排查设备连接、订阅拒绝或消息过期时,需要先看报文类型,再判断属性给出了什么限制、原因码指向何种结果,避免把正常反馈当成协议故障。

学习目标

  • 区分 Property 与 Reason Code 在不同报文中的位置和用途。
  • 识别常见限制属性,以及成功、拒绝和非错误原因码。
  • 用 Python 编解码属性区,并正确解读一个 MQTT 5 原因码。

先确定字段属于哪种报文

MQTT 5 的属性区由 Property Length 和一组“属性标识符+值”构成;属性是否允许出现、能否重复,取决于具体报文类型。大多数控制报文的属性在可变报头中;CONNECT 的遗嘱属性是特殊情况,位于载荷中的遗嘱字段内。

原因码不是通用的固定位置字段。CONNACK 的原因码位于可变报头;SUBACK 和 UNSUBACK 为每个过滤器返回一个原因码,列表位于载荷;PUBLISH 本身没有原因码,QoS 1 发布的处理反馈要看 PUBACK。

MQTT 5 属性区和原因码位置对照

从属性看限制和附加信息

属性 典型报文 排查时的用途
Reason String(0x1F) CONNACK、SUBACK、DISCONNECT 等 Broker 可选的人工可读诊断文字,不能作为程序分支的稳定依据
User Property(0x26) CONNECT、PUBLISH、SUBSCRIBE 等 可重复的键值对,可携带业务关联信息;含义由应用约定
Receive Maximum(0x21) CONNECT、CONNACK 限制同时未完成确认的 QoS 1/2 PUBLISH 数量,不是每秒消息数
Maximum Packet Size(0x27) CONNECT、CONNACK 接收方声明可接受的单个 MQTT 控制报文最大字节数
Session Expiry Interval(0x11) CONNECT、CONNACK、DISCONNECT 判断网络断开后会话状态可以保留多久
Message Expiry Interval(0x02) PUBLISH 表示消息可存活的秒数,过期消息不再继续转发
Content Type(0x03) PUBLISH 提示载荷格式,例如 application/json,但不保证 Broker 会验证 JSON 内容

属性不是“只要想要就能加入”的任意扩展区。例如 Reason String 可以缺失,User Property 可以出现多次,而 Content Type 不应在同一 PUBLISH 的属性区重复。收到意外属性时,先检查报文类型与 MQTT 5 规范中的允许范围。

原因码必须结合操作解释

MQTT 5 原因码为一个字节:小于 0x80 表示非失败结果,大于或等于 0x80 表示失败,但非失败不一定意味着业务目标达成。

场景 原因码 正确判断
CONNACK 0x00 连接已被接受
SUBACK 0x00 / 0x01 / 0x02 分别授予 QoS 0 / 1 / 2,不是同一个“成功”值
UNSUBACK 0x11 原本没有该订阅,不是取消失败
PUBACK、PUBREC 0x10 消息被接受,但无匹配订阅者;不等于发布失败
CONNACK、SUBACK 等支持该码的报文 0x87 Not authorized,应核对身份认证或主题权限
SUBACK、UNSUBACK 0x8F Topic Filter invalid,应核对过滤器规则

0x80 常用于未指明的错误;同一个数值必须按该报文允许的原因码集合解释。若返回了 Reason String,把它作为诊断线索并结合服务端日志,不要让业务逻辑依赖字符串是否存在或具体措辞。

本地验证属性编解码

安装 Paho 2.x:python -m pip install paho-mqtt==2.1.0。下面的完整脚本只在本地构造并反解 PUBLISH 属性区,不需要连接 Broker;随后构造标准中 CONNACK 0x87 的原因码对象,验证失败判定。它并不是伪造一条已从服务器收到的 CONNACK。

python
from paho.mqtt.packettypes import PacketTypes
from paho.mqtt.properties import Properties
from paho.mqtt.reasoncodes import ReasonCode

outgoing = Properties(PacketTypes.PUBLISH)
outgoing.PayloadFormatIndicator = 1
outgoing.ContentType = "application/json"
outgoing.UserProperty = ("source", "sensor-7")

# pack() 编码的是属性区,不包含主题名或 PUBLISH 载荷。
encoded = outgoing.pack()
incoming = Properties(PacketTypes.PUBLISH)
incoming.unpack(encoded)
print("载荷格式标记:", incoming.PayloadFormatIndicator)
print("内容类型:", incoming.ContentType)
print("用户属性:", incoming.UserProperty)

# 用规范中的拒绝码验证判断逻辑,而非模拟真实网络应答。
reason = ReasonCode(PacketTypes.CONNACK, identifier=0x87)
print(f"原因码: 0x{reason.value:02X}")
print("操作结果:", "失败" if reason.is_failure else "成功")

预期输出:

text
载荷格式标记: 1
内容类型: application/json
用户属性: [('source', 'sensor-7')]
原因码: 0x87
操作结果: 失败

在真实客户端中,应从 CONNACK、SUBACK、PUBACK 等回调或抓包获取原因码和属性,再按报文类型解释。如果订阅未生效,先查 SUBACK 是否为 0x87、0x8F 或其他失败码;如果订阅成功却没有消息,再检查实际发布主题、发布者权限及是否存在匹配订阅。这样能避免把属性缺失或“无匹配订阅者”误判成协议连接故障。需要核对完整的原因码和属性适用范围时,可查阅 OASIS MQTT 5.0 官方规范。

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

目录与阅读设置

阅读设置

17

记录一个想法

读懂 MQTT 5 属性和原因码

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

登录哪都通