单片机与物联网 / 系统课时
读懂 MQTT 5 属性和原因码
读懂 MQTT 5 属性和原因码
MQTT 5 将可选的协议属性和用于反馈操作结果的原因码分开表达。排查设备连接、订阅拒绝或消息过期时,需要先看报文类型,再判断属性给出了什么限制、原因码指向何种结果,避免把正常反馈当成协议故障。
学习目标
- 区分 Property 与 Reason Code 在不同报文中的位置和用途。
- 识别常见限制属性,以及成功、拒绝和非错误原因码。
- 用 Python 编解码属性区,并正确解读一个 MQTT 5 原因码。
先确定字段属于哪种报文
MQTT 5 的属性区由 Property Length 和一组“属性标识符+值”构成;属性是否允许出现、能否重复,取决于具体报文类型。大多数控制报文的属性在可变报头中;CONNECT 的遗嘱属性是特殊情况,位于载荷中的遗嘱字段内。
原因码不是通用的固定位置字段。CONNACK 的原因码位于可变报头;SUBACK 和 UNSUBACK 为每个过滤器返回一个原因码,列表位于载荷;PUBLISH 本身没有原因码,QoS 1 发布的处理反馈要看 PUBACK。

从属性看限制和附加信息
| 属性 | 典型报文 | 排查时的用途 |
|---|---|---|
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。
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 "成功")预期输出:
载荷格式标记: 1
内容类型: application/json
用户属性: [('source', 'sensor-7')]
原因码: 0x87
操作结果: 失败在真实客户端中,应从 CONNACK、SUBACK、PUBACK 等回调或抓包获取原因码和属性,再按报文类型解释。如果订阅未生效,先查 SUBACK 是否为 0x87、0x8F 或其他失败码;如果订阅成功却没有消息,再检查实际发布主题、发布者权限及是否存在匹配订阅。这样能避免把属性缺失或“无匹配订阅者”误判成协议连接故障。需要核对完整的原因码和属性适用范围时,可查阅 OASIS MQTT 5.0 官方规范。