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

拆解 MQTT 报文基本结构

拆解 MQTT 报文基本结构

抓到 MQTT 二进制数据时,只有明确报头边界,才能判断消息类型、报文长度与实际内容。本课以 MQTT 3.1.1 的一条 QoS 0 PUBLISH 报文为例,从十六进制字节中定位固定报头、可变报头与载荷,再用 Python 程序验证解析结果。

学习目标

  • 识别 MQTT 控制报文的固定报头、可变报头与载荷。
  • 理解控制报文类型、标志位和剩余长度字段的编码含义。
  • 根据实际字节序列还原一条 PUBLISH 消息,并检查报文长度是否正确。

识别报文边界与三个组成部分

MQTT 在 TCP 连接上传输控制报文。不同控制报文承担不同职责,例如 CONNECT 建立连接,PUBLISH 传输应用消息,SUBSCRIBE 建立订阅,PINGREQ 发送心跳请求。

在 MQTT 3.1.1 中,一条控制报文由以下部分构成:

区域 内容 是否必有
固定报头 报文类型、标志位、剩余长度 是
可变报头 主题名、报文标识符等协议字段 取决于报文类型
载荷 应用消息或连接参数等数据 取决于报文类型

固定报头的第一个字节,高四位表示控制报文类型,低四位表示与该类型相关的标志位。对于 PUBLISH,低四位分别涉及 DUP、QoS 和 RETAIN;其他报文类型可能要求固定的标志位组合。

固定报头还包含 Remaining Length(剩余长度)字段,采用 1~4 字节的变长编码。它表示剩余的可变报头与载荷总字节数,不包括第一个固定报头字节,也不包括 Remaining Length 字段自身占用的字节。

MQTT 控制报文区域划分与 PUBLISH 逐字节拆解

不是每条 MQTT 报文都有可变报头与载荷。例如,MQTT 3.1.1 的 PINGREQ 完整报文可以只有 C0 00 两个字节:C0 表示类型和标志位,00 表示后续没有内容。

逐字节还原一条 PUBLISH

现在分析一条已经完整接收的 MQTT 3.1.1 QoS 0 PUBLISH 报文。它的主题为 a/b,载荷为字符串 hi,DUP 与 RETAIN 均为 0。

报文原始字节如下,使用十六进制表示:

text
30 07 00 03 61 2F 62 68 69

按字节位置解析:

  1. 30:高四位为 0011,即控制报文类型 3,表示 PUBLISH;低四位为 0000,表示 DUP=0、QoS=0、RETAIN=0。
  2. 07:剩余长度为 7 字节。本例小于 128,因此 Remaining Length 只占一个字节。
  3. 00 03:主题名的 UTF-8 编码长度为 3 字节。这是一个两字节无符号大端整数。
  4. 61 2F 62:三个 UTF-8 字节分别表示 a、/、b,还原主题名称 a/b。
  5. 68 69:两个字节对应字符 h 和 i,还原应用载荷 hi。

此时可以核对长度:主题长度字段占 2 字节,主题名称占 3 字节,载荷占 2 字节,合计 7 字节。再加上首字节与剩余长度字段各 1 字节,整条报文实际长度为 9 字节。

由于本例 QoS 为 0,可变报头中没有 Packet Identifier(报文标识符)。如果改成 QoS 1 或 QoS 2 的 PUBLISH,可变报头还需要包含两字节 Packet Identifier,不能继续使用当前的固定偏移直接读取载荷。

使用 Python 校验偏移与长度

下面用 Python 3 编写一个完整的最小解析程序。程序支持按 MQTT 的变长整数规则读取 Remaining Length,但后续字段解析限定为 MQTT 3.1.1 的 QoS 0、DUP=0、RETAIN=0 的 PUBLISH 示例。

python
# 已完整接收的 MQTT 3.1.1 QoS 0 PUBLISH 报文
packet = bytes.fromhex("30 07 00 03 61 2F 62 68 69")

# Remaining Length 采用最多四字节的七位分组编码
remaining = 0
multiplier = 1
offset = 1
for _ in range(4):
    encoded = packet[offset]
    offset += 1
    remaining += (encoded & 0x7F) * multiplier
    if (encoded & 0x80) == 0:
        break
    multiplier *= 128
else:
    raise ValueError("Remaining Length 超过四字节")

if len(packet) - offset != remaining:
    raise ValueError("剩余长度与实际字节数不一致")

packet_type = packet[0] >> 4
flags = packet[0] & 0x0F
if packet_type != 3 or flags != 0:
    raise ValueError("此示例只解析指定标志位的 PUBLISH")

# 主题名以两字节大端长度开头,长度单位是字节
 topic_len = 0

上面代码末行应替换为以下完整的主题与载荷解析部分,再运行整个程序:

python
topic_len = int.from_bytes(packet[offset:offset + 2], "big")
topic_start = offset + 2
topic_end = topic_start + topic_len

topic = packet[topic_start:topic_end].decode("utf-8")
payload = packet[topic_end:].decode("utf-8")

print(f"type=PUBLISH flags={flags} remaining={remaining}")
print(f"topic={topic} payload={payload}")
print(f"total_bytes={len(packet)}")

预期输出:

text
type=PUBLISH flags=0 remaining=7
topic=a/b payload=hi
total_bytes=9

程序利用 offset 记录已经读取的位置。读取 Remaining Length 后,offset 指向可变报头的起点;主题名占用的字节数由两字节长度字段决定,而不是通过查找 / 或其他分隔符推断。

示例中 hi 恰好是合法 UTF-8 文本,因此可以直接解码。真实设备消息也可能是二进制编码、压缩数据或自定义协议格式,解析器不能假定所有载荷都能转成 UTF-8 字符串。

防止长度与协议版本误判

Remaining Length 最容易出现的错误,是把它误认为一个固定的一字节整数。MQTT 使用每字节七个有效数据位的变长编码:

剩余长度数值 编码字节 字节数
0 00 1
127 7F 1
128 80 01 2
16384 80 80 01 3

每个编码字节的最高位表示后面是否还有长度字节。例如 80 01 的第一个字节最高位为 1,表示继续读取;第二个字节最高位为 0,表示结束。MQTT 3.1.1 的 Remaining Length 最多使用四字节,最大表示 268435455。

解析实际网络数据时还要检查几个条件:

  • TCP 是字节流协议,一次读取不一定得到完整 MQTT 报文。必须先读取完整固定报头,再根据 Remaining Length 收齐后续字节。
  • PUBLISH 的可变报头长度受 QoS 影响。QoS 1 和 QoS 2 包含 Packet Identifier,QoS 0 不包含。
  • MQTT 5.0 在相关报文中引入属性字段,不能不加区分地沿用 MQTT 3.1.1 的全部字段偏移。
  • Remaining Length 描述的是字节数,不是字符数。含有中文字符的主题名必须按 UTF-8 编码后的实际字节长度计算。

可以尝试将示例载荷由 hi 改为 hello,重新计算 Remaining Length,并同步修改十六进制数据。正确结果应为剩余长度 10、完整报文长度 12。这个练习可以验证自己是否真正理解了报头长度与消息内容的关系。

排查 MQTT 报文时,建议按照控制报文类型、剩余长度、可变报头字段、载荷的顺序阅读,并结合 OASIS MQTT 3.1.1 标准 核对对应报文的字段定义。

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

目录与阅读设置

阅读设置

17

记录一个想法

拆解 MQTT 报文基本结构

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

登录哪都通