ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

WebSocket API 設計指南 ​

WebSocket 是一種全雙工通信協議，適用於即時應用程序，如聊天、遊戲和即時通知。在設計 WebSocket API 時，必須考慮消息格式、連接管理、安全性和可擴展性。設計 WebSocket API 時必須遵守以下準則:

消息格式 ​

  • 通過 WebSocket 傳輸的所有消息必須使用統一格式，如 JSON。
  • 消息應包含一個類型屬性(property)，以區分不同類型的消息。
  • 應包含時間戳，以便於消息排序和調試。

JSON 消息格式示例:

json
{
  "type": "message_type",
  "data": {
    "key1": "value1",
    "key2": "value2"
  },
  "timestamp": "2024-07-29T12:34:56Z"
}

連接管理 ​

  • 握手: 客戶端必須使用標準 WebSocket 握手建立連接。服務器必須以適當的標頭回應。
  • 保活: 服務器應使用 ping/pong 幀實現保活機制，以檢測和關閉空閒或死亡連接。
  • 重新連接: 客戶端必須實現健壯的重新連接策略，以優雅地處理斷開連接。
  • 優雅關閉: 服務器必須能夠優雅地關閉，正確關閉所有活動的 WebSocket 連接。

安全性 ​

  • 認證: 客戶端必須在建立 WebSocket 連接之前進行認證。這應該使用在握手期間發送的令牌(例如 JWT)來完成。
  • 加密: 必須使用安全 WebSocket (wss://) 來加密客戶端和服務器之間傳輸的數據。
  • 授權: 服務器必須實現授權檢查，以確保客戶端只能執行他們被允許的操作。

DRAFT 錯誤處理 ​

  • 標準錯誤消息: 服務器必須定義一組標準錯誤消息和代碼，以便在出錯時發送給客戶端。
  • 錯誤日誌: 服務器應記錄錯誤以用於調試和監控目的。

錯誤消息格式示例:

json
{
  "type": "error",
  "error": {
    "type": "/problems/unauthorized",
    "message": "Unauthorized access"
  },
  "timestamp": "2024-07-29T12:34:56Z"
}

速率限制 ​

Websocket API 基本上只能限制連線中的 Socket 數量。當數量達到上限時，應該透過 WebSocket 返回以下回應：

json
{
  "type": "error",
  "error": {
    "type": "/problems/reach-maximum-connections",
    "message": "message Maximum number of connections reached"
  },
  "timestamp": "2024-07-29T12:34:56Z"
}

版本控制 ​

請參閱 API Versioning。針對 WebSocket API，基本上只能使用 url versioning。

文件 ​

  • 為您的 WebSocket API 提供全面的文件

OAS 3.1 示例 ​

OpenAPI 規範(OAS) 3.1 支持記錄 WebSocket API。以下是使用 OAS 3.1 記錄 WebSocket API 的示例:

yaml
openapi: 3.1.0
info:
  title: 聊天 WebSocket API
  version: 1.0.0
  description: 用於實時聊天應用程序的 WebSocket API
servers:
  - url: wss://chat.example.com/ws
paths:
  /chat:
    post:
      summary: 建立 WebSocket 連接
      responses:
        '101':
          description: 切換協議
components:
  schemas:
    Message:
      type: object
      properties:
        type:
          type: string
          description: 消息的類型
        data:
          type: object
          additionalProperties: true
          description: 消息的數據負載
        timestamp:
          type: string
          format: date-time
          description: 消息發送的時間戳
    ErrorMessage:
      type: object
      properties:
        type:
          type: string
          const: error
          description: 表示這是一條錯誤消息
        error:
          type: object
          properties:
            code:
              type: integer
              description: 錯誤代碼
            message:
              type: string
              description: 錯誤消息
        timestamp:
          type: string
          format: date-time
          description: 錯誤發生的時間戳

這個示例定義了一個位於 wss://chat.example.com/ws 的 WebSocket 服務器，帶有 /chat 路徑。它包括標準消息和錯誤消息的架構，確保整個 WebSocket API 的消息格式一致。

參考資料 ​