Community程式設計與開發github.com

sk-api

設計與變更 API 合約(REST、gRPC、protobuf、事件),讓既有呼叫端保持正常運作,涵蓋資源與方法形狀、錯誤模型、分頁、版本控制,以及破壞性變更所需的部署順序。適用於新增或修改端點、訊息或事件,或判斷某項提議變更是否會破壞消費者。

sk-api 是什麼?

這項技能旨在協助開發者在設計與修改 API 合約時,確保向後相容性,避免破壞既有呼叫端。它涵蓋 REST、gRPC、protobuf、事件等常見 API 模式,不僅指導如何命名資源、設計操作方法、處理錯誤模型與分頁,還明確列出哪些變更會被視為破壞性變更(如刪除欄位、修改類型、改變錯誤碼),以及哪些變更則是安全的(如新增可選請求欄位、回應欄位、端點等)。 此技能也提供了安全的合約修改流程:先新增再移除,讓新舊兩種版本同時運作至少一個版本週期,並逐步遷移消費者。此外,它強調部署順序的重要性——伺服器與消費者應分別更新,以確保雙方都能相容於兩種形狀。最後,建議透過實際檢查消費者程式碼與合約測試來驗證變更,而非僅依賴文件。此技能適用於 Claude Code、Cursor、Codex 等開發工具,能有效降低 API 演化過程中的中斷風險。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-api

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

API 合約

合約是你對無法控制也無法修復的程式碼所做出的承諾。這就是 API 變更與內部重構不同的地方:犯錯的成本是由別人在你無法選擇的時間點來承擔。

設計

將資源命名為名詞,讓方法承載動詞。對事物本身建模,而不是目前顯示它的螢幕——圍繞當今 UI 設計的酬載,在下一次重新設計時就會出錯。

審慎考量你暴露的內容。你回傳的每個欄位,都必須持續回傳。內部識別碼、資料列版本與實作細節會將你的結構描述洩漏到呼叫端的程式碼中,並將其凍結在那裡。

讓操作具有等冪性,以便呼叫端可以重試——任何可透過網路觸及的操作都應如此。對於任何建立或收費的操作,給予呼叫端一個等冪金鑰,這樣逾時後的重試就不會造成重複。

回傳一致的錯誤模型:一個穩定的機器可讀碼、一個人類可讀的訊息,以及驗證失敗時所參照的欄位。呼叫端會根據該碼進行分支判斷,因此它是合約的一部分——即使形狀不變,變更該碼仍屬破壞性變更。

從第一個版本就對每個清單進行分頁。一個回傳所有資料的端點,在資料表成長前都能正常運作,但之後就會對擁有最多資料的客戶造成失敗。當資料列同時插入時,偏好使用游標而非偏移量。

什麼會破壞呼叫端

以下情況,無論結構描述語言允許與否,皆屬破壞性變更:

  • 移除或重新命名欄位、端點、方法或列舉值。
  • 將可選請求欄位改為必填,或縮小欄位可接受的值範圍。
  • 變更型別,包括將整數改為字串,或將單一值改為清單。
  • 在保留欄位名稱與型別的情況下,變更既有欄位的意義——這是最糟糕的情況,因為沒有明顯的錯誤,資料只會悄悄地出錯。
  • 新增必填請求欄位。
  • 針對既有條件變更錯誤碼或 HTTP 狀態碼。
  • 緊縮預設值,或變更省略欄位時的行為。

安全:新增可選請求欄位、新增回應欄位、新增端點或方法、新增列舉值——僅當每個消費者都已能容忍未知值時才安全——請驗證這一點,而非直接假設。

在 protobuf 中,切勿重複使用或重新編號欄位標籤,並在移除欄位時保留該標籤與名稱。重複使用的標籤會將舊資料解碼到新欄位中,並悄悄地破壞它。

安全地變更合約

先新增再移除,並讓兩者並存至少一個版本:

  1. 將新欄位或方法與舊的並列。
  2. 同時寫入兩者,讀取時先嘗試新的,失敗時再退回舊的。
  3. 遷移消費者,並確認每個消費者都已轉移。
  4. 在後續版本中移除舊的路徑。

僅在資源的意義真正改變時才進行版本化,而非每次新增都版本化。每次變更都版本化會倍增你必須維持活躍的表面積。

部署順序

產生的程式碼與伺服器是分開部署的,而這個間隔就是中斷發生的地方。先推出能夠容忍兩種形狀的那一方:消費者在生產者發出新欄位之前就接受它,生產者在呼叫端發送新請求之前就接受它。

當結構描述透過閘道、代理伺服器或產生的客戶端共享時,路徑中的每個元件都需要重新產生與重新部署。一個已新增至服務但未新增至其前一層的欄位,會在到達呼叫端之前消失,而服務自身的測試將不會注意到這一點。

驗證

在變更形狀之前,先檢查實際的消費者——搜尋呼叫端,而非僅相信合約的文件。

測試合約本身:一個斷言序列化後形狀的測試,可以捕捉到在 handler 的單元測試中完全無法察覺的意外重新命名。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

相關技能