ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-2] ADP 撰寫 ​

指導原則 ​

  • ADP 設計應該(SHOULD)是產品無關的；這些原則旨在適用於同一公司內不同業務單位的每個產品、專案或應用程序。

    • 例外：我們保留了一些 ADP 編號給特定產品使用，請見 ADP 編號。

  • 每個 ADP 可以(MAY)包含一個或多個指導原則或設計建議。

  • 如果指導內容需要多於一句話來描述，它應該(SHOULD)成為一個新的 ADP 頁面。

  • 每個 ADP 必須(MUST)使用大寫的 MUST、MUST NOT、SHOULD、SHOULD NOT、MAY 或 MAY NOT，遵循 RFC 2119 要求關鍵字。

  • 每個 ADP 應該(SHOULD)歸類到特定的現有 ADP 類別，除非有需要創建新類別。

  • 每個 ADP 應該(SHOULD)在適用的情況下包含示例，以說明關鍵概念並提供實際使用場景。

  • 每個 ADP(SHOULD)應該使用美式英語撰寫，以保持文件的一致性。

    • 如果資源允許，每個 ADP 可以(MAY)有繁體中文版本，以適應非英語讀者。

  • 每個 ADP 應該(SHOULD)使用 Markdown 格式，以便於編輯、閱讀和與各種工具兼容。

  • 每個 ADP 文件的 markdown frontmatter 區域應該記錄唯一 ID 以及其他必要資訊。這個 ID 用於網頁路由和開發者之間的溝通。

    markdown
    ---
id: 1
title: Treat Developer Experience as important as User Experience
state: draft
created: 2024-12-12 # 建立文件當下的 ISO8601 日期
updated: 2024-12-13 # 上次修改的 ISO8601日期
---

# 必須將開發者體驗視為與用戶體驗同等重要

## 概述
...

  • 每個 ADP 不應(SHOULD NOT)使用 H1 標題（#），因為標題(title)已經佔用了 H1 級別。

  • 每個 ADP 應該(SHOULD)從預定義列表中明確指定其類別，以確保適當的組織和易於導航。

  • 一旦 ADP 從草稿狀態轉為發布狀態，應該(SHOULD)附加 CHANGELOG 欄位。

  • 每個 ADP 可以(MAY)通過 markdown 鏈接語法連接到其他 ADP，目標 ADP 使用 id：

    md
      - 參見 [描述此主題的 ADP](11)

  • 每個 ADP 必需(MUST)通過 repo 內部的 markdownlint 檢查

    sh
    pnpm run docs:lint
    sh
    docs:lint /Users/alive/Projects/api-design-principle-beta
> markdownlint-cli2 "**/*.md" "#node_modules"

markdownlint-cli2 v0.13.0 (markdownlint v0.34.0)
Finding: **/*.md !node_modules
Linting: 334 file(s)
Summary: 43 error(s)

  • 應(SHOULD)使用 詞彙表 中定義的常用術語。

HTTP API ADP ​

  • 每個與 HTTP API 設計相關的 ADP 應(SHOULD)包含 OpenAPI 文件的示例，因為 OpenAPI 是我們選擇的 HTTP API 文件工具。

ADP 生命週期 ​

  • 每個 ADP 應該在 markdown frontmatter 區域標記他的生命週期所在處，共有以下幾種：
    • state: draft 從提交 pull request 到納入 repo 後都是草案狀態。草案狀態不僅只在 pull request 時存在，有些時候我們需要預先發布一個 ADP 草案用來作為規範的預覽和後續討論的基礎。
    • state: reviewing 收入 repo 後，直到有特定 ADP 審核者開始審核時進入審核狀態。審核過程可能會經歷多個階段，另外用 phase: ${number} 在 frontmatter 區域標註。
    • state: published 審核結束後進入發布狀態。進入發布狀態後，如果有任何變更，需要在 ADP 本體的最後添加變更日誌（Changelog）。
    • state: deprecated 如果 ADP 被認為不再適用，則會進入棄用狀態。

ADP 類別 ​

目前，我們將 ADP 分為以下類別：

  • ADP 本身：與 ADP 框架及其組件相關的文件和指南。
  • 工程原則：指導開發過程的核心工程原則和最佳實踐。
  • HTTP 基礎：HTTP 的基本概念，包括方法、狀態碼和標頭。
  • REST 基礎：設計 RESTful API 的原則和實踐，包括資源建模和 URI 設計。
  • HTTP 語義：HTTP 語義的詳細解釋及其在 API 設計和實現中的應用。
  • JSON 原則：結構化 JSON 數據的指南，包括命名約定和數據類型。
  • 錯誤設計：API 中設計和處理錯誤的最佳實踐，包括錯誤代碼和回應格式。
  • 事件設計：設計事件驅動架構的原則，包括事件類型和負載結構。
  • 命名約定：API 中各種元素的標準化命名約定，如資源、參數和屬性(property)。
  • 應用程序特定約定：特定於應用程序域或項目需求的自定義指南和約定。

這些類別可能會隨著我們持續改進和擴展文件框架而發生變化和重組。

提議新的 ADP ​

  • 必須(MUST)使用 markdown 格式。
  • 在 ADP 站點的存儲庫中提交 pull request。（注意：它可能是一個鏡像存儲庫。找出上游存儲庫）。
  • 提案必須(MUST)包括:
    1. 合乎規範的 frontmatter 內容，包含 ADP 編號。
    2. 清楚的標題與文章內容。
    3. 明確的原則，使用 RFC Requirement Keywords。
    4. 如有必要，請提供設計理由(design rational)。
    5. 設計參考連結。
  • [Draft] 審核流程：TBD。
  • 在接受之前可能會要求反饋和修訂。

一個 ADP 的撰寫過程 ​

  • 找到想闡釋的特定主題。
  • 開始研究標準(IEEE RFC, W3)是否已經針對這個主題有解決方案或提案。
  • 如果沒有標準，那麼一定有慣例(convention)可以依循，試著在各種解決方案中評估出較佳選項。
  • 如果找不到慣例(convention)，才考慮從頭開始設計內容。

參考 ​