採現成格式標準還是自建規範

Fri, 03 Jul 2026 00:00:00 +0800

採現成的 response 格式標準（JSON:API 這類）省的是組織成本：團隊不用再為「JSON 回應該長什麼樣」開會吵、也能重用圍繞該標準的工具。自建規範換到的是貼合自己資料形狀的自由、代價是要自己維護規範與治理。這道選擇題比的是這兩筆帳、不是技術能力 —— 多數格式標準做得到的事、一份認真的自建規範也做得到。本文先講採現成標準各買到與綁定什麼、再回答一個更難的問題：一個格式標準會不會活下去、怎麼在採用前就看出來。（本文的 response 格式指 JSON body 的結構慣例；binary 格式如 Protobuf、hypermedia 格式如 HAL／Siren 在別層、後者見 REST 流派層。）

採現成標準買到的是組織成本

JSON:API 把價值主張直接寫在組織成本上。官網開宗明義：如果團隊曾為 JSON 回應怎麼格式化吵過架、JSON:API 能讓你停止這種 bikeshedding（為瑣碎細節沒完沒了地爭）（見 11.C50）。它賣的是一個大家都同意的現成慣例、格式能力本身並未更強 —— 附帶好處是圍繞這個慣例的工具可以重用、client 端也能靠標準化的結構做快取、有時省掉一次網路請求。

採現成標準的代價相對隱性：response 形狀從此綁在該標準的設計上、標準沒覆蓋的需求要嘛繞、要嘛回頭自建。JSON:API 的版本節奏很慢（1.1 距 1.0 約七年）—— 這既可讀成 spec 穩定、也可讀成演進動能有限。採用前要自己判：這個「慢」對你是保障、還是把你綁在一份不太會跟上新需求的格式上。response 的結構驗證是正交的另一層 —— JSON Schema 這類工具管「回應符不符合約定的形狀」、跟選哪個 response 格式標準是兩件事、選了 JSON:API 不代表驗證也一併有了。

怎麼預測一個標準會不會活

一個標準的正式化程度、不能拿來預測它會不會活。OData 是這條判準最清楚的反例：它是 OASIS 標準、還拿到 ISO/IEC 認證、正式化程度在同類裡最高、主流採用卻不成比例（見 11.C51、退場分析為二手來源）。Netflix 低調關掉 OData catalogue、eBay 同步棄用 —— 招牌級採用者（marquee adopter）的離場、比任何標準機構的背書都更能預測一個標準會不會活。生態才是存活的變數、認證徽章不是。

OData 退場還有更深一層、而且直接是使用層判準：它的設計把 repository 幾乎直通到 wire（對外的網路傳輸層）、自動生成 generic 查詢介面、暴露資料庫內部結構。這種「magic box」跟「API 是刻意設計的對外契約」的治理理念正面衝突 —— 採一個會把 DB 內部直通出去的標準、等於在這一層放棄了契約設計。所以判斷一個格式標準能不能採、除了看生態、還要看它逼你交出多少契約控制權。

採、自建、還是採一部分

三個問題把這道選擇題收斂。團隊會不會為格式反覆爭論、又需要現成工具生態 —— 會、採現成標準的組織成本節省就有買家。response 需求特不特殊、有沒有治理量能維護自建規範 —— 需求夠標準又沒有治理量能、自建規範會退化成沒人遵守的文件、還不如採現成的。這個標準的生態在長還是在縮 —— 看 marquee adopter 的進出、不看認證；看它逼你交出多少契約控制權、不看 feature 清單有多長。

這三題的答案不必指向同一邊。務實的常見解是採一份現成標準的子集當對外骨架、內部保留自建的擴充空間 —— 既拿到「停止爭論」的組織成本節省、又不把特殊需求鎖死在別人的格式設計裡。這道「採標準 vs 自建規範」的選擇、在組織治理層的完整判準見 11.10 API 規範治理。

下一步路由

採標準 vs 自建的治理層判準：11.10 API 規範治理
描述 API 形狀的格式標準怎麼選：描述格式的選型：OpenAPI 與 AsyncAPI
這道選擇題最具體的一次落地：錯誤格式之爭（採 RFC 9457 連 URI 命名空間與未知欄位忽略條款一起拿到，自建則要自己補這兩件）
案例原文：模組十一案例庫

描述格式的選型：OpenAPI 與 AsyncAPI

Fri, 03 Jul 2026 00:00:00 +0800

描述格式標準（OpenAPI、AsyncAPI）描述的是 API 本身的形狀 —— 有哪些 endpoint、吃什麼參數、回什麼結構 —— 給文件生成、client codegen（產生呼叫端程式碼）、mock、契約測試這些工具消費。它跟 response 格式標準（回應長什麼樣）不同層：response 格式管「回應長什麼樣」、描述格式管「怎麼把 API 的形狀寫成一份機器可讀的檔」。選這一層的標準、判準是兩件事：它有沒有既有的採用動能、以及它涵不涵蓋你這種介面。

描述格式標準靠既有動能、不靠背書

OpenAPI 成為 API 描述的事實標準、走的是一條跟 OData 相反的路。它源自 SmartBear 捐出的 Swagger Specification、轉進 Linux Foundation 下的 OpenAPI Initiative、以開放治理與 vendor neutrality 運作（見 11.C52）。關鍵差異在轉移的時機：捐出來時 Swagger 已經是事實標準、治理轉移是把一份已有動能的規格中立化、而不是靠標準機構的背書從零創造動能。

這正是採現成標準篇裡 OData（拿了 ISO 認證卻退場的那個案例）的反向情形。選一個描述格式標準時、要問的是它是不是已經被廣泛採用、還是靠機構背書硬推 —— 前者的認證是市場給的、後者的認證是委員會給的、兩者對存活的預測力差很多。OpenAPI 站穩後把描述範圍延伸到周邊問題（Arazzo 描述多 API workflow、Overlay 讓描述自動更新）—— 一個標準組織站穩後往鄰接問題延伸、是可觀察的生命週期訊號。

REST 加 event 混合時的補位

當系統同時有 REST API 跟 event、描述格式的選型多一個維度：涵蓋範圍。OpenAPI 描述的是 request/response 式的介面、描述不了 event-driven 的 publish/subscribe。AsyncAPI 來補這個空白、而且它補的方式本身是個值得學的策略：不另起爐灶、刻意維持跟 OpenAPI 相容、重用 OpenAPI 的 schema、只把結構換成 event 的語彙（Paths 換成 Channels、HTTP verbs 換成 Publish/Subscribe）（見 11.C53）。它明講的論證是系統很少只有 REST 或只有 event、多半兩者都有 —— 以相容性換採用曲線、站在既有標準的肩上而不是跟它競爭。

使用層的判讀：描述格式的邊界就是治理的邊界。組織同時有 REST 加 event 時、規範治理需要兩份 spec 格式（OpenAPI 描述同步介面、AsyncAPI 描述事件）、但共用一套 schema 來源 —— schema 是 source of truth、兩份描述格式是它在同步與非同步兩側的投影。event 側的能力與交接落在 03 訊息佇列。

選描述格式的兩個問題

選描述格式標準收斂成兩問。這個標準是不是已經是事實標準、有沒有工具生態實際在用它 —— 在 REST／HTTP request-response 這個 paradigm 內、OpenAPI 的動能沒有對手、選它不太需要猶豫。（GraphQL 與 gRPC 各自帶原生的形狀描述 —— GraphQL 的 SDL 加 introspection、gRPC 的 protobuf 加 server reflection —— 這不是 OpenAPI 的缺位、是不同 paradigm 各有自己的事實標準。）你的介面涵蓋哪些種類 —— 只有 REST、OpenAPI 一份就夠；有 event、加 AsyncAPI 補位、但守住「一套 schema 源、兩份格式投影」、別讓兩份描述各自長出不一致的真相。

描述格式選型幾乎不會落到「自建」這一格 —— 描述格式的價值全在生態工具、自建一份沒有工具吃的描述格式等於白做。（平台級玩家是例外：AWS 的 Smithy、Google 的 Discovery Document 都自建 IDL、把多語言 SDK 的 codegen 收進自己的 source、再往下游投影成 OpenAPI —— 自建不划算的判準只對沒有自有工具鏈的一般團隊成立。）這跟採現成標準篇裡「response 格式自建仍是合理選項」的判斷剛好相反、差別在於 response 格式的消費者是你自己的 client（自建規範自己遵守就成立）、描述格式的消費者是一整片第三方工具鏈（脫離事實標準就沒工具可用）。

下一步路由

採標準 vs 自建的治理層判準：11.10 API 規範治理
response 格式的採用選擇：採現成標準還是自建規範
event 側的能力與交接：03 訊息佇列
案例原文：模組十一案例庫

格式標準流派：採現成標準還是自建規範 on Tarragon

採現成格式標準還是自建規範

採現成標準買到的是組織成本

怎麼預測一個標準會不會活

採、自建、還是採一部分

下一步路由

描述格式的選型：OpenAPI 與 AsyncAPI

描述格式標準靠既有動能、不靠背書

REST 加 event 混合時的補位

選描述格式的兩個問題

下一步路由