ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-603] CloudEvents 類型約定 ​

指導原則 ​

  • 必須(MUST)使用命名空間事件

  • 必須(MUST)反轉域名

  • 必須(MUST)遵循命名約定

    json
    com.vivotek[.applicationId].resourceType.eventVersioning.eventInPastTense
    • applicationId 部分是可選的；如果 resourceType 部分在（反轉的）域名下保證唯一，則可以省略 application 部分

  • 可(MAY)使用應用特定域名，這樣不需要指定 applicationId

    json
    com.vortexcloud.resourceType.eventVersioning.eventInPastTense

  • 事件版本控制應該(SHOULD)遵循語義化版本控制

  • 資源類型註冊和管理應該(SHOULD)在集中的註冊表中

  • 整體事件類型註冊和管理應該(SHOULD)在集中的註冊表中

  • 事件名稱應該(SHOULD)使用過去式

  • 單一名稱應該(SHOULD)是駝峰式

示例 ​

以下是一些符合上述指導原則的事件類型示例：

  1. 基本事件類型：

    http
    com.vivotek.camera.v1.recorded

  2. 包含應用 ID 的事件類型：

    http
    com.vivotek.vms.user.v1.created

  3. 使用語義化版本控制的事件類型：

    http
    com.vivotek.accesscontrol.door.v2.1.opened

OpenAPI 示例 ​

以下是一個使用 OpenAPI 3.0 描述 CloudEvents 類型約定的示例：

yaml
components:
  schemas:
    CloudEvent:
      type: object
      required:
        - specversion
        - type
        - source
        - id
      properties:
        specversion:
          type: string
          enum: ['1.0']
        type:
          type: string
          pattern: '^com\.vivotek(\.[a-z0-9]+)*\.[a-z0-9]+\.v\d+(\.\d+){0,2}\.[a-z]+$'
          example: 'com.vivotek.camera.v1.recorded'
        source:
          type: string
          format: uri-reference
        id:
          type: string
        time:
          type: string
          format: date-time
        data:
          type: object

paths:
  /events:
    post:
      summary: 發布一個 CloudEvent
      requestBody:
        content:
          application/cloudevents+json:
            schema:
              $ref: '#/components/schemas/CloudEvent'
      responses:
        '201':
          description: 事件成功發布
        '400':
          description: 無效的事件格式

注意事項 ​

  • 在設計新的事件類型時，應該(SHOULD)考慮現有的事件類型，以避免不必要的重複或混淆。

  • 定期審查和更新事件類型約定，以確保它們繼續滿足系統的需求。

  • DRAFT 考慮建立一個中央事件類型註冊表，以便團隊成員可以輕鬆查找和理解現有的事件類型。

參考資料 ​