ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-604] CloudEvents 來源 ​

摘要 ​

本文件提供了如何正確使用 CloudEvents 中 source 欄位的指導。

背景 ​

CloudEvents 中的 source 欄位標識了事件發生的上下文。它對於唯一識別事件及其來源至關重要。

決策 ​

我們將採用以下 source 欄位指南:

  1. 必須遵循 CloudEvents 規範慣例: source + id 必須是唯一的。
  2. 應該使用 UUID、URI、URL 或 URN 作為 source 欄位，並在同一應用程序/產品中保持一致性。
  3. 應該遵循此優先順序: 絕對 URI > URI 引用 > URN > UUID。

詳細資訊 ​

格式偏好 ​

  1. 絕對 URI (最優先) 當事件源有常規 API 端點時使用。

    json
    {
  "specversion": "1.0",
  "source": "https://api.the-app.com/users/{uuid}"
}

  2. 相對 URI 當事件源未在特定 API 端點公開時使用。

    json
    {
  "specversion": "1.0",
  "source": "//vortexcloud.com/applications/{application-id}"
}

    或

    json
    {
  "specversion": "1.0",
  "source": "/users/{uuid}"
}

  3. URN 提供了一種按類別識別資源的程序化方法。參見 URN 命名約定原則。

  4. UUID (最不優先)

特殊情況 ​

  • 對於集合(資源)的事件，source 可以是集合本身。 示例(用於 created / deleted 事件):

    json
    {
  "specversion": "1.0",
  "type": "com.example.event",
  "source": "/users",
  "id": "A234-1234-1234",
  "time": "2024-07-10T08:42:00Z",
  "datacontenttype": "application/json",
  "data": {
    "message": "新建用戶集合"
  }
}

  • 對於單個資源的事件，source 可以是唯一資源。 示例(用於 updated 事件):

    json
    {
  "specversion": "1.0",
  "type": "com.example.event",
  "source": "/users/123",
  "id": "A234-1234-1234",
  "time": "2024-07-10T08:42:00Z",
  "datacontenttype": "application/json",
  "data": {
    "message": "用戶資料已更新"
  }
}

結果 ​

  • 改善系統中 source 欄位使用的一致性。
  • 更好的事件可追溯性和來源識別。
  • 可能需要更新現有的事件生產者以符合這些指南。

參考資料 ​

  • CloudEvents 規範

    來自 https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md#source-1

    source

    • 類型: URI-reference

    • 描述: 標識事件發生的上下文。通常這將包括諸如事件源的類型、發布事件的組織或產生事件的進程等資訊。URI 中編碼數據的確切語法和語義由事件生產者定義。

      生產者必須確保 source + id 對每個不同的事件是唯一的。

      應用程序可以為每個不同的生產者分配一個唯一的 source，這使得生成唯一 ID 變得容易，因為沒有其他生產者會有相同的源。應用程序可以使用 UUID、URN、DNS 權威或特定於應用程序的方案來創建唯一的 source 標識符。

      一個 source 可能包括多個生產者。在這種情況下，生產者必須協作以確保 source + id 對每個不同的事件是唯一的。

    • 約束:

      • 必需
      • 必須是非空的 URI 引用
      • 推薦使用絕對 URI

    • 示例

      • 具有 DNS 權威的互聯網範圍內唯一 URI。
        • https://github.com/cloudevents
        • mailto:cncf-wg-serverless@lists.cncf.io
      • 具有 UUID 的通用唯一 URN:
        • urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66
      • 特定於應用程序的標識符
        • /cloudevents/spec/pull/123
        • /sensors/tn-1234567/alerts
        • 1-555-123-4567