📚 课程目录第3章规则链基础

3、规则链基础：规则链概念、节点类型、消息元数据与数据体结构

规则链（Rule Chain）是 ThingsBoard 的核心数据处理引擎，它决定了设备上报的数据如何被解析、过滤、转换、存储以及转发到外部系统（如 CSV 文件或 Kafka 集群）。理解规则链的底层概念与消息结构，是后续实现数据导出方案的前提。

3.1 规则链核心概念

规则链本质上是一个由节点（Node）通过连接（Connection）构成的有向无环图（DAG）。每个节点执行一个特定的处理逻辑，消息从根节点流入，沿着连接线依次经过各个节点，最终到达链尾或终止节点。

  关键术语：

  规则链（Rule Chain）： 一组节点的逻辑集合，定义了消息的处理流程。
节点（Node）： 规则链中的最小处理单元，每个节点有唯一的类型和配置。
连接（Connection）： 节点之间的有向边，定义了消息的流转路径。连接可以附带关系标签（Relation Type），如 Success、Failure、True、False。
消息（Message）： 在规则链中流动的数据单元，包含元数据（Metadata）和数据体（Data/Msg）。
根规则链（Root Rule Chain）： 每个租户必须有一个根规则链，所有设备上报的数据默认首先进入根规则链。

3.2 节点类型详解

ThingsBoard 提供了丰富的节点类型，按功能可分为以下四大类：

类别	节点类型	功能描述	典型用途
过滤器	Check Relation / Message Type Filter / Script Filter	根据条件判断消息是否继续向下流转	只处理遥测数据，忽略属性更新
转换器	Script Transformation / Change Originator / Rename Keys	修改消息的元数据或数据体内容	将温度单位从华氏度转为摄氏度
动作	Kafka / MQTT / REST API / Save to Database / CSV Export	执行具体的业务操作，如发送消息、存储数据	将遥测数据写入 Kafka 主题
外部	Generator / Log / Delay / RPC Call Request	与外部系统交互或控制消息流节奏	生成模拟数据、记录日志

💡 节点选择建议： 在数据导出场景中，通常使用 Script Filter 过滤无效数据，使用 Script Transformation 格式化数据体，最后使用 Kafka Node 或 CSV Export Node 完成导出动作。

3.3 消息结构：元数据（Metadata）与数据体（Data）

每条在规则链中流动的消息都包含两个核心部分：元数据和数据体。理解它们的区别与用途，是编写规则链脚本的基础。

3.3.1 元数据（Metadata）

元数据是键值对（Key-Value）形式的上下文信息，通常由系统自动填充或由上游节点设置。元数据不包含设备上报的具体数值，而是描述“消息从哪里来、何时来、谁发的”。

// 元数据示例（JSON 格式）
{
  "deviceName": "温度传感器-A01",
  "deviceType": "temperature_sensor",
  "ts": 1712563200000,
  "customerId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "originatorType": "DEVICE"
}

元数据键	说明	来源
`deviceName`	设备名称	系统自动注入
`deviceType`	设备类型	系统自动注入
`ts`	消息时间戳（毫秒）	系统自动注入
`customerId`	客户 UUID	系统自动注入
`originatorType`	发起者类型（DEVICE/ASSET/ENTITY）	系统自动注入

3.3.2 数据体（Data / Msg）

数据体是消息的载荷部分，即设备实际上报的数据内容。数据体可以是 JSON 对象、字符串或二进制数据。对于遥测数据，通常是一个 JSON 对象，包含多个键值对。

// 数据体示例（JSON 格式）
{
  "temperature": 25.6,
  "humidity": 68.2,
  "pressure": 1013.25,
  "status": "normal"
}

⚠️ 常见误区： 在规则链脚本中，msg 代表数据体，metadata 代表元数据。初学者容易混淆，例如在 Script Transformation 节点中，msg.temperature 访问的是数据体中的温度值，而 metadata.deviceName 访问的是元数据中的设备名称。

3.4 消息在规则链中的完整生命周期

一条消息从进入规则链到最终导出，通常经历以下阶段：

消息注入： 设备通过 MQTT/HTTP/CoAP 上报数据，ThingsBoard 将数据封装为消息，注入根规则链。
消息过滤： 经过 Message Type Filter 或 Script Filter 节点，判断消息类型（遥测/属性/事件）是否符合预期。
消息转换： 通过 Script Transformation 节点，对数据体进行格式化、单位转换、字段重命名等操作。
消息路由： 根据关系标签（Success/Failure），消息被路由到不同的下游节点。
消息动作： 到达 Kafka Node 或 CSV Export Node，执行数据导出操作。
消息终结： 消息被成功处理或丢弃，生命周期结束。

3.5 规则链脚本中的消息访问方式

在 Script Transformation 和 Script Filter 节点中，可以通过预定义的全局变量访问消息内容：

变量名	类型	说明	示例
`msg`	Object	数据体，即设备上报的载荷	`msg.temperature`
`metadata`	Object	元数据，包含设备上下文信息	`metadata.deviceName`
`msgType`	String	消息类型，如 `POST_TELEMETRY`、`POST_ATTRIBUTES`	`msgType === 'POST_TELEMETRY'`
`ts`	Number	消息时间戳（毫秒）	`ts`

// Script Transformation 节点示例：将数据体与元数据合并，准备导出
var newMsg = {
  device: metadata.deviceName,
  timestamp: ts,
  temperature: msg.temperature,
  humidity: msg.humidity,
  pressure: msg.pressure
};
return { msg: newMsg, metadata: metadata, msgType: msgType };

  📌 要点总结：
  规则链是 ThingsBoard 的数据处理流水线，节点通过连接构成有向图。
节点分为过滤器、转换器、动作和外部四大类，每类承担不同职责。
消息由元数据（上下文）和数据体（载荷）组成，脚本中通过 metadata 和 msg 访问。
数据导出场景的核心操作发生在转换器节点（格式化数据）和动作节点（写入外部系统）。