单级通配符

单级通配符

概述

本节介绍 MQTT Topic 的单级通配符 + 的使用方法和实际应用场景。学习完成后，您将能够：

• 理解单级通配符的工作原理
• 使用单级通配符实现灵活的 Topic 订阅
• 区分单级和多级通配符的适用场景
• 在实际 IoT 项目中应用通配符模式

前置要求

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

• 理解 Topic 层级结构
• Mosquitto Broker 已运行
• 已安装 MQTT 命令行工具

Wildcard Overview

What Are Wildcards?

MQTT 通配符是用于订阅时匹配多个 Topic 的特殊符号。MQTT 提供两种通配符：

通配符	名称	匹配范围
+	单级通配符	匹配一个层级
#	多级通配符	匹配多个层级

重要限制：通配符只能在订阅时使用，不能在发布时使用。

Single-Level Wildcard (+)

How It Works

+ 通配符匹配完整的一个 Topic 层级（两个斜杠之间的内容）：

Topic: home/+/temperature

匹配:
✅ home/livingroom/temperature
✅ home/kitchen/temperature
✅ home/bedroom/temperature
✅ home/garage/temperature

不匹配:
❌ home/livingroom/humidity (层级3不相同)
❌ home/ground/kitchen/temperature (层级数不同)
❌ home/livingroom/temperature/unit (层级数不同)

Key Characteristics

1. 精确匹配一个层级：+ 只替换一个层级的内容
2. 不能部分匹配：home/+room/temperature 不是有效写法
3. 支持多个通配符：可以在一个 Topic 中组合使用多个 +
4. 只能用于订阅：发布者不能使用通配符发布消息

Practical Examples

Example 1: Multi-Room Temperature Monitoring

Topic 结构：
home/{room}/temperature

发布：
home/livingroom/temperature → 25.5
home/kitchen/temperature    → 26.0
home/bedroom/temperature    → 23.5
home/garage/temperature     → 18.0

订阅所有房间的温度：
订阅 Topic: home/+/temperature

接收：
home/livingroom/temperature 25.5
home/kitchen/temperature    26.0
home/bedroom/temperature    23.5
home/garage/temperature     18.0

# CLI 验证
# 终端 1: 发布者 - 向不同房间发布温度
mosquitto_pub -h localhost -t "home/livingroom/temperature" -m "25.5"
mosquitto_pub -h localhost -t "home/kitchen/temperature" -m "26.0"
mosquitto_pub -h localhost -t "home/bedroom/temperature" -m "23.5"

# 终端 2: 订阅者 - 使用单级通配符
mosquitto_sub -h localhost -t "home/+/temperature" -v
# 预期输出:
# home/livingroom/temperature 25.5
# home/kitchen/temperature 26.0
# home/bedroom/temperature 23.5

Example 2: Factory Multi-Zone Monitoring

Topic 结构：
factory/{zone}/{sensor_type}

发布：
factory/zone1/temperature → 26.5
factory/zone1/humidity    → 62
factory/zone2/temperature → 28.0
factory/zone2/humidity    → 55

场景 A: 订阅所有区域的温度数据
订阅: factory/+/temperature
接收: zone1的温度 AND zone2的温度

场景 B: 订阅一个区域的所有数据
订阅: factory/zone1/+
接收: zone1的温度 AND zone1的湿度

场景 C: 多通配符 - 订阅所有区域的所有数据
订阅: factory/+/+
接收: 全部数据 (zone1/temp, zone1/hum, zone2/temp, zone2/hum)

# CLI 验证多通配符
mosquitto_sub -h localhost -t "factory/+/+" -v
# 预期: 所有区域的所有传感器数据

Example 3: Multi-Device Command

Topic 结构：
devices/{device_id}/command

场景：对特定设备下发命令
发布到: devices/esp32_001/command → {"reset": true}

场景：接收所有设备的命令
订阅: devices/+/command
接收: 所有设备的命令消息

Multiple Wildcards in One Topic

订阅中可以包含多个 + 通配符：

Topic 结构：factory/{floor}/{room}/{sensor}

订阅: factory/+/+/temperature
匹配:
✅ factory/1/101/temperature
✅ factory/2/205/temperature
✅ factory/3/302/temperature

不匹配:
❌ factory/1/101/temperature/fahrenheit (层级数不同)
❌ factory/1/temperature (层级数不同)

# 多通配符示例
mosquitto_pub -h localhost -t "factory/1/101/temperature" -m "25.0"
mosquitto_pub -h localhost -t "factory/2/205/humidity" -m "60"
mosquitto_pub -h localhost -t "factory/3/302/temperature" -m "23.5"

# 使用双通配符接收一楼所有数据
mosquitto_sub -h localhost -t "factory/1/+/+" -v
# 结果: factory/1/101/temperature 25.0
#       factory/1/101/humidity 60

Real-World Use Cases

Use Case 1: 聚合仪表板

// Node-RED 中订阅多个设备
// 订阅所有 factory 设备的数据
msg.topic = "factory/+/environment/+";

// 仪表板自动显示所有区域的数据

Use Case 2: 调试工具

// MQTT Explorer 中使用通配符
// 订阅整个系统的所有数据
Topic: factory/#

// 或只订阅温度数据
Topic: factory/+/+/temperature

Use Case 3: 动态路由

// Node-RED 中根据通配符匹配路由数据
// 订阅: factory/+/temperature
// 功能: 将所有区域的温度数据汇总到一个处理流程

// Function 节点提取区域名
var topicParts = msg.topic.split('/');
var zone = topicParts[1];  // 提取 zone1, zone2 等
msg.zone = zone;
return msg;

Common Pitfalls

Pitfall 1: 不能部分匹配单词

❌ 错误: home/+room/temperature
✅ 正确: home/+/temperature

说明: + 必须匹配完整的一个层级，不能做部分字符串匹配

Pitfall 2: 层级数量不匹配

发布: home/livingroom/temperature (3层)
订阅: home/+/temperature (3层) ✅ 匹配
订阅: home/+/temperature/extra (4层) ❌ 不匹配
订阅: home/+ (2层) ❌ 不匹配

Pitfall 3: 发布时使用通配符

❌ 错误: mosquitto_pub -t "home/+/temperature" -m "25.5"
    Error: Wildcard not allowed in publish topic

✅ 正确: mosquitto_pub -t "home/livingroom/temperature" -m "25.5"

Comparison: + vs #

特性	单级 +	多级 #
匹配层级	恰好一个层级	多个层级（含 0 个）
使用位置	任何层级	只能在 Topic 末尾
组合使用	可以多个 +	只能一个 #
场景	精确过滤	批量订阅
示例匹配	a/+/c 匹配 a/b/c	a/# 匹配 a/b/c/d/e

验证

验证通配符订阅

# 测试步骤
# 1. 使用通配符订阅
mosquitto_sub -h localhost -t "factory/+/temperature" -v &

# 2. 发布测试消息
mosquitto_pub -h localhost -t "factory/zone1/temperature" -m "26.5"
mosquitto_pub -h localhost -t "factory/zone2/temperature" -m "28.0"
mosquitto_pub -h localhost -t "factory/zone1/humidity" -m "62"  # 不会被接收

# 预期: 只收到两条 temperature 消息
# factory/zone1/temperature 26.5
# factory/zone2/temperature 28.0

Summary

本节要点总结：

1. + 通配符：匹配 Topic 中恰好一个层级的内容
2. 订阅专用：只能在订阅时使用，不能用于发布
3. 多通配符：一个订阅中可以包含多个 + 通配符
4. 适用场景：聚合多个设备的同类数据、按类型过滤
5. 常见错误：不能部分匹配、层级数量必须精确匹配