ws_channel 模块 API 文档与交互逻辑

注意websocket的数据格式为: text

一、模块概述

ws_channel 是基于 Erlang + Cowboy WebSocket 实现的 MQTT 相关交互模块，主要用于服务注册、主题订阅、指标数据上报、事件发送及消息广播等功能，通过 WebSocket 协议实现客户端与服务端的实时双向通信。

三、核心 API 方法

客户端通过发送 JSON 格式文本消息 与服务端交互，消息格式遵循 JSON-RPC 风格（包含 id、method、params 字段）。

1. 服务注册（register）

功能

注册服务并建立客户端与服务进程的关联，是后续操作（订阅、上报数据等）的前提。

请求格式

{
  "id": <整数，请求唯一标识>,
  "method": "register",
  "params": {
    "service_id": <二进制，服务唯一标识，必填>,
    "meta_data": <映射，服务元数据，可选>,
    "container_name": <二进制，容器名称，可选>
  }
}

响应格式

• 成功响应：

  {
    "id": <与请求id一致>,
    "result": "ok"
  }
  

• 失败处理：服务端直接关闭连接（因 attach_channel 失败）

2. 主题订阅（subscribe）

功能

订阅指定主题，后续可接收该主题的广播消息。

请求格式

{
  "id": <整数，请求唯一标识>,
  "method": "subscribe",
  "params": {
    "topic": <二进制，订阅的主题名称，必填>
  }
}

响应格式

• 成功响应：

  {
    "id": <与请求id一致>,
    "result": "ok"
  }
  

• 失败响应：

  {
    "id": <与请求id一致>,
    "error": {
      "code": -1,
      "message": "错误描述"
    }
  }
  

处理逻辑

通过 efka_subscription:subscribe(Topic, self()) 完成订阅，订阅成功后客户端会收到该主题的广播消息。

3. 指标数据上报（metric_data）

功能

向服务进程上报设备指标数据。

请求格式

{
  "method": "metric_data",
  "params": {
    "device_uuid": <二进制，设备唯一标识，必填>,
    "route_key": <二进制，路由键，必填>,
    "metric": <指标数据，必填>
  }
}

响应处理

服务端接收后无返回消息（处理逻辑：efka_service:metric_data(ServicePid, DeviceUUID, RouteKey, Metric)）

4. 事件发送（event）

功能

向服务进程发送事件消息。

请求格式

{
  "method": "event",
  "params": {
    "event_type": <二进制，事件类型，必填>,
    "body": <事件内容，必填>
  }
}

五、基础交互协议

1. Ping/Pong 心跳：

   • 客户端发送 ping 消息
   • 服务端回复 pong 消息，维持连接

2. 未知消息处理：

   • 客户端发送未定义格式的消息时，服务端记录错误并关闭连接

七、典型交互流程

1. 客户端发起 WebSocket 连接
2. 客户端发送 register 请求完成注册
3. 客户端发送 subscribe 请求订阅目标主题
4. 客户端通过 metric_data 上报指标数据 / 通过 event 发送事件
5. 服务端向客户端推送已订阅主题的消息（publish 方法）
6. 连接关闭（主动断开或异常终止）