设备消息、上下线与属性流转

约 1140 字大约 4 分钟

2025-03-03

设备消息既服务于平台内部处理，也用于外部 Hook 和客户端实时展示。本章说明三种接入边界、消息字段及属性上报/控制的完整观察路径。

选择订阅方式

消费者	入口	使用边界
Web/mobile	WebSocket 频道	用户认证与资源授权
外部业务服务	Hook	平台管理员配置企业与能力范围
平台内受信服务	FastEvent 与 `things/share/topics`	内部传输权限，不直接向浏览器暴露

属性变化会按调用点进入应用事件、Hook 与实时频道，但不同链路不构成同一事务。某个消费者收到消息不能证明其他消费者或设备端都已成功。

属性上报的观察路径

设备/协议网关 → Things 接收与解析 → 物模型/质量与时间处理
                              → 存储/最新状态
                              → 内部事件 / Hook / WebSocket

单属性载荷：

{
  "device":{"productID":"DEMO","deviceName":"sensor1"},
  "tenantCode":"<company-code>",
  "projectID":"123",
  "timestamp":"1792112400000",
  "receivedTime":1792112400123,
  "identifier":"temperature",
  "param":25.5,
  "quality":"GOOD"
}

整包属性载荷：

{
  "device":{"productID":"DEMO","deviceName":"sensor1"},
  "tenantCode":"<company-code>",
  "projectID":"123",
  "timestamp":"1792112400000",
  "receivedTime":1792112400123,
  "params":{"temperature":25.5,"humidity":null},
  "quality":{"temperature":"GOOD","humidity":"BAD"}
}

timestamp 为字符串毫秒，receivedTime 为数字毫秒，未知历史接收时间为 0。属性质量按属性分别解释：无效值不能擅自显示为 0，也不能把未上报的属性当作这次上报值。

上下线、事件和行为

上下线消息：

{
  "device":{"productID":"DEMO","deviceName":"sensor1"},
  "status":1,
  "timestamp":"1792112400000"
}

status 为 1 上线、2 下线。断开、超时和平台修正状态均应通过当前状态链路处理，客户端不要只根据自己的 MQTT/WS 连接判断目标设备在线。

事件包含 identifier、type（info/alert/fault）、params、时间及设备信息；行为消息包含 actionID、msgToken、dir、reqType 和结果，按请求标识关联。不要将行为响应和普通事件混为同一个报文。

平台内部事件主题

当前常量在 things/share/topics/notify.go，主要模式如下：

消息	主题
上线	`app.<tenantCode>.device.<productID>.<deviceName>.status.connected`
下线	`app.<tenantCode>.device.<productID>.<deviceName>.status.disconnected`
单属性	`app.<tenantCode>.device.<productID>.<deviceName>.report.thing.property.<identifier>`
整包属性	`app.<tenantCode>.v2.device.<productID>.<deviceName>.report.thing.property`
事件	`app.<tenantCode>.device.<productID>.<deviceName>.report.thing.event.<type>.<identifier>`
行为	`app.<tenantCode>.device.<productID>.<deviceName>.report.thing.action.<actionID>.<reqType>.<dir>`

使用常量与 fmt.Sprintf 构造，不照抄历史 application.device... 主题。普通订阅和队列订阅的选择见事件总线；FastEvent 已处理外层信封，回调解析业务 JSON。

内部主题没有替外部请求做用户认证。需要接收某企业的事件，按受控配置限定企业，禁止将全平台通配订阅直接开放给第三方。

外部 Hook 对应能力

上下线：dmDeviceConn.report、dmDeviceDisConn.report。
属性：devicePropertyReport.report、devicePropertyReportV2.report。
事件：deviceEventReport.report。

Hook 外层有 method/data/userCtx，WebSocket 外层有 type/channel/data；业务内容相似，但不能把一种信封当另一种解析。设备消息的企业与项目来自设备实际归属。

属性控制需要分开确认

用户提交控制 → 身份/项目/物模型权限 → 下发到协议网关 → 设备执行
                                             → 回执/再次上报 → 页面状态收敛

HTTP 控制成功可能表示平台接受或发出请求，不保证设备已经执行。某些控制路径也产生属性变化通知，不能把通知出现当作真实设备回执。测试必须同时观察下行报文、设备/模拟器执行结果、回执或再次上报和页面最终状态。

避免让“收到属性变化 → 再发控制”形成反馈循环。使用请求标识、方向和业务状态判断，必要时去重。

联调检查

设备认证连接、合法主题发布/订阅正常，非法设备和越权主题被拒绝。
上报属性后检查解析、最新值、历史值、质量与时间。
同时观察内部消费者、Hook 和有权 WebSocket 订阅，跨企业订阅不得收到数据。
发出属性控制，观察真实下行及回执，校验不在线设备的结果。
验证断开/重连、重复消息、过期数据和项目切换后的通知范围。

独立协议网关的开发与测试入口见应用协议开发。

更新日志

2026/10/16 19:46

查看所有更新日志

b3b4d-docs(平台开发): 恢复有效专题并更新当前实现示例于 2026/10/16

后端专题

实时通信

业务能力