Topic 结构与层级

Topic 结构与层级

概述

本节介绍 MQTT Topic 的结构设计原则和层级管理。学习完成后，您将能够：

• 设计合理的 Topic 层级结构
• 理解 Topic 命名规范和最佳实践
• 通过实际例子掌握 Topic 设计方法
• 解释 Topic 架构的价值

前置要求

在开始本节之前，请确保：

• 理解发布-订阅架构
• Mosquitto Broker 已运行
• 安装了 MQTT 命令行工具

Topic Basics

What is a Topic?

MQTT Topic 是消息的目标地址，使用 UTF-8 编码的字符串，采用斜杠 / 分隔的层级结构：

Topic 格式：层级1/层级2/层级3/.../层级N

实例：
sensors/temperature/livingroom
factory/zone1/machine3/status
home/groundfloor/office/temperature

Topic Characteristics

特性	说明	示例
层级结构	用 / 分隔的树形结构	floor/room/sensor
区分大小写	Temperature ≠ temperature	注意大小写一致性
可读性	对人类友好的命名	避免缩写歧义
UTF-8 编码	支持多语言文字	中文 Topic 理论上可行
无长度限制规范	但建议 < 256 字符	过长影响性能

Topic Design Principles

General Design Rules

┌────────────────────────────────────────────────────────┐
│               Topic 设计原则                             │
├────────────────────────────────────────────────────────┤
│                                                        │
│  1. 自上而下：从通用到具体                                │
│     设备类型 → 位置 → 传感器类型                          │
│     sensors/factory_zone1/temperature                    │
│                                                        │
│  2. 不要以斜杠开头                                       │
│     ✅ factory/zone1/temperature                         │
│     ❌ /factory/zone1/temperature (产生空级)              │
│                                                        │
│  3. 不要以斜杠结尾                                       │
│     ✅ factory/zone1/temperature                         │
│     ❌ factory/zone1/temperature/ (额外空级)              │
│                                                        │
│  4. 避免空格和特殊字符                                    │
│     ✅ factory/zone1/temperature                         │
│     ❌ factory/zone 1/temperature (空格问题)              │
│                                                        │
│  5. 层级深度建议不超过 5 层                                │
│     ✅ factory/zone1/temperature    (3级)                │
│     ⚠️ factory/building/floor/room/sensor/temp (6级)    │
│                                                        │
└────────────────────────────────────────────────────────┘

Recommended Topic Templates

工厂环境监测：

factory/{zone}/{sensor_type}
factory/{zone}/{machine_id}/{parameter}

实例：
factory/zone1/temperature
factory/zone1/humidity
factory/zone1/machine_003/temperature
factory/zone1/machine_003/vibration

智能家居：

home/{floor}/{room}/{device_type}/{action}

实例：
home/ground/kitchen/temperature
home/ground/livingroom/light/status
home/first/bedroom/light/set
home/first/bathroom/humidity

设备控制：

devices/{device_id}/{command}
devices/{device_id}/{parameter}/status

实例：
devices/esp32_001/control
devices/esp32_001/temperature/status
devices/shelly_002/relay/set
devices/shelly_002/relay/status

Topic Design Examples

Example 1: Single Sensor

不好的设计：

temperature                  # 太笼统，无法区分位置
temp_zone1                   # 混合命名方式

好的设计：

factory/zone1/environment/temperature

Example 2: Multi-Sensor System

不好的设计：

sensors                      # 没有区分度
data                         # 没有信息量

好的设计：

factory/zone1/temperature    # 温度数据
factory/zone1/humidity       # 湿度数据
factory/zone1/light          # 光照数据
factory/zone1/air_quality    # 空气质量

Example 3: Command and Control

常见模式——分离控制和状态：

# 控制命令（设备接收）
devices/kitchen_light/set          # 接收控制命令
  Payload: {"power": "on"}

# 设备状态（设备发送）
devices/kitchen_light/status       # 上报状态
  Payload: {"power": "on", "brightness": 80}

Topic Categories

Data vs Control Topic

将数据和控制分离是一个重要的设计原则：

Topic 类别	用途	示例
Data Topic	传感器数据上报	factory/zone1/temperature
Control Topic	控制命令下发	factory/zone1/actuator/set
Status Topic	设备状态上报	factory/zone1/actuator/status
Config Topic	设备配置管理	factory/zone1/device/config
Event Topic	事件通知	factory/zone1/alarm/hightemp
System Topic	Broker 系统消息	$SYS/broker/clients/connected

Topic Naming Conventions

数据类 Topic：

格式: {domain}/{location}/{sensor_type}
示例: factory/zone1/temperature
      home/livingroom/humidity
      agriculture/greenhouse1/soil_moisture

控制类 Topic：

格式: {domain}/{location}/{actuator}/set
示例: factory/zone1/fan/set
      home/livingroom/light/set
      agriculture/greenhouse1/valve/set

状态类 Topic：

格式: {domain}/{location}/{device}/{parameter}/status
示例: factory/zone1/machine3/power/status
      home/livingroom/light/power/status
      agriculture/greenhouse1/pump/status

Practical Examples

Factory Monitoring System

Topic 结构设计：

factory/                                                # 域：工厂
  zone1/                                                # 区域
    environment/                                        # 环境
      temperature                                       # 温度数据
      humidity                                          # 湿度数据
      light                                             # 光照数据
    machine/                                            # 设备
      m001/
        status                                          # 设备状态
        temperature                                     # 设备温度
        vibration                                       # 振动数据
    alarm/                                              # 告警
      hightemp                                          # 高温告警
      device_offline                                    # 设备离线
  control/                                              # 全局控制
    zone1/
      fan/set                                           # 风扇控制
      ac/set                                            # 空调控制

Smart Home System

Topic 结构设计：

home/                                                   # 域：家庭
  ground/                                               # 楼层：地面
    livingroom/
      temperature                                       # 温度
      humidity                                          # 湿度
      light/status                                      # 灯光状态
      light/set                                         # 灯光控制
    kitchen/
      temperature
      gas/set                                           # 燃气阀控制
      gas/status
  first/                                                # 楼层：二楼
    bedroom/
      temperature
      light/set
      curtain/set                                       # 窗帘控制
    bathroom/
      temperature
      humidity

验证

验证 Topic 设计

# 1. 发布测试消息到设计的 Topic
mosquitto_pub -h localhost -t "factory/zone1/temperature" -m "26.5"
mosquitto_pub -h localhost -t "factory/zone1/humidity" -m "62"

# 2. 使用通配符验证结构
mosquitto_sub -h localhost -t "factory/zone1/#" -v
# 预期输出:
# factory/zone1/temperature 26.5
# factory/zone1/humidity 62

# 3. 使用单级通配符
mosquitto_sub -h localhost -t "factory/+/temperature" -v
# 预期: 所有区域的温度数据

最佳实践

DOs and DON’Ts

• ✅ 推荐: 使用有意义的层级结构，便于过滤和组织
• ✅ 推荐: 为命令、状态、数据使用独立的 Topic
• ✅ 推荐: 在 Topic 设计阶段考虑未来的扩展
• ✅ 推荐: 使用小写字母和短横线（如有需要）
• ❌ 避免: 以 / 开头或结尾的 Topic
• ❌ 避免: Topic 层级超过 5 层
• ❌ 避免: 在 Topic 中包含空格、特殊字符
• ❌ 避免: Topic 名称过于冗长（建议 < 256 字符）

Design Checklist

• Topic 结构是否支持按区域过滤？
• Topic 结构是否支持按设备类型过滤？
• 控制 Topic 和数据 Topic 是否分离？
• Topic 层级是否在 3-5 层之间？
• Topic 命名是否一致且可读？
• 是否预留了扩展空间（新增设备类型、区域）？
• Topic 是否避免了空格和特殊字符？

Summary

本节要点总结：

1. Topic 结构：用斜杠 / 分隔的层级结构，从通用到具体
2. 设计原则：一致性、可读性、扩展性
3. 分类管理：数据 Topic、控制 Topic、状态 Topic 分离
4. 命名规范：小写、无空格、避免特殊字符
5. 层级深度：3-5 层最佳，不超过 5 层