一、协议核心设计原则
- 极致精简主题：仅保留 3 个核心主题，网关仅需订阅 2 个、发布 1 个，大幅降低开发与维护成本；
- 全字段缩写：关键字段采用 1-3 位缩写，压缩 JSON 报文体积 30%+，适配网关低带宽、低存储场景；
- 物模型兼容：保留产品标识、设备 ID、功能点三大物模型核心，覆盖注册、状态上报全流程；
- 标准化通信：基于 MQTT 3.1.1/5.0 协议，QoS=1 保证消息送达，retain=0 避免无效消息堆积。
二、基础规范（核心定义）
2.1 通信载体规范
表格
| 配置项 | 取值 | 说明 |
|---|---|---|
| 传输协议 | MQTT 3.1.1/5.0 | 主流物联网通用协议，兼容性强 |
| 消息质量 | QoS=1 | 至少一次送达，避免核心消息丢失 |
| 保留消息 | retain=0 | 不保留历史消息，减少无效数据占用 |
| 数据格式 | UTF-8 JSON | 轻量易解析，适配嵌入式网关 |
| 消息标识 | mid | 全局唯一消息 ID（UUID），用于链路追踪 |
2.2 关键字段缩写映射
为降低报文体积与开发记忆成本，核心字段统一缩写，映射关系如下：
表格
| 原字段名 | 缩写字段 | 字段含义 | 适用场景 |
|---|---|---|---|
| msgId | mid | 全局唯一消息 ID | 所有报文必含 |
| timestamp | ts | 13 位时间戳 | 所有报文必含 |
| version | ver | 协议版本 | 所有报文必含（固定值v1） |
| type | typ | 功能类型标识 | 区分报文功能，核心缩写字段 |
| productKey | pk | 子设备产品唯一标识 | 子设备注册 / 状态上报 |
| deviceName | dn | 子设备唯一 ID | 子设备注册 / 状态上报 |
| gatewaySn | gs | 网关唯一序列号 | 网关身份唯一标识 |
| properties | prop | 设备功能点 / 状态数据 | 物模型核心字段 |
| subDevices | sds | 子设备数组 | 批量注册场景 |
| hardwareVersion | hw | 网关硬件版本 | 网关注册 |
| softwareVersion | sw | 网关软件版本 | 网关注册 |
| ipAddress | ip | 网关本地 IP | 网关注册 |
| connectType | ct | 联网方式 | 网关注册（取值：wifi/eth/4g） |
2.3 客户端 ID 命名规则
网关作为唯一通信节点，子设备无需独立连接 MQTT，由网关透传所有消息：
- 网关客户端 ID：
gw_{gs}（例：gw_GW20260001，gs为网关序列号）； - 子设备：无独立客户端 ID，通过报文字段
pk+dn标识。
三、极致精简主题设计（仅 3 个）
以网关唯一序列号 gs 为核心隔离维度，所有功能复用主题，通过typ字段区分报文类型，主题格式如下：
表格
| 主题缩写格式 | 发布端 | 订阅端 | 覆盖功能 | 备注 |
|---|---|---|---|---|
gw/{gs}/req |
网关 | 平台 | 网关注册、子设备注册、状态上报 | 网关仅需发布此主题 |
gw/{gs}/resp |
平台 | 网关 | 所有请求的统一响应 | 网关核心订阅主题 |
gw/{gs}/ntf |
平台 | 网关 | 平台主动通知（可选） | 注册过期、设备异常等，按需启用 |
🔧 替换说明：
{gs}需替换为网关实际序列号（例：gw/GW20260001/req）
四、通用报文规范（必含字段）
所有请求 / 响应报文必须包含通用头字段，保证通信统一性，通用头结构如下：
json
{
"mid": "UUID唯一标识", // 全局唯一，用于匹配请求与响应
"ts": 1743456789012, // 13位时间戳，避免消息时序混乱
"ver": "v1", // 协议版本，固定值，便于版本兼容
"typ": "字符串" // 功能类型缩写，核心区分报文用途
}五、核心功能报文（全缩写）
5.1 网关注册（typ=rg）
功能说明
网关上电后向平台注册身份，上报硬件、软件、联网方式等基础信息，是网关与平台建立通信关系的第一步。
报文示例（网关→平台，发布至gw/{gs}/req）
json
{
"mid": "a1b2c3d4-5678-90ef-ghij",
"ts": 1743456789012,
"ver": "v1",
"typ": "rg",
"data": {
"gs": "GW20260001", // 网关唯一序列号
"hw": "v1.0", // 硬件版本
"sw": "v2.1", // 软件版本
"ip": "192.168.1.100", // 网关本地IP
"ct": "eth" // 联网方式：eth=以太网、wifi=无线、4g=移动网络
}
}平台响应报文（平台→网关，发布至gw/{gs}/resp）
json
{
"mid": "a1b2c3d4-5678-90ef-ghij",
"ts": 1743456789567,
"ver": "v1",
"typ": "rg",
"code": 200, // 状态码，200=成功
"msg": "网关注册成功", // 响应描述
"data": {
"et": 86400, // 注册有效期（秒）
"pt": 1743456789567 // 平台标准时间戳
}
}5.2 子设备注册（typ=rs）
功能说明
网关扫描并挂载子设备后，批量向平台上报子设备物模型信息（产品标识、设备 ID、功能点等），支持单次注册多个子设备。
报文示例（网关→平台，发布至gw/{gs}/req）
json
{
"mid": "b2c3d4e5-6789-01fg-hijk",
"ts": 1743456790123,
"ver": "v1",
"typ": "rs",
"data": {
"gs": "GW20260001",
"sds": [ // 子设备数组，支持批量注册
{
"pk": "TEMP_SENSOR_001", // 子设备产品标识（对应物模型）
"dn": "TS_0001", // 子设备唯一ID
"dt": "sensor", // 设备类型：sensor=传感器、switch=开关
"mv": "v1.0", // 物模型版本
"prop": [ // 子设备物模型功能点（核心）
{"id": "temp", "n": "温度", "t": "float", "u": "℃", "ro": true},
{"id": "bat", "n": "电量", "t": "int", "u": "%", "ro": true}
]
}
]
}
}平台响应报文（平台→网关，发布至gw/{gs}/resp）
json
{
"mid": "b2c3d4e5-6789-01fg-hijk",
"ts": 1743456790789,
"ver": "v1",
"typ": "rs",
"code": 200,
"msg": "子设备注册完成",
"data": {
"sc": 1, // 成功注册的子设备数
"fc": 0, // 失败注册的子设备数
"sl": ["TEMP_SENSOR_001_TS_0001"] // 成功注册的子设备ID列表
}
}5.3 子设备状态上报（typ=pr）
功能说明
子设备状态变化（如温度更新、电量变化）或定时上报时，网关透传数据至平台，支持单 / 多属性同时上报，适配实时监控场景。
报文示例（网关→平台，发布至gw/{gs}/req）
json
{
"mid": "c3d4e5f6-7890-12hi-jklm",
"ts": 1743456791234,
"ver": "v1",
"typ": "pr",
"data": {
"gs": "GW20260001",
"pk": "TEMP_SENSOR_001", // 待上报状态的子设备产品标识
"dn": "TS_0001", // 待上报状态的子设备唯一ID
"prop": { // 状态数据，键为功能点id，值为对应数值
"temp": 25.6,
"bat": 85
}
}
}平台响应报文（可选，平台→网关，发布至gw/{gs}/resp）
json
{
"mid": "c3d4e5f6-7890-12hi-jklm",
"ts": 1743456791890,
"ver": "v1",
"typ": "pr",
"code": 200,
"msg": "状态上报接收成功"
}六、通用状态码定义
统一状态码便于网关与平台排查通信问题，所有响应报文包含code字段，含义如下：
表格
| 状态码 | 含义 | 适用场景 |
|---|---|---|
| 200 | 操作成功 | 注册、状态上报等所有正常流程 |
| 400 | 参数错误 | 报文缺失必填字段、字段格式错误 |
| 401 | 鉴权 / 未注册失败 | 网关未注册、身份验证失败 |
| 404 | 设备不存在 | 上报状态时，子设备未在平台注册 |
| 500 | 平台服务异常 | 平台内部错误，无法处理请求 |
七、网关端实现流程（技术落地指引）
7.1 上电通信流程
- 初始化：网关启动后，初始化 MQTT 客户端，配置连接参数（服务器地址、端口、客户端 ID）；
- 订阅主题 ：连接 MQTT 后，订阅
gw/{gs}/resp与gw/{gs}/ntf（2 个主题，完成响应与通知接收）； - 网关注册 ：发布
rg类型报文至gw/{gs}/req，等待平台注册响应； - 子设备注册 ：注册成功后，扫描本地子设备列表，发布
rs类型报文完成子设备物模型注册； - 状态上报 ：子设备状态变化时，网关采集数据并发布
pr类型报文，实现实时同步。
7.2 异常处理机制
- MQTT 重连：连接断开后，自动触发重连，重连成功后重新订阅主题，并重发未收到响应的请求；
- 离线缓存：网关本地缓存离线状态数据，重连后批量补发，避免数据丢失；
- 超时重试：请求发送后，若超过设定时间（如 5 秒）未收到响应，自动重试（最多 3 次），避免单次通信失败。
八、协议核心优势
- 主题极致精简：仅 3 个主题，网关订阅 / 发布逻辑极简，大幅降低嵌入式网关开发复杂度；
- 报文体积最小：全字段缩写，JSON 体积压缩 30%+，适配低带宽、低存储的网关硬件；
- 物模型完整兼容：保留物模型核心定义，支持自定义功能点，可适配传感器、开关、控制器等各类子设备；
- 扩展灵活 ：新增功能（如指令下发、设备离线通知）仅需扩展
typ字段值，无需新增主题，无缝升级； - 标准化强：基于 MQTT+JSON 通用协议，兼容阿里云、华为云、腾讯云等主流物联网平台，降低对接成本。
九、扩展建议（可选功能）
- 指令下发扩展 ：新增
gw/{gs}/cmd主题，平台向网关下发子设备控制指令，typ扩展为ctrl（控制）、cfg（配置）； - 离线消息扩展：网关本地增加离线消息队列，缓存网络异常期间的注册、状态数据，重连后自动补发；
- 心跳机制 ：网关定时发布
typ=hb（心跳）报文至req主题，平台接收后判定网关在线状态，提升通信可靠性。
文末说明
本文协议专为物联网网关场景设计，兼顾精简性 与功能性，可直接作为网关端开发的技术文档，也可根据实际业务需求扩展指令下发、远程配置等功能。若需对接具体物联网平台，可在响应报文中增加平台专属标识字段，实现快速兼容。