MQTT主题命名规范

1. 概述

本文档定义了懒人精灵高级版混合开发项目中MQTT消息主题的命名规范，以确保消息传递的一致性和可维护性。

以下信息主要是以标准网关为例，并不是强制要求。仅供参考。

2. 主题结构

MQTT主题采用多层结构，使用斜杠(/)作为分隔符，结构如下：

{direction}/{dataType}/{operation}/{userId}/{deviceId}/{messageType}

2.1 层级说明

3. 命名规则

3.1 基本规则

• 只使用小写字母
• 不使用空格和特殊字符
• 层级之间使用斜杠(/)分隔
• 使用有意义的名称
• 保持主题层级的一致性，避免解析错误

3.2 具体命名

3.2.1 传输方向 (direction)

• mqtt: 设备上报到服务端
• cloud: 服务端下发到设备控制

3.2.2 数据类型 (dataType)

• device: 设备相关信息
• task: 任务相关信息
• screen: 屏幕相关信息

3.2.3 操作类型 (operation)

• data: 数据传输
• request: 请求操作
• status: 状态更新
• info: 信息更新

3.2.4 消息类型 (messageType)

• live: 实时数据
• history: 历史数据
• event: 告警事件
• switch: 控制命令

4. 主题示例

4.1 设备相关主题

mqtt/device/info/{phone}/{deviceId}/live     # 设备信息上报
mqtt/device/status/{phone}/{deviceId}/live   # 设备状态上报

4.2 任务相关主题

mqtt/task/data/{phone}/{deviceId}/live       # 任务数据上报

4.3 屏幕相关主题

mqtt/screen/data/{phone}/{deviceId}/live     # 屏幕数据上报
cloud/screen/request/{phone}/switch          # 屏幕请求下发（下发给指定用户的所有设备）

5. 最佳实践

5.1 主题设计原则

1. 层级清晰: 每一层级都有明确的含义
2. 易于扩展: 便于添加新的数据类型或操作
3. 一致性: 相同类型的数据使用相同的主题结构
4. 可读性: 主题名称直观易懂

5.2 注意事项

1. 避免主题层级过深（建议不超过6层）
2. 避免使用通配符订阅过于宽泛的主题
3. 合理设置QoS级别和保留消息标志
4. 定期清理不再使用的主题

6. 示例代码

6.1 Lua端主题定义

-- 设备信息主题
local topicDeviceInfo = "mqtt/device/info/" .. phone .. '/' .. getDeviceId() .. '/live'
-- 设备状态主题
local topicDeviceState = "mqtt/device/status/" .. phone .. '/' .. getDeviceId() .. '/live'
-- 任务信息主题
local topicTaskInfo = "mqtt/task/data/" .. phone .. '/' .. getDeviceId() .. '/live'
-- 屏幕数据主题
local topicScreenData = "mqtt/screen/data/" .. phone .. '/' .. getDeviceId() .. '/live'
-- 屏幕请求主题
local topicScreenRequest = "cloud/screen/request/" .. phone .. '/switch'

6.2 消息处理示例

gobridge.register("onMQTTMessage", function(jsonData)
    local data = jsonLib.decode(jsonData)
    local topicParts = {}
    for part in string.gmatch(data.topic, "[^/]+") do
        table.insert(topicParts, part)
    end

    if #topicParts >= 4 then
        local direction = topicParts[1]
        local dataType = topicParts[2]
        local operation = topicParts[3]

        -- 根据主题路径处理不同类型的消息
        if direction == "cloud" and dataType == "screen" and operation == "request" then
            sendSccreenBase64Data()   // 发送投屏数据
        end
    end
end)

7. 版本历史