紀律一：只加不改

加法安全的機制基礎是 client 的顯式選取：REST 回應裡新增欄位、所有消費者都會收到（多數忽略、少數壞掉）；GraphQL 新增欄位、沒請求它的 query 完全不受影響。這讓「加」在 GraphQL 是真正的零風險操作 — 但「改」與「刪」的風險跟任何風格相同、versionless 的意思是把這兩類操作用紀律排除、而非讓它們變安全。

隱藏帳單是 schema 只增不減的膨脹：欄位一旦發布、有沒有人用、用的人肯不肯走、都要靠量測回答。GraphQL 在這點上有結構優勢 — client 逐欄位聲明取數、server 端可以精確統計每個欄位的使用量與呼叫方、比 REST 的「整包回應、不知道誰讀了哪個欄位」可觀測得多。這個優勢要主動兌現：欄位使用量進 metrics 是 versionless 能長期運作的基礎設施前提、對應 11.5 退場量測段的同一條原則。

紀律二：deprecation 標注

@deprecated directive 把退場資訊放進 schema 本身：欄位標注後、introspection 與工具鏈（IDE 自動完成、linter）會對新的使用者顯示警告、既有 query 照常運作。這是 deprecation 執行工具箱 裡 in-band warning 的 schema 層版本 — 訊號出現在開發者寫 query 的當下、時點比 response warning 更早。

隱藏帳單是「標注不等於退場」：@deprecated 沒有強制力、沒有日期語意、long tail 消費者可以永遠不動。實務上的補法是把欄位使用量量測跟 deprecation 標注綁在一起 — 標注後看用量衰減曲線、歸零才真正刪除；用量不動、回到 11.5 的遷移壓力工具。

紀律三：nullable 預設

GraphQL type system 把每個欄位預設為 nullable、官方理由包含後端局部故障與細粒度授權（C26 觀察層）：某個 resolver 失敗或某個欄位被權限拒絕時、該欄位回 null、response 的其餘部分照常返回 — 局部失敗不炸掉整個回應。這個設計跟演進的關係在第三層：nullable 欄位的移除路徑比 non-null 平緩（消費者本來就要處理 null、欄位「永遠 null」是移除前的可用中繼態）。

隱藏帳單是 null 語意的多義：欄位是 null、消費者無法區分「值就是空」「resolver 失敗」「權限拒絕」三種情況 — 錯誤資訊要靠 response 的 errors 陣列補充、而這正是 GraphQL 把 transport status 與業務錯誤解耦的設計（錯誤格式的跨風格交鋒、掛在 11.4 的爭論文章 backlog）。schema 設計的實務判準：業務上不可能缺席的欄位（id、type）明文標 non-null、其餘保留 nullable 預設 — 全部標 non-null 換到的型別安全、會在第一次局部故障時以整包 response 失敗的形式付還。

versionless 是承諾結構、不是免維護

三個紀律合起來看、versionless 的實質是把版本管理的工作換了位置：版本號消失、換來的是欄位級的使用量量測、deprecation 生命週期管理、null 語意設計三項常態工作。跟 11.5 的日期版本方案相比、差異在粒度 — 日期版本以「版本」為單位管理遷移、GraphQL 以「欄位」為單位；粒度變細讓大翻版消失、也讓管理點的數量成長一個量級。組織層的判讀：schema 治理（誰能加欄位、誰審 deprecation、linting 進 CI）承擔的角色跟 11.10 的 guidelines 治理同構、schema registry 類工具是這一層的基礎設施。

no-versioning 立場的跨流派交鋒（Fielding 的 hypermedia 路線、Stripe 的 date-based 路線、GraphQL 的欄位粒度路線）、收在掛 11.5 的版本策略爭論文章 backlog（見 模組頁）。

下一步路由

• 跨風格的變更紀律框架：11.6 向後相容的變更紀律
• 執行層的代價：執行成本與攻擊面
• 組織層的進退：公開 API 的 GraphQL 進退
• 案例原文：模組十一案例庫

N+1：從偶發問題變成預設行為

resolver-per-field 的執行模型讓 N+1 從查詢寫壞才發生的偶發問題、變成不做處理就必然發生的預設：列表的每個元素各自觸發子欄位的 resolver、一層巢狀就是一輪 N 次資料庫存取。11.C24 記錄了官方生態的回應方式 — batching 做成基礎設施而非優化技巧：DataLoader 把單一執行 frame 內的個別 load 合併成 batch、概念源自 Facebook 2010 年的內部 Loader API、早於 GraphQL 開源；GitHub 2016 年上線 GraphQL 時、技術棧 day one 就帶著 Shopify 維護的 graphql-batch。判讀：評估 GraphQL 的建置成本時、dataloader 層是基礎配備、不是後期優化項 — 缺少它的 GraphQL 服務、第一個帶列表的巢狀 query 就會對資料庫造成 N 倍讀放大。

成本計點：限流模型的被迫重建

請求成本不是常數的直接後果是 per-request 限流失效。11.C19 記錄了 GitHub 的完整應對：對每個 query 依 connection 展開計算 point、每小時 5,000 點；另設 500,000 node 上限與分頁參數 1-100 的限制；消費者可事前預估、也可事後查 rateLimit.cost。動靜兩層各擋一類風險（C19 判讀）— 成本計點管累積用量、node 上限管單發炸彈；成本模型對消費者透明可預估、是它能當契約的前提（對外流量語意的承諾邊界、見 11.9）。自建 GraphQL 公開 API 時這一整層都要自己蓋 — 這是 REST 世界拿現成 gateway 限流就能用的能力。

Introspection：型別系統是雙面刃

introspection 讓 schema 自我描述、工具鏈（IDE、codegen、文件生成）全建立在它上面 — 同一個能力對攻擊者是免 fuzzing 的偵察工具。11.C25 是具體實證：某電商平台的第三方服務暴露 GraphQL 端點、introspection 開啟、研究者列舉 schema 後發現未加驗證的 CreateAdminUser mutation、直接取得管理權限。REST 世界要靠字典檔猜端點、GraphQL 用型別系統直接把地圖交出去。加上授權模型的難度 — 每個 field 都要各自做授權檢查、且授權檢查本身也會 N+1（C22 觀察）— GraphQL 的攻擊面治理是欄位粒度的、middleware 式的單點防護模型在結構上對不上。

Persisted queries：介於全開與撤退之間

執行成本與攻擊面的問題有一條收斂路線：把 named operations 存在 server 端、對外只暴露操作 ID、完全不接受任意 query。11.C27 把這條路線推到論證的極端 —「GraphQL 不該直接暴露在公網、該當 server-side 查詢語言用」；來源是販售此方案的 vendor、立場要標明、但攻擊面描述與 C22、C25 獨立互證。persisted queries 的效果是把 GraphQL 的彈性收回開發期：開發時保有 client 聲明取數的 DX、上線後對外面積等於一組預先審核過的操作 — 成本可預算、introspection 可關閉、任意 query 的攻擊面消失。代價是把「第三方自由組合查詢」這個公開 API 的賣點一起收掉 — 對內部 client 幾乎是純收益、對開放平台則等於換了一種產品。

判讀訊號

資料庫讀放大跟 API 請求量的比值持續高於預期、先查 dataloader 覆蓋率而非加 read replica；限流被繞過的事故發生在「配額內的重查詢」、代表還在用 per-request 模型計量；滲透測試報告第一項是 introspection 開啟、關掉它之後要接著問「欄位級授權有沒有做」— introspection 只是地圖、權限缺口才是漏洞本體。

下一步路由

• 判準層的流量語意與承諾邊界：11.9 對外流量語意
• schema 層的演進紀律：Schema 演進
• 這些成本在組織層的總帳：公開 API 的 GraphQL 進退
• 案例原文：模組十一案例庫

採用：動機要能量化

11.C18 記錄了 GitHub 2016 年的採用動機、關鍵在它的可量化性：既有 REST API 佔資料庫層超過 60% 的請求、且 over-fetching 與 under-fetching 並存 — 送太多資料、又缺消費者要的資料。這是基礎設施成本層的痛、不只是開發體驗敘事。判讀：GraphQL 的採用決策值得用同樣的標準檢驗 — 說得出「哪個資源層指標會因 client 聲明取數而改善」、動機成立；只說得出「前端想要彈性」、先確認這個彈性有多少會被實際用到（消費者形狀判準、見 11.2）。

穩態一：雙軌共存

GitHub 的十年後狀態記錄在 11.C20：官方立場是 REST 與 GraphQL 並行、依情境選用、且明文說明功能覆蓋不對等 — 某功能可能只在其中一個 API 支援。這是「新風格取代舊風格」預期的反面實證：兩套 API 各自累積消費者之後、任何一套的退場都是大規模 breaking change（成本結構見 11.1）、共存從過渡狀態變成永久狀態。雙軌的隱藏成本是每個新功能的「要不要兩邊都做」決策與文件、SDK、支援的雙倍表面積 — 採用前把這筆帳算進去、雙軌不是免費的中間路線。

穩態二：平台強制的 all-in

11.C21 記錄了反方向的極端：Shopify 2024 年把 REST Admin API 標為 legacy、新上架 app 強制只用 GraphQL、配套 rate limit 加倍與 connection query 成本降 75%。這條路線的成立條件寫在案例的結構裡 — Shopify 對 app 生態有審核強制力（新 app 不遷就上不了架）、遷移壓力不靠說服。判讀有兩層：對平台方、all-in 的前提是強制力、沒有 app store 式關卡的組織複製這個策略只會得到雙軌的事實與 all-in 的公告；對生態方、成本降 75% 的配套反向印證了執行成本（前一篇 的計點模型）是 GraphQL 採用的隱含稅 — 平台要自己吸收一部分、生態才動得起來。

撤退：兩類動機、兩個教訓

撤退案例分兩類、動機幾乎正交。執行成本類（11.C22、反例）：六年使用者列出的代價全在執行期與安全面 — 欄位級授權、成本不可預測、解析層攻擊面、防禦性 dataloader；撤退判準句是「控制得了 client、就不需要 GraphQL 的彈性」（C22 判讀核心句）。開發體驗類（11.C23、反例）：同一資料形狀在五層重複宣告、三層 codegen 產出 8,200 行型別檔拖垮 IDE、遷移到 tRPC 後淨減 1,608 行；作者自列的前提是全 TypeScript 同倉 — schema 作為跨團隊契約的價值、在單團隊同構技術棧下變成純開銷。

兩類撤退指向同一條邊界的兩側：GraphQL 的 schema 中介層、價值在「跨團隊 / 跨 client 的契約協調」— 消費者異質且不受控、彈性有買家、中介層成本值得；消費者單一且同構、彈性沒有買家、中介層是稅。C23 的 tRPC 面向（型別共享的前提與代價）主寫在 rpc-revival 流派層（backlog）。

中間路線與適用邊界

全開與撤退之間有 persisted queries 的收斂路線（案例 11.C27；機制與 vendor 立場標注見 執行成本篇 的 persisted queries 段）：內部保留 GraphQL 的開發彈性、對外只暴露預審操作。把四種結局加中間路線並排、適用邊界收斂成三個問句：消費者是誰、有多異質（單團隊同構 → 撤退案例的前車）；對生態有沒有強制力（沒有 → 雙軌是實際終點、all-in 只是公告）；執行層的計點限流、欄位授權、dataloader 誰來蓋（沒人蓋 → 攻擊面與容量問題按 執行成本篇 的清單逐項到期）。

下一步路由

• 選型判準層：11.2 風格選型總覽
• 執行層機制：GraphQL 執行成本與攻擊面
• schema 層紀律：Schema 演進
• 案例原文：模組十一案例庫

觀察

GitHub 2016 年公開 GraphQL API 時明言：既有 REST API 負責超過 60% 的資料庫層請求、且同時「送太多資料、又缺消費者需要的資料」（over-fetching 與 under-fetching 並存）。技術棧為 graphql-ruby 加 Shopify 的 graphql-batch、公告前已在 production 運行、前後端用 Relay 協作。

判讀

採用動機是可量化的基礎設施成本（DB 層負載）、不只是 DX 敘事 — 這讓它成為「什麼規模的 over-fetching 痛才值得換風格」的錨點案例。graphql-batch 出現在 day-one 技術棧、顯示 N+1 是第一天就要面對的問題、不是後期優化。

對應大綱

公開 API 的 GraphQL 進退（anchor、已引用）、11.2 風格選型交叉。GitHub cluster 之一（C18-C20）。

下一步路由

回 模組十一案例庫。

引用源

• The GitHub GraphQL API（GitHub engineering blog、2016）

觀察

GitHub GraphQL API 依 connection 展開的請求數對每個 query 計 point（總請求數除以 100、最低 1 點）、user 每小時 5,000 點、Enterprise 10,000 點；另有 500,000 node 上限與 first / last 參數 1-100 的限制；client 可事後查 rateLimit.cost、也可事前預估。

判讀

一個 request 的成本在 GraphQL 下不再是常數 — per-request rate limiting 的假設被打破、平台被迫發明成本模型。node 上限與分頁參數上限是防執行爆炸的靜態防線、動靜兩層並存本身就是教學重點。

對應大綱

執行成本與攻擊面（機制主寫、已引用）、11.9 對外流量語意（現象層、已引用）。GitHub cluster 之一。

下一步路由

回 模組十一案例庫。

引用源

• Rate limits and node limits for the GraphQL API（GitHub docs）

觀察

GitHub 官方文件明言「不需要獨佔使用其中一個 API」；GraphQL 建議用於減少請求數與精準取數（mobile、巢狀關聯）、REST 建議給熟悉傳統 HTTP 慣例者；並承認「某功能可能只在其中一個 API 支援」。

判讀

2016 年的採用者（C18）在多年後的穩態是雙軌並行、功能覆蓋不對等 — 這是「大平台採用 GraphQL 的長期終點是共存」的最直接證據、支撐「進退」章的結論框架。跟 Shopify 的 all-in 策略（C21）形成兩個極端。

對應大綱

公開 API 的 GraphQL 進退（anchor、已引用）、11.2 風格選型（共存段、已引用）。GitHub cluster 之一。

下一步路由

回 模組十一案例庫。

引用源

• Comparing GitHub’s REST API and GraphQL API（GitHub docs）

觀察

Shopify 2024-10 宣告 REST Admin API 標為 legacy、不再開發新功能；2025-04-01 起新上架 app 必須只用 GraphQL；配套措施包含 rate limit 加倍、connection query 成本降 75%；部分新能力（2,000 product variants、Metaobjects）只在 GraphQL 提供。

判讀

跟 GitHub 的共存路線（C20）相反 — 用「新功能只上 GraphQL」製造遷移壓力。判準案例：「平台對生態系有強制力時才可能 all-in」。成本降 75% 的配套也反向印證 cost-based limiting 是 GraphQL 採用的隱含稅。

對應大綱

公開 API 的 GraphQL 進退（anchor、已引用）、11.2 風格選型（共存段、已引用）。Shopify cluster（與 C24 graphql-batch 相關）。

下一步路由

回 模組十一案例庫。

引用源

• All in on GraphQL（Shopify partners blog、2024）

觀察

作者（六年 GraphQL 使用經驗）列舉：每個 field 都要各自做授權檢查；128 bytes 的惡意查詢可耗 10 秒 CPU；畸形 directives 造成 2,000 倍記憶體放大；N+1 迫使處處防禦性套 Dataloader、且授權檢查本身也會 N+1。建議控制得了 client 的團隊改用 OpenAPI 3 REST（FastAPI / tsoa / TypeSpec）。

判讀

代價清單全部落在執行期與安全面 — 跟採用文宣的 DX 敘事正交、逐條對應「執行成本與安全」章的大綱（授權下推到 field、成本不可預測、解析層攻擊面）。撤退判準的核心句：「控制得了 client、就不需要 GraphQL 的彈性」。

對應大綱

執行成本與攻擊面 與 公開 API 的 GraphQL 進退（皆已引用）、11.2 風格選型（消費者形狀軸、已引用）。反例。

下一步路由

回 模組十一案例庫。

引用源

• Why, after 6 years, I’m over GraphQL（Matt Bessey、2024）

觀察

痛點是 double declaration：同一資料形狀要在 Prisma / Nexus / GraphQL operations / codegen types / client queries 五層宣告；三層 codegen 產出 8,200 行型別檔、常需重啟 VSCode language server；GraphQL 依賴 81.2kb、tRPC 23.7kb；Apollo normalized cache 在 mutation 後常態性要手動 refetchQueries。遷移後淨減 1,608 行。文章同時明列 tRPC 前提：「server 用 TypeScript 且與 client 共置」、無法有效服務公開第三方 API。

判讀

撤退動因是「單一團隊同時擁有前後端」時、GraphQL 的 schema 中介層變成純開銷 — schema 作為跨團隊 / 跨 client 契約才有價值、同構 TypeScript 單團隊是反指標。作者自列的 tRPC 邊界（公開 API 不適用）可直接引用、避免被讀成萬用推薦。

對應大綱

公開 API 的 GraphQL 進退（適用邊界段、反例、已引用）、styles/rpc-revival/「tRPC 與型別共享」（anchor、backlog）。

下一步路由

回 模組十一案例庫。

引用源

• Why we ditched GraphQL for tRPC（Echobind blog、2022）

觀察

DataLoader 把單一執行 frame 內的個別 load 合併成 batch、加 per-request 快取；概念源自 Facebook 2010 年的內部 Loader API、早於 GraphQL 開源、跨語言存在（如 Haskell 的 Haxl）。Shopify 維護的 Ruby 版 graphql-batch（loader pattern + promise）被 GitHub 2016 年採用時直接引入、至 2025-09 仍在發版。

判讀

N+1 不是 GraphQL 發明的問題、但 resolver-per-field 執行模型讓它從偶發變成預設 — 所以官方生態把 batching 做成基礎設施、不是優化技巧。「連 GitHub day-one 都要帶 graphql-batch」是最直接的教學證據。

對應大綱

執行成本與攻擊面（N+1 段、anchor、已引用）。

下一步路由

回 模組十一案例庫。

引用源

• graphql/dataloader（GraphQL 基金會、GitHub repo）
• Shopify/graphql-batch（GitHub repo）

觀察

某電商平台的第三方 banner 服務暴露 GraphQL 端點、introspection 開啟；研究者（J. Francisco Bolivar、2023 HackerOne Ambassador World Cup 期間回報）用 introspection 列舉 schema、發現未加驗證的 CreateAdminUser mutation、直接取得管理權限、數日內修復。報告結論建議：production 關 introspection、field-level authorization、移除不必要的 mutation。

判讀

REST 世界要靠 fuzzing 才找得到的隱藏端點、GraphQL 用型別系統自己告訴你。教學上與 C22 的 CPU / 記憶體放大並列成兩類攻擊面：資訊暴露與資源耗盡。

對應大綱

執行成本與攻擊面（introspection 段、已引用）。邊緣（安全單點案例）。

下一步路由

回 模組十一案例庫。

引用源

• How a GraphQL Bug Resulted in Authentication Bypass（HackerOne blog）

觀察

官方教學明文：GraphQL 只回傳明確請求的資料、所以新能力可以透過新 type 或既有 type 的新 field 加入而不造成 breaking change；「永遠避免 breaking change、提供 versionless API」被稱為 common practice。同時「type system 中每個 field 預設 nullable」、理由包含後端局部故障與細粒度授權。驗證備註：官方站主頁對 fetcher 回 403、內容以官方 GitHub repo 的 source 檔驗證、對外引用用官方教學頁 URL。

判讀

no-versioning 的實質是把演進成本轉嫁到三個紀律：只加不改、deprecation 標注、nullable 預設 — 版本管理的工作換了位置、沒有消失。nullable-by-default 正是為了讓局部失敗與授權拒絕不炸掉整個 response — 這條因果鏈是 schema 演進篇的骨幹。可與 WunderGraph 批評（C27）對照：versionless 解 schema 相容、解不了組織層的舊 client 支援。

對應大綱

Schema 演進（anchor、已引用）、11.6 格式層紀律（主引用）、11.2 / 11.5 交叉、版本策略爭論文章。

下一步路由

回 模組十一案例庫。

引用源

• Schema design（GraphQL 官方教學）

觀察

兩篇文章的論點：單一 query 可觸發數千次 resolver、middleware 式安全模型失效；introspection 洩漏內部架構；schema traversal 可越權。解法是把 named operations 存在後端、對外轉成 JSON-RPC 式端點、完全不暴露 GraphQL endpoint。後篇補充：versioning 的組織問題 GraphQL 沒解、self-documenting 是迷思、type safety OpenAPI 也有。

判讀

「GraphQL 當 server-side 查詢語言、對外只開 persisted operations」是介於全開與撤退之間的第三條路、公開 API 進退章需要這個中間選項。來源是賣此方案的 vendor、立場要標明；但攻擊面描述與 Bessey（C22）、HackerOne（C25）獨立互證。

對應大綱

執行成本與攻擊面（persisted queries 段、已引用）與 公開 API 的 GraphQL 進退（中間路線段、已引用）。邊緣偏反例。

下一步路由

回 模組十一案例庫。

引用源

• GraphQL is not meant to be exposed over the internet（WunderGraph blog、Jens Neuse）
• Why not use GraphQL?（WunderGraph blog）