📚 课程目录第3章消息结构解析

3、消息结构解析：消息体（msg）、元数据（metadata）、消息类型（msgType）详解，消息在规则链中的流转方式

在 ThingsBoard 规则链中，每一条消息都是一个结构化的数据包，由三个核心部分组成：消息体（msg）、元数据（metadata）和消息类型（msgType）。理解这三者的定义、作用以及它们在规则链中的流转方式，是进行高效调试和故障排查的基础。

3.1 消息三要素详解

规则链中的消息类似于一个信封：msgType 是信封上的“邮件类别”，metadata 是信封上的“寄件人/收件人信息”，而 msg 则是信封内的“信件内容”。三者协同工作，驱动着规则链的逻辑判断与数据转换。

要素	数据类型	典型内容	作用
消息体（msg）	JSON 对象	`{"temperature": 25.6, "humidity": 68}`	承载设备上报的实际业务数据，是规则链处理的核心载荷。
元数据（metadata）	键值对（Key-Value）	`deviceName: "温度传感器A"`, `deviceType: "sensor"`	携带消息的上下文信息，如设备名称、客户ID、数据来源、时间戳等。
消息类型（msgType）	字符串（String）	`POST_TELEMETRY`, `POST_ATTRIBUTES`, `ENTITY_CREATED`	标识消息的用途或来源，决定规则链的入口节点如何解析该消息。

调试提示：在规则链的“脚本”节点中，您可以通过 msg、metadata、msgType 三个内置变量直接访问消息的各个部分。例如，metadata.deviceName 可获取设备名称，msg.temperature 可获取温度值。

3.1.1 消息体（msg）——业务数据的载体

消息体是一个 JSON 对象，它包含了设备上报或系统生成的实际数据。对于遥测数据，msg 通常包含传感器读数；对于属性更新，msg 则包含属性键值对。在规则链处理过程中，msg 可以被转换、过滤或增强。

// 遥测消息示例
{
  "temperature": 25.6,
  "humidity": 68,
  "pressure": 1013.2
}

// 属性更新消息示例
{
  "firmwareVersion": "2.1.0",
  "configMode": "auto"
}

3.1.2 元数据（metadata）——消息的上下文信息

元数据以键值对形式存储，为规则链处理提供必要的上下文。它通常由系统自动填充，也可以在规则链中通过节点进行添加、修改或删除。常见的元数据键包括：

deviceName：发送消息的设备名称。
deviceType：设备类型。
customerId：关联客户ID。
ts：消息产生的时间戳（毫秒）。
dataType：数据来源类型（如遥测、属性）。

// 元数据示例
{
  "deviceName": "温湿度传感器-01",
  "deviceType": "temperatureSensor",
  "ts": "1698912345678",
  "customerId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"
}

3.1.3 消息类型（msgType）——消息的“身份证”

消息类型决定了消息在规则链中的入口行为。不同的消息类型会触发不同的处理路径。以下是 ThingsBoard 中最常见的消息类型：

消息类型	触发场景	典型 msg 内容
`POST_TELEMETRY`	设备上报遥测数据	传感器读数（温度、湿度等）
`POST_ATTRIBUTES`	设备上报属性数据	设备配置、状态信息
`ENTITY_CREATED`	创建设备、资产等实体	新实体的详细信息
`ENTITY_UPDATED`	更新实体信息	更新后的实体字段
`ENTITY_DELETED`	删除实体	被删除实体的ID
`RPC_REQUEST_FROM_SERVER`	服务器向设备发起RPC调用	RPC方法名和参数
`RPC_REQUEST_TO_SERVER`	设备向服务器请求RPC	请求的方法和参数

3.2 消息在规则链中的流转方式

消息在规则链中的流转遵循“输入 → 处理 → 路由 → 输出”的模型。每个规则节点接收消息，根据其内部逻辑处理消息，然后通过关系链接（Relation Link）将消息转发到下一个节点。

  核心流转机制：消息的流转不是广播式的，而是基于节点间定义的关系（如 Success、Failure、True、False）进行定向传递。一个节点可以有多个输出关系，每个关系对应不同的处理结果。

下图展示了消息从设备上报到规则链处理完成的标准流转路径：

3.3 消息在节点间的传递与变更

消息在规则链中流转时，其三个组成部分（msg、metadata、msgType）均可以被节点修改。理解这种变更机制对于调试至关重要。

消息体（msg）的变更：转换节点可以添加、删除或修改 msg 中的字段。例如，将摄氏温度转换为华氏温度后更新 msg.temperature。
元数据（metadata）的变更：元数据节点可以添加新的键值对（如从数据库查询到的客户等级），或删除不再需要的上下文信息。
消息类型（msgType）的变更：生成节点可以创建全新的消息，并赋予新的 msgType。例如，一个“告警生成”节点可以将遥测消息转换为 ALARM 类型的消息。

常见调试陷阱：在脚本节点中修改 msg 或 metadata 时，必须确保返回正确的数据结构。如果脚本返回 undefined 或格式错误的 JSON，消息将被丢弃，规则链处理中断。调试时建议在关键节点后添加“日志”节点，输出当前消息的完整结构。

3.4 消息流转的完整示例

以下是一个实际场景，展示消息从设备上报到触发告警的完整流转过程：

设备上报：温度传感器上报遥测数据 {"temperature": 85}，消息类型为 POST_TELEMETRY。
规则链入口：消息类型解析后进入“温度监控规则链”。
脚本节点处理：脚本读取 msg.temperature，判断是否超过阈值 80。如果超过，将 metadata.isOverheated 设置为 true。
条件路由：根据 metadata.isOverheated 的值，消息被路由到“告警生成节点”（True）或“数据存储节点”（False）。
告警生成：告警节点创建一个新的消息，msgType 变为 ALARM，msg 包含告警详情，metadata 保留设备上下文。

// 步骤3：脚本节点中的处理逻辑（JavaScript）
if (msg.temperature > 80) {
    metadata.isOverheated = 'true';
    metadata.overheatThreshold = 80;
    return { msg: msg, metadata: metadata, msgType: msgType };
} else {
    metadata.isOverheated = 'false';
    return { msg: msg, metadata: metadata, msgType: msgType };
}

通过上述示例可以看出，消息的 msg、metadata 和 msgType 在规则链的每个节点中协同工作，共同驱动着复杂的 IoT 业务逻辑。掌握这三者的结构和流转方式，是进行规则链调试和故障排查的第一步。