# MQTT协议联调

## 规则（Rules）

# MQTT协议联调规范

## 适用对象和范围

本规范适用于所有MQTT协议联调对接的场景。

---

## 1. Topic匹配规范

**规则**：发布方和订阅方的Topic必须完全匹配，通配符使用需准确。

- `+` 匹配单层，`#` 匹配多层，不可混用

**违反后果**：Topic不匹配导致消息无法送达。

---

## 2. QoS等级规范

**规则**：禁止忽略QoS等级差异，发布与订阅的QoS等级必须一致。

**违反后果**：QoS不匹配影响消息送达可靠性。

---

## 3. 数据转换规范

**规则**：禁止直接修改设备端固件代码来适配服务端格式，必须通过转换层处理。

**违反后果**：修改固件代码导致设备端维护困难。

## 方法（Methods）

# MQTT协议联调方法

## 前置条件

- [ ] 已有MQTT协议设计文档
- [ ] 服务端已实现MQTT Broker连接
- [ ] 设备端或前端已实现MQTT客户端连接

---

## 流程概览

```
阅读协议文档 → 检查Topic设计 → 检查消息格式 → 编写数据转换协议 → 逐Topic验证 → 修复问题
```

---

## 详细步骤

### 步骤1：阅读MQTT协议文档

分析协议文档，提取Broker地址、Topic定义、消息格式和QoS等级。

### 步骤2：检查Topic设计与订阅

检查发布方和订阅方的Topic是否匹配，通配符使用是否正确。

### 步骤3：检查消息格式

## 技巧（Tips）

# MQTT协议联调技巧

## 1. 使用统一的Topic命名规范

**适用场景**：设计MQTT Topic结构时。

**具体做法**：使用层级结构 `/domain/device_id/action` 组织Topic。

**示例**：
```
/devices/{device_id}/upload
/devices/{device_id}/command
/system/notification/{type}
```

## 2. 编写Payload转换函数

**适用场景**：设备端与服务端数据格式不一致时。

**具体做法**：编写 `transformDeviceToServer` 和 `transformServerToDevice` 转换函数。

## 3. 常见问题速查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 消息收不到 | Topic不匹配 | 检查发布和订阅的Topic字符串 |
| 消息格式错误 | Payload结构不一致 | 编写转换函数统一格式 |
| 连接失败 | Broker地址错误 | 检查Broker地址和端口 |