[ADP-3] ADP 編號

目的

ADP 編號的目的是為了方便引用(例如：根據 ADP-501，...)。並且為了方便管理，我們制定了一些規則，將相關的 ADP 分類到特定的主題目錄下，每個主題目錄都保留了一個編號範圍。

指導

• 每個 ADP 必須(MUST)有一個唯一標識符，目前是一個數字。
• 通用 ADP 可以(MAY)在分配的範圍內定義自己的 ADP 編號範圍。
• ADP 編號必須(MUST)遵循以下分配：

ADP 編號分配

• 0-1000：保留給 HTTP API 設計的通用 ADP。
  • 此目錄下目前進一步分給了好幾個不同子目錄。
    • ADP 綜合: 0-19
    • 工程原則: 20-39
    • API 治理: 40-79
    • 命名慣例: 80-99
    • HTTP 基礎: 100-299
    • REST 基礎: 300-350
    • HTTP 語意: 350-399
    • 錯誤設計: 400-599
    • 事件設計: 600-699
    • JSON 原則: 700-749
    • OpenAPI 原則: 750-799
• 1000-2000：保留給擴展或補充 0-1000 範圍內的通用 ADP。
• 2000-2499：保留給 WebSocket API 設計。
• 2500-2999：保留給 GraphQL API 設計。
• 3000-3999：保留給異步 API 設計。
• 4000-4999：保留給非 HTTP 基礎的 API 設計。
• 10000+、20000+、30000+ 等：保留給特定應用程式/語言/組件/庫特定的 ADP。

DRAFT 狀態和版本控制

• 每個 ADP 應(SHOULD)包含一個狀態欄位，指示其當前狀態：

  • draft：初始提案
  • reviewing: 審核中
  • published：批准實施
  • deprecated：不再推薦

• DRAFT 已經 publised 的 ADP 還應(SHOULD)包括 Changelog 以追蹤隨時間變化。

範例

• ADP-404：HTTP API 錯誤處理（通用，HTTP API 設計）
• ADP-2105：WebSocket 連接生命週期（WebSocket API 設計）
• ADP-2750：GraphQL 查詢複雜度限制（GraphQL API 設計）
• ADP-10042：MyApp 特定錯誤處理（應用程式特定 ADP）

處理重疊

• 在 ADP 可能適合多個類別的情況下（例如，使用 WebSocket 的 GraphQL API），應(SHOULD)使用最具體或主要的類別。如有必要，可以包含對其他類別中相關 ADP 的交叉引用。

未來擴展

ADP 編號系統可能在未來擴展，以適應新的類別或子類別。任何此類擴展都將在本 ADP 的更新中公告和記錄。