承諾的範圍比 schema 大

對外承諾的範圍涵蓋所有消費者觀察得到、且會寫進程式碼依賴的介面性質 — 欄位與型別只是最顯眼的一層。錯誤碼、HTTP status 的使用慣例、欄位預設值、回應時序、分頁行為、ID 字串的長度與格式、甚至欄位在 JSON 裡的順序、都可能被某個消費者拿去依賴。這個現象有個常被引用的名字：Hyrum’s Law — 使用者夠多時、介面的每個可觀察行為都會被某人依賴、無論服務端是否承諾過。

契約邊界的有效管理方式是把「消費者不可依賴的性質」明文寫出來、而非留給雙方猜。Stripe 的 upgrade 文件明列了一份相容變更清單、劃出服務端保留變更自由的軸（清單逐項與它在變更審查裡的用法、主寫在 11.6；案例見 11.C11）。這份清單的作用是雙向的：服務端保留這些軸上的變更自由、消費者拿到「寫 client 時什麼可以依賴」的明確指引。缺少這種明文劃界時、每個未宣告的性質都處於灰色地帶 — 變更的權責只能事後協商。

變更成本的兩種分配設計

承諾確立之後、變更成本的分配有兩種本質設計：由服務端吸收、或攤給所有消費者。這是 11.5 版本策略 背後的經濟結構、在本章先建立判讀框架。

服務端吸收的極端案例是 Stripe：服務端的轉換層一次吸收了約 100 個 backwards-incompatible 升級、同時維持與 2011 年以來每一版相容（轉換層機制的展開見 11.5；案例見 11.C10）。這個設計把變更成本收在服務端的基礎設施投資裡、換來的是消費者幾乎永遠不被迫遷移。

攤給消費者的設計則以「版本 + 遷移窗口」的形式出現：服務端宣告新版、給一段支援期、到期消費者必須完成遷移。成本較低、但把協調負擔外部化 — 適合消費者數量有限、或平台對生態有強制力的情境。兩種設計的選擇判準是消費者的數量、異質性、跟服務端對消費者的控制力：內部服務間的 API 可以直接協調升級、公開平台的十萬個 integration 只能靠承諾與窗口。

承諾違約的模式

違約的傷害大小跟違約的模式有關、明確的失敗優於靜默的行為改變。Facebook Graph API v1.0 退場時、到期的 v1.0 請求被靜默改以 v2.0 語意處理、而非回傳明確錯誤 — v2.0 移除了 friends 資料等大範圍權限、未遷移的 app 不會炸在認證層、而是拿到形狀不同的資料默默壞掉（見 11.C17、反例）。對照組是明確錯誤：消費者立刻知道、監控立刻報警、修復路徑清楚。設計退場行為時的判準是「消費者發現問題的延遲」— 靜默切換把發現延遲拉到不可控、明確錯誤把它壓到第一個請求。

判讀訊號

這些訊號的共同根因是承諾範圍或成本分配沒有被當成明確的設計對象。修法從明文化開始：先有相容變更清單、再有版本與退場政策、最後才是工具。

邊界

本章的框架適用於「有外部消費者」的介面 — 外部指組織邊界或部署邊界之外、修正代價無法用一次 refactor 收掉的情境。同一個 repo 內、同一次部署一起上線的模組間介面、變更成本結構完全不同、用內部重構紀律處理即可、套用本章框架是過度設計。

下一步路由

• 選風格與建模：11.2 風格選型總覽、11.3 資源建模與操作語意
• 承諾怎麼分期、什麼算 breaking：11.5 版本策略與 deprecation、11.6 向後相容的變更紀律
• 契約的驗證手段（consumer-driven contract test）：6.10 契約測試
• 名詞層：API Contract、Contract 知識卡
• 案例原文：模組十一案例庫

判準軸一：消費者形狀

消費者形狀指誰在呼叫、服務端對呼叫方有多少控制力、呼叫方跟服務端的部署與語言關係。這條軸是三條裡權重最高的、因為它決定其他軸的成本怎麼放大。

流派自己劃出的邊界最有說服力。tRPC 官方 FAQ 明言前提：脫離 monorepo 就失去 client 與 server 一起運作的保證、替代方案是把 backend 型別發成 private npm package — 語言鎖定 TypeScript、部署形態鎖定同倉或私包（見 11.C33）。公開撤退立場的六年 GraphQL 實踐者也給出同構的判準句、並建議控制得了 client 的團隊改用 OpenAPI REST（見 11.C22、反例、作者判讀層）。兩個相反方向的來源指向同一條判讀：選型的第一步是確認消費者是誰、再比對風格能力。

消費者形狀的常見分型與傾向：

表格是索引、每列的成立條件在真實情境裡要重新判讀。以 JSON-RPC 列為例：它在 web API 世代被 REST 式做法取代、卻在 LSP 與 MCP 兩份現代 spec 裡被選為訊息層 — 兩份 spec 都在 JSON-RPC 2.0 上加約束、而非發明新協議（見 11.C34；spec 只陳述採用、選型理由是本模組的判讀）。共同的條件組合是本地、雙向、需要 notification 語意、生態工具要求零 codegen 可自省 — 這組條件下 gRPC 的 HTTP/2 與 codegen 成本全是負資產。判讀重點是條件組合、而非「JSON-RPC 回來了」這種風格敘事。其餘各列的成立條件同樣散在後文 — gRPC 與 tRPC 的前提在判準軸二、三展開、GraphQL 的代價在爭論地圖路由的流派層、表格只負責索引。

判準軸二：演進成本

每種風格都要回答「介面上線後怎麼改」、機制差異很大。兩個代表性答案：GraphQL 的 versionless 路線把演進成本轉嫁到 schema 層的紀律、protobuf 把相容性直接做成編碼格式的性質 — 兩者的具體紀律與條款、主寫在 11.6 變更紀律 的格式層段（案例 11.C26、11.C28）。HTTP+JSON 的演進紀律則多半靠約定與流程、缺格式層的強制 — 這是它自由度最高也最容易踩線的原因。

選型時的判讀問題是團隊承擔得起哪種紀律：格式層強制（protobuf）適合跨團隊多語言、因為紀律不依賴人的自覺；約定層紀律（JSON、GraphQL SDL）需要配套的變更審查與工具、組織面見 11.10 規範治理。

判準軸三：操作與 debug 可及性

介面會被 on-call 的人徒手戳、會過 LB 與 proxy、會被防火牆規則篩 — 這些操作面的成本在能力比較表上通常缺席。gRPC 在這條軸上的代價有完整的一手批評：協議要求端到端 HTTP/2 加 trailers、瀏覽器支援需要翻譯 proxy、debug 時 curl | jq 不可行（見 11.C30、發布方是競品 vendor、批評點與 11.C32 的獨立實踐者批評互證後採用）。C32 提出的「傳一個 cURL 範例給朋友」測試是這條軸的可操作判準。

這條軸的權重跟組織的 infra 成熟度成反比：有能力在框架層集中處理 proxy、觀測、部署的組織（如 Dropbox 的 Courier、見 11.C31）、操作成本被平台吸收；小團隊每個介面都要自己扛操作面、可及性差的風格會在 on-call 時收利息。

共存是常態、取代是例外

大平台的長期實證支持「多風格共存」而非「新風格取代舊風格」。GitHub 2016 年採用 GraphQL、多年後的官方立場是 REST 與 GraphQL 並行、依情境選用、且明文說明功能覆蓋不對等（見 11.C20）。反方向的 Shopify 宣告 GraphQL 為唯一 API — 但它動用了「新功能只上 GraphQL、新 app 強制」的平台強制力、還配套 rate limit 加倍與查詢成本降 75%（見 11.C21）。判讀：沒有平台強制力的組織、務實的預期是多風格長期共存、選型的真正產出是「每個介面用對風格」、而非全公司統一答案。

爭論地圖

本章只給判準軸；各風格的深度交鋒在 styles/ 流派層：REST 語意學之爭與 hypermedia 復興（已完成）、GraphQL 的執行成本與進退（已完成）、proto 演進紀律與部署邊界（styles/grpc、backlog）、tRPC 與 JSON-RPC 的復興條件（styles/rpc-revival、backlog）、格式標準化的反覆嘗試（styles/standards、backlog）、server 推 client 的承諾差異（styles/realtime、案例待採集）。完整 backlog 見 模組頁 章節規劃。

下一步路由

• 承諾成本結構的框架：11.1 API 作為服務邊界的責任
• 選了風格之後的資源建模：11.3 資源建模與操作語意
• 事件式交接的能力邊界：03 訊息佇列、Webhook 知識卡
• 案例原文：模組十一案例庫

資源與表徵是兩層

資源建模的第一個概念區分是資源（resource）與表徵（representation）：資源是被命名的概念實體、表徵是它在某次回應裡的具體格式。這個區分出自 REST 論文的 uniform interface 子約束 manipulation through representations — client 透過表徵操作資源（約束清單見 11.C1、定義展開依論文原文）。工程意義：同一個資源可以有多種表徵（完整版、列表精簡版、不同版本的形狀）、表徵的形狀可以演進而資源身分不變 — URL 命名的是資源、欄位設計的是表徵、兩層的變更紀律不同。把這兩層混在一起的常見症狀是「加一個欄位要開一個新 endpoint」。

資源導向與動作導向的取捨

兩種建模方向各有成立情境、判準是操作的語意複雜度與演進預期。

資源導向把業務操作收斂成「對某個名詞的狀態操作」：建立、讀取、更新、刪除、加上狀態欄位變更。收益是介面詞彙統一 — 消費者學會一個資源的操作方式、就會操作所有資源；快取、權限、審計都能按資源粒度統一處理。成本是有些操作硬塞進名詞會失真：「重算報表」「合併帳號」「試算價格」這類操作沒有自然的資源對應。

動作導向（RPC 式端點）直接命名操作。收益是語意直白、參數自由；成本是介面詞彙發散 — 每個動作都是新詞彙、消費者要逐個學、橫切能力（快取、重試語意、權限）要逐個處理。

務實的判準是混用、但混用要有規則：預設資源導向、動作導向保留給「狀態機轉換有業務儀式」的操作（下單、退款、發布）、且動作端點的回應仍回到資源表徵（回訂單、不回裸 ack）。這條規則讓橫切能力至少在回應側保持統一。跨資源的操作（轉帳、合併）建議建模成獨立資源（transfer、merge job）— 操作本身有生命週期、有查詢需求、有失敗狀態時、它就值得一個名詞。

HTTP method 與 status 是承諾、不只是慣例

method 與 status 的選用向中介層與消費者承諾了行為性質、選錯的代價由基礎設施收取。GET 承諾安全（無副作用）— proxy 與瀏覽器會據此重試、預取、快取；PUT 承諾冪等 — client 可以直接重送、無需判斷前次結果；POST 兩者都沒承諾、所以需要冪等鍵機制補強（11.8 API 層冪等設計 主寫）。status 同理：2xx 對監控承諾成功、4xx 承諾「錯在請求、重試無用」（限流的 429 是明確例外、可重試但要等、見 11.9）、5xx 承諾「錯在服務、可以重試」— 把業務失敗包在 200 裡回傳、等於對整條觀測與重試鏈說謊、錯誤率圖表從此失真。錯誤語意的完整設計是 11.4 錯誤模型設計 的主題、本章只立「status 是給機器的承諾」這條判準。

Available actions 由誰計算

資源當下可做什麼操作、有兩種回答方式 — 這是 hypermedia 爭論落到建模層的具體形式。htmx 的 HATEOAS essay 用透支帳戶做對照：HTML 表徵在透支時只回 deposit 連結、業務狀態直接編碼在可用操作裡、client 零業務知識；JSON 表徵回 status: "overdrawn" 欄位、client 靠文件理解語意跟下一步（見 11.C5）。由此得到的操作型判別法：available actions 由 server 算完放進 response、還是 client 讀狀態欄位自己算 — 前者是 hypermedia 路線、後者是業界主流的 JSON API 路線。

判準層的建議：machine-to-machine 的 JSON API 走 client 自算是務實預設（消費者是程式、本來就要讀文件寫死邏輯）；但「狀態欄位 + 文件」的組合要把狀態機明文化 — 狀態列舉、每個狀態下的合法操作、非法操作回什麼錯誤。hypermedia 路線的完整論證與反方立場、收在 Hypermedia 與 HATEOAS 復興。

Richardson 成熟度模型可以當這個決策的定位工具：Level 1（資源化）、Level 2（method 與 status 語意正確）、Level 3（hypermedia controls）。一手來源自己標注它是理解工具、非 REST 認證（見 11.C3）。用它描述「我們的 API 在哪、要不要往上」是合法用法、拿它當合規檢查表是誤用 — 完整的實用讀法與誤用邊界、主寫在 Richardson 成熟度的實用讀法。

判讀訊號

四個訊號的損害半徑不同、排查順序從半徑最大的開始：GET 副作用會被中介層自動放大、屬立即修；200 包業務失敗污染整條觀測鏈、次之；端點增生與狀態機未明文是設計債、按迭代節奏收。

邊界

本章的建模判準以 HTTP+JSON 風格為主要語境。gRPC 與 GraphQL 的建模單位（service/method、type/field）有各自的紀律、收在對應流派層；事件式介面的建模（event schema）屬 03 訊息佇列 的範圍。

下一步路由

• 資料層的結構設計：1.2 Schema 設計（資源表徵與資料表是兩層、交接處看這篇）
• 風格還沒定、先回：11.2 風格選型總覽
• 承諾框架：11.1 API 作為服務邊界的責任
• 名詞層：Request-Response Protocol、API Contract 知識卡
• 案例原文：模組十一案例庫

第一刀：可重試與終態

錯誤分類的第一個維度是對消費者行為的指示：這個錯誤重試有沒有用。可重試（服務暫時失效、限流、鎖衝突）指示消費者退避後重送；終態（參數錯誤、權限拒絕、業務規則拒絕）指示消費者停止重試、走修正或人工路徑。這一刀切錯的代價是雙向的：終態錯誤被標成可重試、消費者的 retry 迴圈空轉壓垮服務；可重試被標成終態、暫時性故障變成使用者眼中的永久失敗。

HTTP status 承擔這一刀的粗分類（4xx 終態、5xx 與 429 可重試、見 11.3 的 status 承諾段）、錯誤 body 承擔細分類。兩層要一致 — body 說可重試、status 給 400、中介層跟 SDK 只看 status、消費者的兩層邏輯就互相矛盾。

格式設計：標準與自訂並存的現實

錯誤格式有現行標準、也有大廠自成一格的成熟先例、兩者的設計目標一致：機器可判讀、人類可理解、格式可演化。

RFC 9457 定義 application/problem+json：type（URI）、title、status、detail、instance 五個核心成員、允許 extension members 且要求 client 忽略不認識的欄位（見 11.C35）。兩個設計值得單獨理解：type 用 URI 而非字串 enum、把錯誤種類的命名空間外部化、跨團隊不撞名；「client MUST ignore unknown extensions」是格式的演化條款 — 服務端可以加欄位而不破壞既有消費者、等同錯誤模型的開放封閉原則。

Stripe 的錯誤物件早於這個標準自成一格、分層思路可以直接借用：type 承擔路由層（哪類錯誤、走哪條處理分支）、code 承擔分支層（細粒度機器碼）、param 加 message 承擔 UI 層（哪個欄位錯、給人看什麼）、三個正交欄位讓消費者各層各取所需（見 11.C36）。這個模型還藏著一個結構訊號：idempotency_error 是四個 type 之一 — 冪等衝突在支付 API 是預期常態、錯誤模型要為它保留一級位置（冪等語意主寫在 11.8）。

選標準還是自訂的判準：新 API 從 RFC 9457 起手、拿到現成的演化條款與工具生態；既有 API 有自訂格式且被大量依賴、遷移本身就是 breaking change、務實做法是把 9457 的兩個設計（type 命名空間化、未知欄位忽略條款）補進自訂格式、而非換格式。

錯誤狀態下的系統行為

錯誤模型的最後一段責任是「錯誤發生時、系統還敢做什麼」。Twilio 2013 年計費事故的教訓落在這：關鍵狀態讀不到、自動扣款卻繼續跑、演變成重複扣款（事故時序與冪等閘門的抽象、主寫在 11.8 的反例段）。落到錯誤模型的通用判準：關鍵狀態讀寫失敗的錯誤處理、預設要往「拒絕服務」收斂、而非「帶著壞狀態繼續」— 錯誤分類表裡要有一類「狀態不可信、停止副作用」、它的處理路徑跟一般 5xx 不同。

常見設計錯誤

• 業務失敗包 200：觀測與重試鏈失真、修法見 11.3 的 status 承諾段。
• 錯誤碼用連續數字：code: 1047 無命名空間、跨服務撞號、grep 不到語意 — 用可讀字串或 URI。
• message 當機器介面：消費者 parse 錯誤訊息文字做分支、訊息改字就是 breaking change — 機器分支一律走 type / code。
• 錯誤格式沒有演化條款：第一版沒宣告「未知欄位忽略」、之後每次加欄位都無法確認安全性 — 條款從第一版就寫進文件。

爭論地圖與下一步

本章的分類與格式判準、以 HTTP transport 承載 status 語意為前提。錯誤格式的跨風格交鋒（RFC 9457、envelope 包裝、GraphQL 的 200-with-errors 慣例）是掛在本章的爭論深度文章 backlog（見 模組頁 章節規劃）— GraphQL 把 transport 層 status 跟業務錯誤解耦的做法、在該文攤開、本章不展開。

• 可重試錯誤的消費端行為設計：11.8 API 層冪等設計、6.12 冪等與重放驗證
• 限流錯誤（429）的完整語意：11.9 對外流量語意
• 案例原文：模組十一案例庫

版本擺哪裡：URI、header、日期

版本識別的三個主流位置、差異在「版本被當成什麼」：

URI 版本的優勢是可見性：版本寫在每個請求上、curl 就能切版、快取與路由基礎設施天然按版本分流。代價是「v2」的粒度太粗 — 整個 API 一起翻版、消費者面對的是大遷移、服務端面對的是雙版本長期並行的維護。

header 與 date-based 把版本移出資源身分、版本粒度可以細到單一 breaking change。GitHub 2022 年為 REST API 引入 calendar versioning 時同步給了承諾結構：新版釋出後舊版至少支援 24 個月（見 11.C12）— 支援窗口從隱性期待變成 SLA 式的明文契約、消費者可以據此排遷移計畫。Stripe 的 date-based pin 更進一步：帳號自動 pin 住首次呼叫時的版本、服務端把每個 breaking change 封裝成一個 version change module、response 依時間反向流過模組鏈、轉換成該帳號 pin 住版本的回應 schema — 截至 2017 年累積約 100 個 backwards-incompatible 升級、維持與 2011 年以來每一版相容（見 11.C10；這種「服務端吸收」的成本分配框架見 11.1）。

選型判準回到 11.1 的成本分配：消費者多而異質、值得投資 header / date-based 加服務端吸收層；消費者少而可協調、URI 版本的簡單性划算。另一派主張版本化本身是錯的 — Fielding 的立場是「DON’T」、用 hypermedia 的執行期演化取代版本號（InfoQ 訪談、2014、見 11.C14）；GraphQL 的 versionless 路線是這個方向的工程化實例（見 11.C26、紀律代價的深化見 Schema 演進）。兩者的完整交鋒收在掛本章的「版本策略流派之爭」爭論文章 backlog（見 模組頁）。

Deprecation 的執行工具箱

宣告 deprecation 容易、讓長尾消費者實際完成遷移才是工程問題。公開案例累積出一組執行工具、各自解決通訊鏈的不同斷點：

分階段日期。Slack 收斂四族舊 API 到 Conversations API 時用三個日期各擋一種風險：宣告日起算、五個月後新建 app 拿不到舊方法（掐斷新增量）、十三個月後全面停用（處理存量）（見 11.C16）。先斷增量再清存量的順序讓債務停止成長、清理才有終點。

In-band warning。同一案例的過渡期、呼叫舊方法會在 response 收到 method_deprecated warning 加退場日期 — 訊號出現在開發者一定會看的地方（自己的 response）、觸及率高於任何公告渠道。

Brownout。GitHub 廢止 Git 操作密碼認證前、在兩個預告時窗暫時停用再恢復（見 11.C13）— 沒讀公告的長尾消費者、只有短暫的真實故障能觸達、且是在低風險時窗先遭遇明確失敗、不是在強制日全面斷線。

Sunset header。RFC 8594 定義用 HTTP header 宣告退場時點的機器可讀層（見 11.C15）— Informational 地位、實務採用有限、Slack 與 GitHub 都沒等它。引用價值是概念完整性：通訊鏈該有一層給程式讀、具體形式各家自選。

工具的組合邏輯：公告觸及會讀公告的人、in-band warning 觸及在開發的人、brownout 觸及所有人。退場計畫的完整度檢查是「三類人各被哪個工具覆蓋」。

退場的量測與到期行為

退場決策要有數據：舊版的呼叫量、呼叫方分布、衰減曲線。量測的基礎設施跟 04 觀測 共用、版本維度要進 metrics label。到期行為的設計原則承接 11.1 的違約模式分析：到期回明確錯誤、而非靜默改變語意 — Facebook Graph v1.0 的靜默語意切換反例在該段完整展開。

版本策略運作不良的訊號可以從三個地方讀：舊版呼叫量長期不衰減（deprecation 工具箱沒有形成遷移壓力）、多數帳號 pin 死在首版（新能力的價值不足以驅動升級、或遷移成本被低估）、每次退場都演變成客訴事故（通訊鏈有一類消費者始終沒被覆蓋）。三個訊號指向的修法分別是執行工具、版本內容、通訊覆蓋 — 對症下藥、而非一律延長支援期。

下一步路由

• 什麼算 breaking、變更怎麼審：11.6 向後相容的變更紀律
• 承諾成本結構的上游框架：11.1 API 作為服務邊界的責任
• 退場量測的觀測基礎：04 可觀測性平台
• 案例原文：模組十一案例庫

Breaking 的定義要明文、且比直覺寬

變更紀律的地基是一份「什麼算 breaking」的明文清單、而且清單的範圍比直覺預期的寬。直覺抓得到的：刪欄位、改型別、改必填。直覺常漏的：改欄位預設值（消費者依賴舊預設）、改錯誤碼（消費者的分支邏輯建在上面）、改回應時序（輪詢邏輯依賴）、收緊驗證規則（昨天合法的請求今天 400）。反向的參照是 Stripe 明文的相容變更清單 — 新增資源、新增 optional 參數、新增 response property、property 順序改變、opaque ID 的長度格式改變、新增 event type（見 11.C11）：清單同時劃出「這些軸服務端保留自由」、消費者不可依賴。兩份清單（breaking 清單、相容清單）合起來才是完整的契約邊界、只有其中一份時灰色地帶照樣存在。

紀律的三個放置層：格式、工具、流程

相容紀律可以放在三個層、強度遞減、適用情境不同。

格式層：相容性做成編碼格式的性質、違規在技術上不可行或立即失效。protobuf 是代表 — field number 一旦投入使用即不可變更、刪除必須 reserve、重用會造成解碼歧義與資料損毀（見 11.C28）；官方文件直接把 schema 變更分成 wire-safe、wire-unsafe 與 conditionally wire-compatible 三類 — 判定規則明文化之後、不依賴資深工程師在場。GraphQL 的 versionless 紀律同型、案例判讀把它歸納為三個支柱：只加不改、deprecation 標注、nullable 預設、由 schema 語言承載（C26 的判讀整理、觀察層見 11.C26；GraphQL 內部機制的深化見 Schema 演進）。

工具層：相容檢查做成 CI gate、在 merge 前擋下。Buf 的 breaking detection 對比歷史 schema、在 merge 前擋下破壞性變更、規則分四級（FILE、PACKAGE、WIRE_JSON、WIRE）、文件明言「Catching this before merge is the point」（見 11.C29）。從四級的分級設計可以抽出選級判準（C29 判讀）：選符合消費者實際依賴的等級 — 只走 wire 的消費者用 WIRE、有 generated code 依賴的要更嚴的級。這條主張可以推廣成本章的通用判準：相容性檢查的粒度是產品決策、不是工具預設 — 檢查太嚴、內部重構寸步難行；太鬆、消費者實際依賴的層沒被保護。HTTP+JSON 的對應工具是 OpenAPI diff 類檢查、把 spec 當 schema 跑同樣的 gate（工具治理見 11.10 規範治理）。

流程層：格式與工具都蓋不到的語意變更（預設值、時序、驗證規則）、由變更審查流程把關 — review checklist 上有「對照 breaking 清單」一項、重大變更走 API design review。流程層是三層裡唯一蓋得住全部變更類型的、也是唯一依賴人自覺的 — 所以務實的配置是三層疊加：格式層鎖結構、工具層鎖 spec、流程層鎖語意。

到期與豁免的邊界設計

紀律需要兩個邊界條款才能長期運作。到期行為：宣告過的 breaking 變更到期執行時、回明確錯誤而非靜默改語意 — 原則的完整推導與 Facebook Graph v1.0 的反例展開見 11.1 的違約模式段；審查視角的增量是把到期行為當成變更提案的必填欄位、跟 brownout 這類預告機制（見 11.C13）一起在 review 時就定案、而非退場當天即興。豁免宣告：每次變更公告要明列「誰不受影響」— GitHub 的密碼認證廢止同時明列 2FA 使用者、GHES、GitHub App 不受影響、讓多數消費者第一段就能停止閱讀、注意力留給真正要動的人。

判讀訊號

四個訊號的排查有方向性：前一個的修法是後三個的前提 — 清單沒立好、CI 粒度沒有校準對象；粒度爭議反覆出現、多半是清單跟消費者依賴的實況脫節。從清單開始修、工具與流程的爭論通常跟著消失。

下一步路由

• Breaking 決定要做之後的分期與退場：11.5 版本策略與 deprecation
• 消費端驗證（consumer-driven contract test 把「誰依賴什麼」顯性化）：6.10 契約測試
• 相容檢查工具進 CI 的組織面：11.10 API 規範治理
• 案例原文：模組十一案例庫

分頁：offset 的兩個失效模式

offset 分頁（?page=3&limit=50）的介面直觀、失效有明確的機制。Slack 的工程紀錄給了一手描述：其一、LIMIT / OFFSET 深頁掃描 — 資料庫要掃過並丟棄前面所有列、頁數越深成本越高；其二、page window 漂移 — 高頻寫入下、兩次請求之間有新資料插入、消費者會看到跳項或重複（見 11.C37）。

Slack 的解法是遷移到 opaque cursor：介面收斂為 cursor 加 limit、回傳 next_cursor、cursor 內容 Base64 編碼、消費者不可解析。opaque 這個性質是設計重點 — 分頁狀態的表示權留在 server 端、消費者不能解析就不能依賴內部格式、server 可以自由更換底層策略（keyset、shard 位置、甚至混合）而不動介面。同一份紀錄明列了付出的代價：失去 total count 與跳頁能力 — 這是明示的產品決策、選 cursor 前要跟產品端確認「第 N 頁」跟「共幾筆」是不是真需求。

判準：資料量小、寫入頻率低、產品要跳頁 — offset 合理且便宜；資料量大或寫入頻繁 — cursor、並從第一版就 opaque（先給透明 cursor 再收緊、又是一次 breaking change）。offset、cursor、keyset 的完整交鋒與「cursor 不透明性算承諾還是逃生門」的爭議、收在掛本章的分頁爭論文章 backlog（見 模組頁）。

批次操作：部分失敗是預設、不是例外

批次介面（一次建立 100 筆）的核心設計問題是部分失敗語意：第 37 筆驗證失敗、前 36 筆算什麼。三種可承諾的語意、各有成立情境：

• 全有全無：包成一個 transaction、任一筆失敗全部回滾。語意最乾淨、消費者重試最簡單（整包重送）；成本是 server 端要撐住大 transaction、且單筆失敗導致整批回滾的體驗、在大批次下代價過高。
• 獨立處理、逐筆回報：回應是跟請求等長的結果陣列、每筆自己的成功或錯誤。務實預設、但消費者的重試邏輯變複雜 — 要能只重送失敗子集、這又要求逐筆操作冪等（11.8 的主題）。
• fail-fast：處理到第一個錯誤即停、回報已處理數。適合順序有意義的批次（匯入）、消費者從斷點續傳。

判準是消費者的重試能力與資料的順序性；唯一的反模式是不宣告 — 文件沒寫部分失敗語意的批次介面、消費者只能拿 production 事故來逆向工程。

長時操作：把「進行中」實體化

超過請求逾時預算的操作（報表、匯入、佈建）、介面要回的是「工作的身分」而非結果。Google AIP-151 是這個模式的系統化規範：長時方法回傳 Operation resource、client 輪詢其 done / response / error 狀態、回應型別事先宣告、operation 約 30 天過期（見 11.C44）。比起裸的 202 加 Location、Operation resource 的增量價值在統一：所有長時操作共用同一個查詢介面、client 寫一套 polling 邏輯到處用；done=true 直接回的 validate-only 條款、示範了用同一個介面模式涵蓋同步捷徑的手法（C44 判讀）。

設計時要明訂的三件事：operation 的生命週期（查詢結果保留多久 — AIP 選 30 天）、輪詢的節奏指引（配合 11.9 的限流語意、避免消費者用 while-true 打爆查詢端點）、以及完成通知的替代路徑（webhook 回呼、屬 styles/realtime 的 backlog 範圍）。

常見設計錯誤

• 透明 cursor：消費者 decode 後依賴內部欄位、底層換策略即斷 — 從第一版就 opaque。
• 批次語意未宣告：部分失敗行為靠消費者猜。
• 長時操作同步等：把 5 分鐘的工作掛在一條 HTTP 連線上、逾時、重試、重複執行三連發。
• list 端點無上限：limit 沒有 max、一個請求拉全表 — 上限是集合介面的基本流量防線（完整語意見 11.9）。

下一步路由

• 批次重試的前提：11.8 API 層冪等設計
• 深頁掃描背後的資料庫機制：1.13 Query 反模式
• 案例原文：模組十一案例庫

冪等是協作、三種失敗點是分析骨架

冪等契約由兩端共同履行、server 端的 replay 快取只解一半。Stripe 的設計文章把失敗拆成三個時點 — 連線建立前失敗（重送安全、根本沒到 server）、執行中失敗（server 要決定 replay 什麼）、回應遺失（操作成功了、消費者不知道）— 並明確劃出 client 端的責任：exponential backoff 加 jitter、否則故障當下的集體重試會壓垮服務（見 11.C38）。三個時點是設計冪等機制時的分析骨架：replay 行為要對三種情況分別給出答案。

冪等契約的條款清單

冪等契約要承諾的條款有五項；逐條的基準參照是 Stripe 的 API reference — 目前公開文件裡最明確的一份（見 11.C39）：

• key 由誰生成：消費者生成、建議 UUIDv4、上限 255 字元 — key 代表「消費者眼中的同一次操作」、只有消費者知道邊界。
• 存多久：至少 24 小時、逾期同 key 視為新請求 — 保存期是承諾、要明文、消費者據此設計重試窗口。
• replay 回什麼：首次請求的 status code 加 body、包含 500 也照樣快取重放。這條最容易自建做錯 — 快取的是「該次請求的結局」、而非「成功結果」；只快取成功的實作、會在 server 錯誤後讓同 key 重試觸發第二次執行、冪等保證在最需要它的時刻失效。
• 衝突怎麼回：同 key 不同參數直接報錯 — key 綁定請求語意、防止被當 session id 濫用。Stripe 的錯誤模型甚至為此保留一級錯誤型別 idempotency_error（見 11.4）。
• 作用範圍：只限 POST — GET 與 DELETE 的冪等由 method 語意承諾、不需要 key。

無標準的現況：條款逐家不同

冪等鍵是「業界事實標準先行、正式標準停滯」的典型。IETF 的 Idempotency-Key header draft 推進到第 7 版後過期、狀態 expired（見 11.C40）— 引用它只能引語意骨架、不能宣稱 RFC。後果是各家條款實際有差、對照 PayPal 可見三個維度（見 11.C41）：header 命名不同（PayPal-Request-Id）；replay 語意不同 — Stripe 回「首次結局快照」、PayPal 回「前次請求的最新狀態」、後者對非同步操作友善、但失去 exactly-once 回應保證；契約精確度不同 — Stripe 承諾 24h、PayPal 的保存期寫「a period of time」。設計自己的 API 時、這三個維度就是條款檢查表；整合外部 API 時、逐家讀條款、拿 Stripe 的語意假設去打 PayPal 會踩錯。

反例：冪等閘門缺席的內部迴圈

冪等的適用範圍大於對外 header — 系統內部會自動重試的 side-effect 動作、同樣需要閘門。Twilio 2013 年計費事故的時序（C45 觀察層）：Redis 故障讓餘額資料遺失歸零且無法寫回、auto-recharge 在「餘額為零、扣款成功、餘額寫不回去」的循環中對約 1.4% 客戶重複扣款（見 11.C45、反例）。把事故抽象成冪等語言（判讀層）：扣款的觸發條件在執行後未被消除、等效於無限重放的非冪等操作。通用形式：冪等閘門 = 執行紀錄先寫、後執行副作用；配套的 fail-safe = 狀態寫不進去、就不准產生金流級 side effect。對外的 idempotency key 只是這個通用形式在 API 邊界的特例。

判讀訊號

這四個訊號有共同的檢查入口：把五項條款清單當 checklist 對照自家文件、缺哪條補哪條 — 客訴類訊號（第一列）是條款缺位的滯後指標、等它出現才補、代價已經發生。

下一步路由

• 冪等衝突的錯誤表達：11.4 錯誤模型設計
• retry 節奏與限流的互動：11.9 對外流量語意
• 內部交付語意（at-least-once 下的去重處理與驗證）：3.4 consumer 設計、6.12 冪等與重放驗證、Processing Semantics 知識卡
• 案例原文：模組十一案例庫

承諾邊界：配額資訊是預警、不是保證

限流語意的第一條設計原則是明確劃出承諾邊界。IETF 的 RateLimit header draft（active、v11、引用需標狀態）把配額資訊拆成兩個 header — RateLimit-Policy（靜態政策：quota、window、partition key）與 RateLimit（動態剩餘量）— 並明文「client MUST NOT assume 正配額保證下一請求會被服務」（見 11.C42）。兩個設計都值得借用：政策與即時狀態拆開、政策可快取、狀態逐請求變動；informational only 條款把配額 header 定位成禮貌性預警而非 SLA — 服務端保留在異常流量下提前收緊的權利、消費者的正確姿勢是把 429 處理寫對、而非精算剩餘配額。

429 與 Retry-After：被擋之後的契約

拒絕本身也是介面。可承諾的最小集合：status 用 429（讓消費者與中介層知道「可重試、但要等」、跟終態 4xx 區分、錯誤分類見 11.4）；Retry-After 給等待時間、且服務端說到做到 — 消費者等滿再來就該被服務、否則 Retry-After 淪為裝飾、消費者退回盲目退避。GitHub 的文件在這條上有可指出的語意瑕疵：超限回 403 或 429、文件未明確劃分兩者的使用時機（見 11.C43）— 消費者要同時處理兩種 status、分支邏輯多一倍。設計新 API 時可直接採納的判準：拒絕的 status 只用一個。

消費端的配套是 backoff 加 jitter（同 11.8 的 retry 責任）— 限流語意跟冪等語意在消費端匯合：429 之後的重送、要嘛操作本身冪等、要嘛帶 idempotency key。

單一維度擋不住真實濫用

GitHub 的雙層限流揭露配額設計的一個實證：primary limit（每小時總額度）之外、還有 secondary limits — 並發上限、單端點吞吐、CPU 時間、內容建立速率（見 11.C43）。存在本身就是判讀：單一維度的請求計數擋不住真實濫用模式 — 額度內的高並發、額度內的單端點轟炸、額度內的重查詢。設計配額時從「要保護什麼資源」反推維度、而非從「一小時幾次」起手。

同一案例也記錄了 header 命名的遷移期現實：GitHub 的 x-ratelimit-* 是前標準時代的事實慣例、與 IETF 標準命名並存 — 新 API 該出標準 header、消費端 SDK 仍要能讀 x- 系、兩者會共存很久。

成本模型：per-request 假設的破裂

「一個請求算一次」的配額假設、在請求成本不是常數的風格下失效。GitHub 的 GraphQL API 為此建立 point system：依 query 的展開規模計算成本、配額按點數計、另設結構上限當靜態防線、且成本對消費者可預估可查詢（參數細節與機制展開主寫在 GraphQL 執行成本與攻擊面、案例 11.C19）。判準層的收穫有兩條：請求成本變動大的介面（GraphQL、批次、重查詢）、配額要計成本而非計次；成本模型本身要對消費者透明可預估 — 消費者無法預估成本、就無法設計合規的 client。執行成本的機制細節（resolver 展開、N+1、persisted queries）主寫在 GraphQL 執行成本與攻擊面。

常見設計錯誤

• 限流回 500：消費者把它當服務故障告警、但成因是自身超額 — 語意錯位、429 才能觸發正確的消費端行為。
• Retry-After 不準：等滿再來還是被擋、消費者棄用該 header、生態退化成盲目重試。
• 配額只在文件、不在 header：消費者無法程式化管理額度、只能在被擋下後才發現額度邊界。
• 無 burst 設計：嚴格平滑限流把正常的批次行為（頁面載入拉 10 個資源）也擋掉 — 政策要區分持續超額與瞬時尖峰。

下一步路由

• 執行機制與 gateway 層：05 部署平台與網路入口、5.3 Load Balancer 合約（限流實作章屬 05 backlog）
• 高峰期的容量面：9.11 高峰事件準備
• 429 後的重送安全：11.8 API 層冪等設計
• 案例原文：模組十一案例庫

治理模式三型

提案制把規範做成有生命週期的提案系統。Google AIP 用編號提案累積規範、進入 Reviewing 需編輯核可、Approved 需兩位非作者 approver 簽核、TL 是 escalation 終點（見 11.C46）— 本質是把 IETF RFC 流程內化到單一組織、換到的是每條規範的決策可追溯、可演進。結構上仍是中心化：社群貢獻是輸入、不是決策權。

Guild 制的重點是規範外的配套。Zalando 在 8,000+ 服務、300+ 團隊的規模下、由 API Guild 擁有 guidelines 的 ownership、API spec 以 PR 提交 peer review、重要 API 由 Guild 介入、再加 API Portal 集中可發現性（見 11.C47）。這個案例的關鍵在完整性：guidelines（文件）、Guild（人）、Zally（自動化）、Portal（可發現性）四件缺一環、規範就退化成書架文件。

分軌制是規模的誠實妥協。Microsoft 的 guidelines repo 內含核心軌加 Azure 與 Graph 兩條產品線專屬軌（見 11.C48）— 單一 guideline 蓋不住差異巨大的產品線、規範沿組織邊界分化。它跟 Zalando「像同一團隊設計」的理想構成一組張力：統一到什麼粒度是治理設計的自變數、不是越統一越好 — 分軌的成本是消費者跨產品線時要學兩套慣例、統一的成本是規範遷就最大公約數而失去產品線的貼合度。

工具層：規範進 CI

治理成本的關鍵優化是把可機檢的規則從人工 review 前移到 CI。OpenAPI 生態的代表是 Spectral（內建 OpenAPI 與 AsyncAPI rulesets、組織自帶自訂規則）跟 Zalando 的 Zally（預設 ruleset 直接執行 Zalando guidelines）；兩者的生態軌跡本身是選型訊號 — Spectral 有 8.1k dependent projects 且持續發版、Zally 的 release 停在 2022：兩個資料點指向「通用 linter 加組織自帶 ruleset、比單一組織專用 linter 更能存活」的判讀（C49 判讀、樣本有限、見 11.C49）。protobuf 生態的對應物是 buf 的 lint 與 breaking check（11.6 的工具層）。工具的邊界要誠實：linter 蓋得住命名、結構、必填欄位；蓋不住語意（這個資源建模合不合理）— 語意層仍回到 design review、工具的價值是讓人的注意力只花在語意上。

失敗的模式：文件不會自己活著

治理缺席時規範的結局有公開的乾淨反例：White House API Standards — 內容完整的 RESTful guidelines、34 個 commit 後停止維護、2022 年正式 archived（見 11.C54、反例）。文件品質過關、缺的是 Zalando 四件套裡的另外三件：沒有 owner、沒有 review 流程、沒有工具。跟 C47 並排的結論：規範的存活取決於配套組織機制、不取決於文件寫得多好 — 評估自己組織的規範健康度、先問 owner 是誰、上次更新是何時、違反規範的 API 會在哪一關被擋。

採現成標準、還是自建規範

治理的另一個選項是直接採跨組織標準、讓別人維護規範。JSON:API 的價值主張就放在這 —「stop the bikeshedding」、用現成慣例消除團隊內的格式爭論（見 11.C50）。反面的量尺是 OData：OASIS 標準加 ISO 認證、生態仍萎縮、Netflix 與 eBay 離場（見 11.C51、反例、退場分析屬二手來源）— 標準機構背書不能替代生態動能、採標準前看的是 marquee adopter 與工具鏈、而非認證章。務實的中間路線是「採描述格式標準、自建設計規範」：OpenAPI 描述介面、AsyncAPI 補事件面（兩者的生態關係見 11.C52 與 11.C53）、設計判準寫成自家 guidelines 配 Spectral ruleset。標準化嘗試的完整興衰史收在 styles/standards 流派層 backlog（見 模組頁）。

判讀訊號

治理訊號的判讀跟前面各章不同、歸因要先分「機制缺席」還是「機制失效」：前兩個訊號是缺席（規範或執行環節根本沒建）、對照四件套補件；後兩個是失效（建了但跟組織實況脫節）、修內容而非加機制 — 失效時再疊新機制、只會累積更多沒人遵守的規則。

下一步路由

• 相容性檢查的工具細節：11.6 向後相容的變更紀律
• 各章判準是治理的內容物：從 11.1 依序讀
• 案例原文：模組十一案例庫