📚 课程目录第4章 Data Layer读写与订阅实战

4. Data Layer读写与订阅实战

Data Layer 是 ctrlX AUTOMATION 中承载实时过程数据的核心服务，所有应用、PLC 程序、HMI 与外部系统之间的数据交换，最终都落到 Data Layer 的节点树上。节点以路径形式组织，例如 plc/app/Application/sym/PLC_PRG/counter 或 diagnostics/.../cpu/load，每个节点带有值、类型、时间戳、权限与元数据。要真正把 Data Layer 用起来，关键不是记住某个接口，而是理解三种访问通道各自的定位：REST API 适合一次性读写与批量操作，WebSocket 适合持续订阅与低延迟推送，SDK 适合在应用内部以类型安全的方式集成。本节围绕这三条通道，给出可直接落地的读写、订阅与批量处理方式。

一、REST API：一次性读写与批量操作

REST 接口以 HTTP 动词映射数据操作：GET 读取节点，PUT 写入节点，POST 用于批量或带参数的复杂操作。读取单个节点时，路径直接拼在 URL 中：

GET /automation/api/v1/.../nodes/plc/app/Application/sym/PLC_PRG/counter
Authorization: Bearer <token>

200 OK
{
  "type": "int32",
  "value": 42,
  "timestamp": "2025-01-15T08:31:22.114Z"
}

写入时使用 PUT，请求体只需给出 value，服务端会按节点声明的类型做校验：

PUT /automation/api/v1/.../nodes/plc/app/Application/sym/PLC_PRG/setpoint
Content-Type: application/json

{ "value": 75.5 }

如果类型不匹配（例如向 int32 节点写 75.5），服务端返回 400 并附带类型错误说明，而不是静默截断。这一点在调试时非常重要：写入失败往往不是权限问题，而是类型或路径错误。

批量操作是 REST 通道最有价值的场景。逐个读写 200 个节点会产生 200 次往返，而批量接口一次请求即可完成。典型做法是把多个节点操作放入一个请求体，服务端按顺序执行并返回每个节点的结果：

POST /automation/api/v1/.../nodes/bulk
{
  "operations": [
    { "op": "read",  "path": "plc/.../counter" },
    { "op": "write", "path": "plc/.../setpoint", "value": 80.0 },
    { "op": "read",  "path": "plc/.../status" }
  ]
}

返回结果中每一项都带独立的 status，因此部分成功、部分失败是可以被精确识别的。批量操作适合初始化参数下发、周期性采集一组相关信号、或在一次事务中同步多个设定值。需要注意的是，批量并不等于原子事务：若第 2 项失败，第 1 项通常已经生效，应用层需要根据返回结果决定是否回滚。

二、WebSocket：订阅通知与变化推送

轮询 REST 接口读取变化值会带来延迟与流量浪费。WebSocket 通道建立长连接后，客户端只需声明订阅的节点路径，服务端在值变化时主动推送。订阅请求通常包含路径、采样方式与推送条件：

{
  "type": "subscribe",
  "path": "plc/app/Application/sym/PLC_PRG/counter",
  "sampling": "on_change",
  "deadband": 1
}

sampling 可取 on_change（值变化才推）或 polling（固定周期推）；deadband 用于抑制小幅抖动，例如 deadband: 1 表示变化量不足 1 时不推送。推送消息一般包含路径、新值、旧值与时间戳，便于应用判断是上升沿、下降沿还是越限。订阅建立后应处理三类事件：正常数据帧、连接断开、以及服务端返回的订阅错误（如路径不存在）。生产代码中必须实现断线重连与重新订阅，否则一次网络抖动就会导致数据静默丢失。

三、SDK：应用内类型安全集成

当数据访问发生在 ctrlX 应用内部时，使用 SDK 比裸调 HTTP 更合适。SDK 把节点路径、数据类型和订阅回调封装为强类型接口，编译期即可发现类型错误。典型流程是：创建 Data Layer 客户端 → 按路径读取或写入 → 注册订阅回调 → 在回调中处理数据。SDK 内部仍然走 REST 与 WebSocket，但省去了手工拼装 JSON、解析响应和处理重连的重复工作。对于需要高频读写或与 PLC 周期同步的场景，SDK 还能配合批量接口减少调用次数。

四、通道选择与结果判读

三条通道并非互斥，实际项目常组合使用：启动阶段用 REST 批量下发参数并读取初始状态；运行阶段用 WebSocket 订阅关键信号；应用内部逻辑用 SDK 封装读写。选择依据可以归纳为：需要一次性取值或批量操作时用 REST；需要持续感知变化时用 WebSocket；需要在应用代码中频繁、类型安全访问时用 SDK。

结果判读上，REST 关注 HTTP 状态码与响应体中的 status；WebSocket 关注推送帧的时间戳是否连续、断线后是否重新订阅成功；SDK 关注回调是否被触发以及异常是否被捕获。一个常见的排障顺序是：先用 REST GET 确认路径存在且可读，再用 PUT 确认写权限与类型，最后用 WebSocket 确认变化能被推送。若 REST 可读但 WebSocket 无推送，通常问题在订阅条件（deadband 过大或 sampling 设置不当），而非数据本身。

批量操作时建议把“读”和“写”分开组织：先批量读取当前值作为基线，再批量写入新值，最后批量读取回读值进行校验。这样即使部分写入失败，也能通过回读结果定位具体节点。

WebSocket 订阅不会自动恢复。连接断开后必须重新发送订阅请求，并在重连成功后重新拉取一次全量值，避免因断线期间的变化丢失而导致状态不一致。

把这三条通道用熟之后，Data Layer 就不再是一个抽象的“数据服务”，而是一套可精确控制、可观测、可批量处理的数据访问层。后续无论是做 HMI 数据绑定、PLC 与上层应用协同，还是做诊断与日志采集，都可以在此基础上直接展开。