174 lines
4.1 KiB
Markdown
174 lines
4.1 KiB
Markdown
---
|
||
outline: [2, 3]
|
||
---
|
||
|
||
# Websocket
|
||
|
||
WebSocket 是现代前端开发中使用最广泛的技术之一。为了简化 Olares 应用的使用与开发，Olares 应用程序运行时提供了一个通用的 WebSocket 组件。
|
||
|
||
## 客户端
|
||
|
||
基于 JavaScript/TypeScript 的方式开发的客户端，采用 “ws” 库。
|
||
应用服务提供 WebSocket 的路径格式：`wss://<appid>.<username>.olares.com/ws`
|
||
|
||
### 发送消息
|
||
|
||
客户端发送 WebSocket 消息格式如下（支持其他格式）：
|
||
```json
|
||
{
|
||
"event": "...",
|
||
"data": {...}
|
||
}
|
||
```
|
||
|
||
### Ping
|
||
|
||
客户端需要定期发送 ping 包（30 秒一次），以维持 WebSocket 连接。（WebSocket 服务定期检查 ping 包，超时则会主动关闭该连接），ping 包数据格式如下（严格按照如下格式）：
|
||
```json
|
||
{
|
||
"event": "ping",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
## 应用
|
||
|
||
WebSocket 服务提供多种功能：
|
||
- 允许服务器通过广播消息或响应客户端发送的 WebSocket 消息与客户端进行通信。
|
||
- 可用于关闭特定用户或连接 ID 的 WebSocket 连接。
|
||
- 获取当前连接列表。
|
||
|
||
因为 WebSocket 与应用是部署在一个容器中的，所以直接访问 localhost 即可调用 WebSocket 服务。端口 `40010`。
|
||
|
||
### 广播消息
|
||
```json
|
||
// URL：http://localhost:40010/tapr/ws/conn/send
|
||
// 请求方式：POST
|
||
// body
|
||
{
|
||
"payload": {}, // 消息。
|
||
"conn_id": "<connId>", // 连接 ID；用于响应客户端的单次 Ws 请求。按 users 广播时不要填写 connId
|
||
"users": ["<userName-1>", "<userName-2>"], // 指定用户，如果填写该字段，则是广播。广播场景下不要填写 connId
|
||
}
|
||
|
||
// 响应示例
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
}
|
||
```
|
||
|
||
### 关闭客户端的 WebSocket 连接
|
||
```json
|
||
// URL：http://localhost:40010/tapr/ws/conn/close
|
||
// 请求方式：POST
|
||
// body
|
||
{
|
||
"conns": ["<connId>", ...], // 关闭指定连接
|
||
"users": ["<userName>", ...], // 关闭指定用户的所有连接
|
||
}
|
||
|
||
// 响应示例
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
}
|
||
```
|
||
|
||
### 获取当前在线的连接列表
|
||
|
||
```json
|
||
// URL：http://localhost:40010/tapr/ws/conn/list
|
||
// 请求方式：GET
|
||
// 响应示例
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"name": "<userName>",
|
||
"conns": [
|
||
{
|
||
"id": "<connId>", // 连接 ID
|
||
"userAgent": ""
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### WebSocket 转发客户端消息到应用
|
||
|
||
将转发到应用的客户端消息分为三种类型：
|
||
- 客户端连入
|
||
- 客户端正常发送的消息
|
||
- 客户端连接断开，如关闭浏览器，网络异常等。
|
||
|
||
**客户端连入**
|
||
|
||
```json
|
||
// URL：http://localhost:3010/websocket/message
|
||
// 请求方式：POST
|
||
// body
|
||
|
||
{
|
||
"data": {},
|
||
"action": "open", // action
|
||
"user_name": "<userName>",
|
||
"conn_id": "1" // WebSocket 连接 ID
|
||
}
|
||
|
||
// 应用 App 接收到 open 的消息后，做相关处理。
|
||
```
|
||
|
||
**客户端正常发送的消息**
|
||
|
||
```json
|
||
// URL：http://localhost:3010/websocket/message
|
||
// 请求方式：POST
|
||
// header，会传递客户端的原始 Cookie 给后端应用
|
||
Cookie: .... // v1.0.3 版本新增功能
|
||
|
||
// body
|
||
{
|
||
"data": { ... }, // 客户端发到 WSGateway 的原始数据，内部结构为 {"event":"", "data": {...}}
|
||
"action": "message", // action
|
||
"user_name": "<userName>",
|
||
"conn_id": "1", // WebSocket 连接 ID
|
||
}
|
||
|
||
// 应用 App 处理后通过“广播消息”的接口，将数据回传给客户端
|
||
|
||
```
|
||
|
||
**客户端连接断开**
|
||
>WebSocket 服务响应到 close 事件后回调应用
|
||
|
||
```json
|
||
// URL：http://localhost:3010/websocket/message
|
||
// 请求方式：POST
|
||
// body
|
||
|
||
{
|
||
"data": {},
|
||
"action": "close", // action
|
||
"user_name": "<userName>",
|
||
"conn_id": "1" // WebSocket 连接 ID
|
||
}
|
||
|
||
// 应用 App 接收到 close 的消息后，做相关处理。
|
||
```
|
||
|
||
## 应用部署 WebSocket 服务
|
||
|
||
应用要使用这个功能只需要在应用 Chart 的 [OlaresManifest.yaml](../package/manifest.md#websocket) 中申明。
|
||
```yaml
|
||
options:
|
||
websocket:
|
||
url: /ws/message
|
||
port: 8888
|
||
```
|
||
|
||
WebSocket 是在客户端和应用之间承载消息转发的组件，所以应用端需要提供一个 API 接口，供 WebSocket 调用转发客户端的 ws 消息。比如，按上面的申明应用应提供接口名为：`/ws/message`，端口是 `8888`。
|