127 lines
3.2 KiB
Markdown
127 lines
3.2 KiB
Markdown
# ws_channel 模块 API 文档与交互逻辑
|
||
|
||
## 注意websocket的数据格式为: text
|
||
|
||
## 一、模块概述
|
||
`ws_channel` 是基于 Erlang + Cowboy WebSocket 实现的 MQTT 相关交互模块，主要用于服务注册、主题订阅、指标数据上报、事件发送及消息广播等功能，通过 WebSocket 协议实现客户端与服务端的实时双向通信。
|
||
|
||
|
||
## 三、核心 API 方法
|
||
客户端通过发送 **JSON 格式文本消息** 与服务端交互，消息格式遵循 JSON-RPC 风格（包含 `id`、`method`、`params` 字段）。
|
||
|
||
|
||
### 1. 服务注册（register）
|
||
#### 功能
|
||
注册服务并建立客户端与服务进程的关联，是后续操作（订阅、上报数据等）的前提。
|
||
|
||
#### 请求格式
|
||
```json
|
||
{
|
||
"id": <整数，请求唯一标识>,
|
||
"method": "register",
|
||
"params": {
|
||
"service_id": <二进制，服务唯一标识，必填>,
|
||
"meta_data": <映射，服务元数据，可选>,
|
||
"container_name": <二进制，容器名称，可选>
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 响应格式
|
||
- 成功响应：
|
||
```json
|
||
{
|
||
"id": <与请求id一致>,
|
||
"result": "ok"
|
||
}
|
||
```
|
||
- 失败处理：服务端直接关闭连接（因 `attach_channel` 失败）
|
||
|
||
### 2. 主题订阅（subscribe）
|
||
#### 功能
|
||
订阅指定主题，后续可接收该主题的广播消息。
|
||
|
||
#### 请求格式
|
||
```json
|
||
{
|
||
"id": <整数，请求唯一标识>,
|
||
"method": "subscribe",
|
||
"params": {
|
||
"topic": <二进制，订阅的主题名称，必填>
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 响应格式
|
||
- 成功响应：
|
||
```json
|
||
{
|
||
"id": <与请求id一致>,
|
||
"result": "ok"
|
||
}
|
||
```
|
||
- 失败响应：
|
||
```json
|
||
{
|
||
"id": <与请求id一致>,
|
||
"error": {
|
||
"code": -1,
|
||
"message": "错误描述"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 处理逻辑
|
||
通过 `efka_subscription:subscribe(Topic, self())` 完成订阅，订阅成功后客户端会收到该主题的广播消息。
|
||
|
||
|
||
### 3. 指标数据上报（metric_data）
|
||
#### 功能
|
||
向服务进程上报设备指标数据。
|
||
|
||
#### 请求格式
|
||
```json
|
||
{
|
||
"method": "metric_data",
|
||
"params": {
|
||
"device_uuid": <二进制，设备唯一标识，必填>,
|
||
"route_key": <二进制，路由键，必填>,
|
||
"metric": <指标数据，必填>
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 响应处理
|
||
服务端接收后无返回消息（处理逻辑：`efka_service:metric_data(ServicePid, DeviceUUID, RouteKey, Metric)`）
|
||
|
||
|
||
### 4. 事件发送（event）
|
||
#### 功能
|
||
向服务进程发送事件消息。
|
||
|
||
#### 请求格式
|
||
```json
|
||
{
|
||
"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. 连接关闭（主动断开或异常终止） |