MQTT主题设计规范智慧农业设备分层Topic设计设备/大棚/分组Topic 设计是 MQTT 项目中最容易被忽视、却影响最深远的架构决策。改 Topic 结构等于推翻重来——设备端、服务端、前端全得跟着改。本文聊聊怎么设计一套不后悔的 Topic 体系。一、为什么Topic需要设计规范先看一个真实的反面案例。某农业项目初期十几个传感器随意起了 Topictemp1、greenhouse/humidity、farm_data/soil、sensor_001/data。设备少的时候还能管理后来扩到 500 个设备问题全来了无法批量订阅Topic 没有层级规律想监控所有温度传感器做不到。通配符订阅失控有人用#订阅了全部消息导致每条消息都推一份给他流量爆炸。命名冲突两个开发者各自起名pump/status到底是1号泵还是2号泵没人说得清。权限无法控制Topic 无规律ACL访问控制列表没法按层级授权。结论没有规范的 Topic 灾难的开始。Topic 设计应该在项目第一天就定好规范所有开发者共同遵守。二、Topic设计基本原则2.1 层级清晰用/分隔MQTT Topic 用/作为层级分隔符类似文件系统路径。每一层代表一个维度的分类。farm/greenhouse03/sensor/temperature从左到右范围从大到小农场 → 大棚 → 设备类型 → 数据类型。2.2 命名规范小写字母 下划线greenhouse_03不用GreenHouse03或green-house-03不用空格和特殊字符空格、中文、#、都是禁忌#和是通配符保留字见名知意temp不如temperaturedev不如device2.3 避免开头使用/# ❌ 不推荐 /agriculture/farm01/sensor/temperature # ✅ 推荐 agriculture/farm01/sensor/temperature以/开头会在第一层产生一个空层虽然 MQTT 5.0 允许但在某些客户端和 Broker 上可能引发兼容性问题调试时也容易混淆。2.4 Topic 不宜过深建议不超过 5 层。层数太多不仅可读性差通配符订阅时也容易出错。# ❌ 太深了 agriculture/farm01/zone03/greenhouse02/area05/sensor/temperature/dht22/value # ✅ 刚好 agriculture/farm01/greenhouse02/sensor/temperature三、智慧农业Topic体系设计下面是一套经过实践验证的 Topic 分层方案3.1 层级定义层级含义示例第1层业务域agriculture第2层农场编号farm01第3层大棚编号greenhouse03第4层设备类型sensor/controller/camera第5层数据子类temperature/status/command3.2 完整示例上行数据设备 → 服务器# 温度传感器上报 agriculture/farm01/greenhouse03/sensor/temperature # 土壤湿度传感器上报 agriculture/farm01/greenhouse03/sensor/soil_moisture # 水肥泵状态上报 agriculture/farm01/greenhouse03/controller/pump01/status下行指令服务器 → 设备# 控制水肥泵启停 agriculture/farm01/greenhouse03/controller/pump01/command # 控制卷帘机 agriculture/farm01/greenhouse03/controller/curtain01/command设备状态上报# 设备在线/离线/故障 agriculture/farm01/greenhouse03/controller/pump01/status3.3 上行/下行分离设计在更复杂的场景中可以在设备类型前增加方向层明确区分上下行# 上报类 agriculture/${farm}/${greenhouse}/up/${device_type}/${data_type} # 指令类 agriculture/${farm}/${greenhouse}/down/${device_type}/${command}这样做的好处是权限控制更清晰——设备只能 publish 到up/只能 subscribedown/服务端反之。ACL 规则一条就能搞定。四、通配符订阅策略MQTT 通配符是 Topic 设计的灵魂用好通配符能极大简化订阅逻辑。4.1 两种通配符通配符含义示例匹配单层sensor//temperature匹配sensor/a/temperature不匹配sensor/a/b/temperature#匹配多层只能放在末尾sensor/#匹配sensor/a/temperature和sensor/a/b/c4.2 智慧农业通配符实战监控所有农场的温度传感器agriculture///sensor/temperature一个订阅就能收到所有大棚的温度数据不用逐个订阅。监控某个大棚的一切数据agriculture/farm01/greenhouse03/#调试单个大棚时特别有用。监控所有控制器的状态agriculture///controller//status运维大盘只关心设备状态不关心传感器数据用这条订阅即可。4.3 通配符使用注意#必须独占最后一层不能写成sensor/#/temp$SYS/开头的系统 Topic 不受通配符匹配详见下文谨慎使用#订阅全部消息——在大规模场景下会造成性能问题五、系统类TopicEMQX 等 Broker 内置了系统级 Topic以$SYS/开头用于获取 Broker 自身运行状态$SYS/broker/version # Broker 版本号 $SYS/broker/uptime # 运行时间 $SYS/broker/clients/connected # 当前连接数 $SYS/broker/messages/received # 累计接收消息数注意$SYS不以/开头且$开头的 Topic不会被通配符匹配。也就是说#不会匹配到$SYS/#这是协议设计的保护机制防止系统消息意外泄露给业务订阅者。六、Topic数量评估设计 Topic 时要估算总量确保 Broker 能扛住。以一个中型农场为例类型数量计算Topic 数传感器数据10个大棚 × 10种传感器100控制器指令10个大棚 × 5个控制器50设备状态150个设备 × 1150系统TopicBroker 内置~20合计~320EMQX 单节点轻松处理数十万 Topic320 个完全不在话下。即使是大型基地上万设备Topic 数也就几万个毫无压力。真正需要关注的不是 Topic 数量而是消息吞吐速率和订阅关系数量。每个订阅关系会占用内存大规模场景下需要关注 Dashboard 中的订阅数指标。七、Topic注册与管理7.1 是否需要Topic白名单小规模项目500设备不需要。Topic 规范靠团队约定和代码审查保证即可。中大规模项目500设备建议引入 Topic 白名单。EMQX 支持 ACL 规则配置限定设备只能 publish/subscribe 特定模式的 Topic# EMQX ACL 配置示例-permission:allowaction:publishtopic:agriculture/farm01//sensor/-permission:allowaction:subscribetopic:agriculture/farm01//controller//command这样即使设备被篡改也无法向非法 Topic 发送消息。7.2 Topic命名文档化强烈建议在项目初期建立 Topic 字典文档类似 API 文档Topic方向Payload格式发布者订阅者说明agriculture/{farm}/{gh}/sensor/temperature上行{temp: 25.3, ts: 1704067200}传感器数据服务温度上报agriculture/{farm}/{gh}/controller/pump/command下行{action:start,speed:80}控制服务控制器泵控制指令有了这份文档前后端、设备端开发者一目了然不用猜 Topic 含义。总结Topic 设计的核心就一句话像设计数据库表结构一样设计 Topic。想清楚层级、命名、通配符需求和权限边界一次定稿全程受用。千万不要先随便起个名后面再改——后面改的代价远超你想象。
MQTT主题设计规范智慧农业设备分层Topic设计设备/大棚/分组Topic 设计是 MQTT 项目中最容易被忽视、却影响最深远的架构决策。改 Topic 结构等于推翻重来——设备端、服务端、前端全得跟着改。本文聊聊怎么设计一套不后悔的 Topic 体系。一、为什么Topic需要设计规范先看一个真实的反面案例。某农业项目初期十几个传感器随意起了 Topictemp1、greenhouse/humidity、farm_data/soil、sensor_001/data。设备少的时候还能管理后来扩到 500 个设备问题全来了无法批量订阅Topic 没有层级规律想监控所有温度传感器做不到。通配符订阅失控有人用#订阅了全部消息导致每条消息都推一份给他流量爆炸。命名冲突两个开发者各自起名pump/status到底是1号泵还是2号泵没人说得清。权限无法控制Topic 无规律ACL访问控制列表没法按层级授权。结论没有规范的 Topic 灾难的开始。Topic 设计应该在项目第一天就定好规范所有开发者共同遵守。二、Topic设计基本原则2.1 层级清晰用/分隔MQTT Topic 用/作为层级分隔符类似文件系统路径。每一层代表一个维度的分类。farm/greenhouse03/sensor/temperature从左到右范围从大到小农场 → 大棚 → 设备类型 → 数据类型。2.2 命名规范小写字母 下划线greenhouse_03不用GreenHouse03或green-house-03不用空格和特殊字符空格、中文、#、都是禁忌#和是通配符保留字见名知意temp不如temperaturedev不如device2.3 避免开头使用/# ❌ 不推荐 /agriculture/farm01/sensor/temperature # ✅ 推荐 agriculture/farm01/sensor/temperature以/开头会在第一层产生一个空层虽然 MQTT 5.0 允许但在某些客户端和 Broker 上可能引发兼容性问题调试时也容易混淆。2.4 Topic 不宜过深建议不超过 5 层。层数太多不仅可读性差通配符订阅时也容易出错。# ❌ 太深了 agriculture/farm01/zone03/greenhouse02/area05/sensor/temperature/dht22/value # ✅ 刚好 agriculture/farm01/greenhouse02/sensor/temperature三、智慧农业Topic体系设计下面是一套经过实践验证的 Topic 分层方案3.1 层级定义层级含义示例第1层业务域agriculture第2层农场编号farm01第3层大棚编号greenhouse03第4层设备类型sensor/controller/camera第5层数据子类temperature/status/command3.2 完整示例上行数据设备 → 服务器# 温度传感器上报 agriculture/farm01/greenhouse03/sensor/temperature # 土壤湿度传感器上报 agriculture/farm01/greenhouse03/sensor/soil_moisture # 水肥泵状态上报 agriculture/farm01/greenhouse03/controller/pump01/status下行指令服务器 → 设备# 控制水肥泵启停 agriculture/farm01/greenhouse03/controller/pump01/command # 控制卷帘机 agriculture/farm01/greenhouse03/controller/curtain01/command设备状态上报# 设备在线/离线/故障 agriculture/farm01/greenhouse03/controller/pump01/status3.3 上行/下行分离设计在更复杂的场景中可以在设备类型前增加方向层明确区分上下行# 上报类 agriculture/${farm}/${greenhouse}/up/${device_type}/${data_type} # 指令类 agriculture/${farm}/${greenhouse}/down/${device_type}/${command}这样做的好处是权限控制更清晰——设备只能 publish 到up/只能 subscribedown/服务端反之。ACL 规则一条就能搞定。四、通配符订阅策略MQTT 通配符是 Topic 设计的灵魂用好通配符能极大简化订阅逻辑。4.1 两种通配符通配符含义示例匹配单层sensor//temperature匹配sensor/a/temperature不匹配sensor/a/b/temperature#匹配多层只能放在末尾sensor/#匹配sensor/a/temperature和sensor/a/b/c4.2 智慧农业通配符实战监控所有农场的温度传感器agriculture///sensor/temperature一个订阅就能收到所有大棚的温度数据不用逐个订阅。监控某个大棚的一切数据agriculture/farm01/greenhouse03/#调试单个大棚时特别有用。监控所有控制器的状态agriculture///controller//status运维大盘只关心设备状态不关心传感器数据用这条订阅即可。4.3 通配符使用注意#必须独占最后一层不能写成sensor/#/temp$SYS/开头的系统 Topic 不受通配符匹配详见下文谨慎使用#订阅全部消息——在大规模场景下会造成性能问题五、系统类TopicEMQX 等 Broker 内置了系统级 Topic以$SYS/开头用于获取 Broker 自身运行状态$SYS/broker/version # Broker 版本号 $SYS/broker/uptime # 运行时间 $SYS/broker/clients/connected # 当前连接数 $SYS/broker/messages/received # 累计接收消息数注意$SYS不以/开头且$开头的 Topic不会被通配符匹配。也就是说#不会匹配到$SYS/#这是协议设计的保护机制防止系统消息意外泄露给业务订阅者。六、Topic数量评估设计 Topic 时要估算总量确保 Broker 能扛住。以一个中型农场为例类型数量计算Topic 数传感器数据10个大棚 × 10种传感器100控制器指令10个大棚 × 5个控制器50设备状态150个设备 × 1150系统TopicBroker 内置~20合计~320EMQX 单节点轻松处理数十万 Topic320 个完全不在话下。即使是大型基地上万设备Topic 数也就几万个毫无压力。真正需要关注的不是 Topic 数量而是消息吞吐速率和订阅关系数量。每个订阅关系会占用内存大规模场景下需要关注 Dashboard 中的订阅数指标。七、Topic注册与管理7.1 是否需要Topic白名单小规模项目500设备不需要。Topic 规范靠团队约定和代码审查保证即可。中大规模项目500设备建议引入 Topic 白名单。EMQX 支持 ACL 规则配置限定设备只能 publish/subscribe 特定模式的 Topic# EMQX ACL 配置示例-permission:allowaction:publishtopic:agriculture/farm01//sensor/-permission:allowaction:subscribetopic:agriculture/farm01//controller//command这样即使设备被篡改也无法向非法 Topic 发送消息。7.2 Topic命名文档化强烈建议在项目初期建立 Topic 字典文档类似 API 文档Topic方向Payload格式发布者订阅者说明agriculture/{farm}/{gh}/sensor/temperature上行{temp: 25.3, ts: 1704067200}传感器数据服务温度上报agriculture/{farm}/{gh}/controller/pump/command下行{action:start,speed:80}控制服务控制器泵控制指令有了这份文档前后端、设备端开发者一目了然不用猜 Topic 含义。总结Topic 设计的核心就一句话像设计数据库表结构一样设计 Topic。想清楚层级、命名、通配符需求和权限边界一次定稿全程受用。千万不要先随便起个名后面再改——后面改的代价远超你想象。
