首页/网络/工控与物联网速查/MQTT主题命名与层级规划方法
物联网协议60 条

MQTT主题命名与层级规划方法

MQTT 主题是按斜杠分层的 UTF-8 字符串,设计要点是层级稳定、能被通配符自然切分、且不把易变信息塞进层级。主题一旦上线即等同于接口契约,改名的代价由所有订阅方共同承担。

工控与物联网速查网络更新于 2026-10-17
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌​​‌​‌‌‌‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌‌​‌‌​‌‌​‌​‌‌‌​​​‌​‌‌‌​‌​​​‌‌‌​‌​​​​‌​‌‌​‌​‌‌‌​‌​​​‌‌​‌‌‌‌​‌‌‌​​​​​‌‌​‌​​‌​‌‌​​​‌‌​​‌​‌‌​‌​‌‌​​‌​​​‌‌​​‌​‌​‌‌‌​​‌‌​‌‌​‌​​‌​‌‌​​‌‌‌​‌‌​‌‌‌​​​‌​‌‌​‌​‌‌‌​​​​​‌‌‌​​‌​​‌‌​‌​​‌​‌‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌​​‌​‌‌‌​​​​​‌‌​‌‌​​​‌‌​​‌​‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌​‌​​​​‌‌‌​‌​​​‌‌​‌‌​‌​‌‌​‌‌​​

主题即接口

主题区分大小写,连续斜杠会产生空层级,以斜杠开头会多出一个无名的前导层级,一般不建议。好的主题设计让订阅方可以用单层通配符和多层通配符按维度切片,例如按站点订阅或按设备类型订阅;同时每个层级的内容保持稳定,设备改名或位置调整不会改变主题结构。

推荐的结构

推荐的结构
# 层级:企业 / 站点 / 设备类型 / 设备编号 / 数据类别
# 遥测:acme/shanghai/plc/line1-03/telemetry
# 状态:acme/shanghai/plc/line1-03/status
# 指令:acme/shanghai/plc/line1-03/cmd
# 订阅:acme/shanghai/plc/+/telemetry 收全厂遥测
# 避免:把时间戳、坐标或随机串放进层级

层级设计对照

做法示例评价
维度固定、值可变site/device-type/device-id/data推荐,通配符可按维度切片
时间戳放载荷主题固定,载荷内含时间字段推荐,便于判断数据新鲜度
时间放进主题device/20261017/telemetry不推荐,主题数量随时间无限膨胀
以斜杠开头/acme/device/data不推荐,产生空的前导层级
层级堆叠属性device/id/type/room/floor/...不推荐,位置调整就会破坏订阅

典型使用场景

  • 平台侧聚合:按站点或设备类型用通配符订阅,新增设备无需修改平台配置
  • 权限隔离:以主题前缀作为授权边界,设备只能写入自己的前缀
  • 数据分区:按主题前缀把消息路由到不同的存储或计算管道
  • 多租户:以租户标识作为最高层级,天然隔离不同客户的数据
主题数量与订阅关系数量都会消耗服务端内存。主题设计得过于细碎会明显抬高代理的资源占用,需要在业务维度与资源开销之间权衡。
主题改名的连锁代价很大:订阅方、权限规则、路由规则都要同步修改。命名规范应在设计阶段写成文档并做评审。

易错点

  • 把时间戳或会话标识放进主题层级:主题数量爆炸,服务端订阅树与存储压力骤增
  • 主题以斜杠开头或含空层级:不同客户端匹配行为不一致,埋下隐患
  • 主题层级跟随物理位置变化:设备搬迁就要重新配置所有订阅方
  • 命名没有规范就直接上线:后期只能靠加通配符补救,权限隔离也无从实现
  • 同一层级里混用英文与中文或其他分隔符:过滤器匹配结果与预期不一致,排查成本很高

数据来源与参考

  • OASIS MQTT Version 5.0 规范(主题与主题过滤器章节)
  • MQTT 官方站点主题设计入门文档

整理校对:其其网ICT文档中心 · 本页地址:docs.qiqicto.com/ics/mqtt-topic-design-principles.html

​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌​​‌​‌‌‌‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌‌​‌‌​‌‌​‌​‌‌‌​​​‌​‌‌‌​‌​​​‌‌‌​‌​​​​‌​‌‌​‌​‌‌‌​‌​​​‌‌​‌‌‌‌​‌‌‌​​​​​‌‌​‌​​‌​‌‌​​​‌‌​​‌​‌‌​‌​‌‌​​‌​​​‌‌​​‌​‌​‌‌‌​​‌‌​‌‌​‌​​‌​‌‌​​‌‌‌​‌‌​‌‌‌​​​‌​‌‌​‌​‌‌‌​​​​​‌‌‌​​‌​​‌‌​‌​​‌​‌‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌​​‌​‌‌‌​​​​​‌‌​‌‌​​​‌‌​​‌​‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌​‌​​​​‌‌‌​‌​​​‌‌​‌‌​‌​‌‌​‌‌​​