使用 FastAPI 建構 API:從設計到部署
引導使用者經歷六個階段:理解 → 設計 → 建構 → 測試 → 封裝 → 部署。僅詢問會改變結果的事項,其餘部分則宣告假設,並在不要求逐階段批准的情況下進行建構。
職責與限制
- 在可用環境中產生並測試程式碼。
- 實際部署由使用者在自己的帳戶或伺服器上執行,因為助手通常沒有權限。提供確切的命令與驗證步驟。
- 如果環境有伺服器或平台 CLI 的權限(例如 Claude Code),則僅在使用者必要的確認下執行操作。
- 如果無法執行測試或部署,請不要聲稱已執行。
階段 1:理解(一輪關鍵提問)
在編寫程式碼之前,釐清會影響架構的事項。如果有可點選選項的提問工具(ask_user_input_v0),請使用它;否則,製作一個簡短清單。最多三到四個問題,並跳過已經回答的問題:
- 目的與資源: API 做什麼?它操作哪些實體(例如客戶、發票、訂單)?需要哪些操作?
- 持久化: 無資料庫、SQLite(原型)還是 PostgreSQL?
- 消費者與存取: 誰呼叫它(RPA/Automation Anywhere 機器人、Web 應用程式、其他服務)?它應該是公開的還是內部的?這決定了驗證與部署方式。
- 目標: 如果已知,直接使用;否則,提供階段 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.mdreferences/deploy-paas.mdreferences/deploy-cloud.md
外部平台的命令和畫面會改變。如果使用者指出介面不符,請查閱最新的文件,而不是堅持使用過時的說明。
最後進行部署後驗證:
curl https://<url>/health
開啟 /docs,測試一個帶有金鑰和沒有金鑰的端點(沒有金鑰應回傳 401),並檢查日誌。如果失敗,要求提供錯誤訊息或日誌並進行診斷。常見問題:連接埠錯誤(應用程式應監聽 $PORT)、缺少環境變數、使用了 postgres:// 而非 postgresql://,或 CORS 阻擋了前端。
最終交付格式
保持簡短且實用,並包含:
- 建構了什麼以及所做的假設。
- 如何在本地執行的命令。
- 所需的環境變數。
- 端點表格。
- 所選部署的下一步。
避免不必要地重複檔案的內容。