Community程式設計與開發github.com

fastapi-api-builder

從頭到尾的指南:使用 Python 與 FastAPI 設計、建置、測試、封裝與部署 REST API。每當使用者想建立 API、後端、Web 服務、端點、Webhook,或將腳本/流程轉換為可被 RPA 機器人、Automation Anywhere、應用程式或前端呼叫的服務時,都應使用此技能。

fastapi-api-builder 是什麼?

這個 AI 技能是一個完整的工作流程,引導使用者走過六個階段來建立與部署 FastAPI 應用程式:理解、設計、建構、測試、封裝與部署。它專為開發者、DevOps 工程師以及 RPA 專家設計,目的是將任何流程轉換為一個安全的 REST API,可與 Automation Anywhere、Web 應用程式或前端整合。該技能支援多種部署選項,包括 Docker、PaaS(例如 Render、Railway)以及雲端服務(如 Cloud Run、App Runner),並根據使用者需求提供架構建議。其獨特之處在於透過最小化提問(僅針對影響結果的關鍵事項提問)並對其餘部分做出合理假設(例如使用 API 金鑰驗證、統一的 JSON 錯誤格式),來減少摩擦。該技能涵蓋了程式碼建立、使用 pytest 進行測試、使用 Docker 進行容器化,並提供生產環境前檢查清單以確保安全部署。此外,它還包含用於快速初始化的腳本模板,以及針對 Automation Anywhere 或自訂資料庫設定的參考文件(若相關文件存在)。

相容平台✓Claude Code~Codex CLI~Cursor
Part ofMobile
npx skills add https://github.com/EstefaniaRojasal-design/Skills/tree/main/fastapi-api-builder

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

在你喜歡的 AI 中提問

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

說明文件

使用 FastAPI 建構 API:從設計到部署

引導使用者經歷六個階段:理解 → 設計 → 建構 → 測試 → 封裝 → 部署。僅詢問會改變結果的事項,其餘部分則宣告假設,並在不要求逐階段批准的情況下進行建構。

職責與限制

  • 在可用環境中產生並測試程式碼。
  • 實際部署由使用者在自己的帳戶或伺服器上執行,因為助手通常沒有權限。提供確切的命令與驗證步驟。
  • 如果環境有伺服器或平台 CLI 的權限(例如 Claude Code),則僅在使用者必要的確認下執行操作。
  • 如果無法執行測試或部署,請不要聲稱已執行。

階段 1:理解(一輪關鍵提問)

在編寫程式碼之前,釐清會影響架構的事項。如果有可點選選項的提問工具(ask_user_input_v0),請使用它;否則,製作一個簡短清單。最多三到四個問題,並跳過已經回答的問題:

  1. 目的與資源: API 做什麼?它操作哪些實體(例如客戶、發票、訂單)?需要哪些操作?
  2. 持久化: 無資料庫、SQLite(原型)還是 PostgreSQL?
  3. 消費者與存取: 誰呼叫它(RPA/Automation Anywhere 機器人、Web 應用程式、其他服務)?它應該是公開的還是內部的?這決定了驗證與部署方式。
  4. 目標: 如果已知,直接使用;否則,提供階段 6 的選項,並推薦一個,但不應阻礙建構。

對於其他事項,假設合理的值(FastAPI、API 金鑰、統一的錯誤格式、pytest、Docker),並在一行中宣告它們。

階段 2:設計

在建構之前,提供一個緊湊的設計,以便使用者可以修正;如果使用者確認或沒有異議,則繼續建構:

  • 端點表格:方法、路徑、函數以及回應代碼。
  • 輸入/輸出模型:欄位與驗證規則。
  • 選擇的驗證方式及其理由;如果存在,請查閱 references/auth.md。

REST 慣例:複數名詞(/clientes)、使用 HTTP 動詞表示動作、建立時回傳 201、刪除時回傳 204、不存在時回傳 404、無效資料回傳 422、無憑證時回傳 401。

階段 3:建構

如果可用,請透過 scaffold 複製經過測試的模板,而不是重寫:

python <ruta-del-skill>/scripts/scaffold.py "<nombre-del-proyecto>" --out /home/claude

將模板調整為設計:

  • 將範例資源 app/routers/items.py 和 app/schemas.py 替換為所需的資源。
  • 在 app/main.py 中使用 include_router 註冊路由器。
  • 為新變數調整 app/config.py 和 .env.example。
  • 如果有資料庫,請查閱 references/database.md(如果存在)。
  • 如果需要使用者登入,請查閱 references/auth.md(如果存在)。
  • 如果消費者為 Automation Anywhere,請查閱 references/aa-integration.md(如果存在)並應用其契約:清晰的 HTTP 代碼、包含 status 和有用訊息的 JSON。

不要發明不可用的模板檔案或參考資料。如果它們不存在,請明確建立等效的解決方案。

分層結構(routers、schemas、config、security)便於擴展;Pydantic 在邏輯之前驗證資料;全域處理器回傳統一的錯誤,如 {"status":"error","message":"..."},且不在 500 錯誤中洩漏內部細節。包含 /health 以供 Docker、負載平衡器和平台使用。透過環境變數進行配置:在本地與生產環境中使用相同的程式碼,機密資訊保留在儲存庫之外。

階段 4:測試

在交付之前始終執行測試,並修復失敗直至通過(在環境允許的情況下):

cd <proyecto> && pip install -r requirements-dev.txt && python -m pytest -q

為每個新端點添加測試:快樂路徑、無效資料、資源未找到,以及在適用的情況下未驗證的測試。如果可能,啟動真實伺服器(uvicorn app.main:app --port 8000)並使用 curl 驗證 /health、帶有金鑰和沒有金鑰的受保護端點,以及 /docs。如果無法執行某個測試,請解釋原因以及缺少什麼。

階段 5:封裝

  • Dockerfile 應以非特權使用者身分執行,並監聽 $PORT,以便在 Render、Railway、Cloud Run 和 VPS 上同樣運作。
  • .dockerignore 和 .gitignore 應排除 .env;檢查程式碼或交付的檔案中是否包含機密資訊。
  • 如果這些工具可用,將完整的專案壓縮後交付到 /mnt/user-data/outputs/ 並使用 present_files。如果不可用,以有用的形式提供結構和檔案,但不要聲明已建立 ZIP。
  • 包含簡短摘要:如何在本地執行、所需的環境變數以及端點。

生產前檢查清單

  • API_KEY(或 JWT)已定義為長而隨機的值,並作為機密資訊儲存在平台上。
  • CORS_ORIGINS 包含明確的清單,而非 *。
  • ENVIRONMENT=production。
  • 資料庫是持久化的並有備份;不要在暫存磁碟上使用 SQLite。
  • HTTPS 已啟用;切勿透過 HTTP 暴露 API 金鑰。
  • .env 不在儲存庫中。
  • 測試通過且 /health 有回應。
  • 日誌可存取,並在出現 5xx 錯誤時發出警報。

階段 6:部署

如果使用者尚未選擇目標,請呈現以下比較,並根據他們的情況推薦。如果使用者基礎設施經驗較少,推薦 PaaS;如果需要內部網路或完全控制,推薦 VPS/自有伺服器;如果公司已經使用某個雲端,推薦該雲端的託管容器。

選項努力控制典型成本最適合
VPS 或自有伺服器上的 Docker中等完全固定且低內部網路、控制、可預測的成本
PaaS(Render、Railway、Fly.io)低中等低到中,按用量計費快速上線、小型團隊
雲端(Cloud Run、Container Apps、App Runner/ECS)中等到高高按用量計費已有雲端、需要擴展、合規要求

選擇後,僅查閱對應的指南(如果存在):

  • references/deploy-vps-docker.md
  • references/deploy-paas.md
  • references/deploy-cloud.md

外部平台的命令和畫面會改變。如果使用者指出介面不符,請查閱最新的文件,而不是堅持使用過時的說明。

最後進行部署後驗證:

curl https://<url>/health

開啟 /docs,測試一個帶有金鑰和沒有金鑰的端點(沒有金鑰應回傳 401),並檢查日誌。如果失敗,要求提供錯誤訊息或日誌並進行診斷。常見問題:連接埠錯誤(應用程式應監聽 $PORT)、缺少環境變數、使用了 postgres:// 而非 postgresql://,或 CORS 阻擋了前端。

最終交付格式

保持簡短且實用,並包含:

  1. 建構了什麼以及所做的假設。
  2. 如何在本地執行的命令。
  3. 所需的環境變數。
  4. 端點表格。
  5. 所選部署的下一步。

避免不必要地重複檔案的內容。

相關技能