用 Codex 開發 Python FastAPI + Pydantic 接口服務實戰:類型校驗、異步數據庫與 Pytest 覆蓋

讓 AI 寫 FastAPI 接口常出現 Pydantic v1/v2 混用、異步路由塞進同步阻塞 I/O 或報 MissingGreenlet 錯誤。本文拆解 AGENTS.md 規範、SQLAlchemy 2.0 異步會話約束與 Pytest 覆蓋實戰。

NNathaniel bigo··原創首發·AI 輔助撰寫
11 分鐘讀完
資料核對於 2026-11-19 · 依據官方文檔與公開資料整理 Plus 帳號

結論先說

  1. 在 AGENTS.md 鎖定 Pydantic v2 與類型註解規範,能立刻消除一大半版本混用報錯。明確要求使用 ConfigDict(from_attributes=True)、model_dump()、field_validator 和完整的 Python 類型提示,同時禁止把數據庫 ORM 實體直接作為接口返回值,防止誤把密碼哈希或內部審計字段序列化給客戶端。
  2. 異步數據庫最常見的坑是隱式惰性加載(MissingGreenlet)與事件循環阻塞。SQLAlchemy 2.0 異步會話下必須將 expire_on_commit=False 寫進會話工廠,並在查詢關聯關係時顯式使用 selectinload 或 joinedload;所有 async def 路由內嚴禁混用同步網絡庫或同步數據庫驅動。
  3. 測試層用 httpx.AsyncClient + ASGITransport 配合 app.dependency_overrides,既跑真實路由校驗又保持隔離。把數據庫會話依賴替換成測試專用事務會話,不僅能覆蓋 200 正常鏈路,還能把 422 參數校驗失敗、404 資源不存在、409 唯一鍵衝突統統測實(防寫出假測試見 /guides/codex-generate-unit-tests-playwright-e2e-avoid-fake-mocks)。
  4. 每次改完接口必須三件套聯跑:ruff check + mypy + pytest --cov。把靜態風格、靜態類型和異步覆蓋率綁成統一驗收標準,可徹底杜絕模型用 Any 和 # type: ignore 糊弄校驗(批量修 Ruff / 類型報錯見 /guides/codex-batch-fix-typescript-eslint-ruff-errors)。
  5. 同時兼顧複雜 Pydantic 校驗模型、異步事務回滾與高覆蓋率 Pytest 套件會持續消耗 Codex 推理配額。國內若缺少外幣卡或希望一步到位提升額度,可在本站按需開通 ChatGPT Plus 充值 或高配額 ChatGPT Pro 充值,團隊多人研發可了解 ChatGPT Business 團隊定製。

FastAPI 異步服務與測試五步閉環

圖:本站根據 FastAPI 文檔 與 SQLAlchemy 異步文檔 整理的示意圖

本文根據 FastAPI 官方文檔《Request Body》、Pydantic 官方文檔《Models》、SQLAlchemy 2.0 官方文檔《Asynchronous I/O》及 OpenAI Codex 官方文檔《Custom instructions with AGENTS.md》整理,資料核對於 2026-11-19。配圖為本站整理的示意圖,不是介面截圖。本站(bigolab.com)不是 OpenAI 官方網站。

適用於誰

  • 使用 FastAPI + Pydantic v2 + SQLAlchemy 2.0 構建異步接口服務,希望讓 Codex 高質素生成路由、數據校驗和異步測試的 Python 開發者;
  • 遇到模型順手寫出 Pydantic v1 廢棄語法(orm_mode、.dict())、在 async def 路由裏塞入同步 requests 調用、或者一序列化關聯對象就炸出 MissingGreenlet 異常的人;
  • 希望把 ruff、mypy 與 pytest --cov 串成 Codex 自動化質素門禁的後端工程師。

一、編寫 FastAPI + Pydantic v2 專屬 AGENTS.md 護欄

將下面這份約定放到 Python 倉庫根目錄 AGENTS.md 中,能顯著減少 Codex 寫舊語法和阻塞代碼的概率(更多護欄技巧見 /guides/codex-agents-md-guardrails-stop-deleting-tests):

markdown
# Python FastAPI 服務約束(AGENTS.md)

## 契約與類型規範
- 嚴格使用 Pydantic v2(`ConfigDict(from_attributes=True)`、`model_dump()`、`field_validator`),禁止使用 v1 廢棄寫法(`class Config`、`orm_mode`、`.dict()`)。
- 路由必須顯式聲明 `response_model`,Request/Response Schema 放在 `app/schemas/`,與 `app/models/` ORM 模型徹底解耦。
- 禁止為了繞過靜態檢查而濫用 `Any`、`# type: ignore` 或 `# noqa`。

## 異步與數據庫紅線
- `async def` 路由與服務層嚴禁調用阻塞同步 I/O(如 `requests`、同步 `psycopg2`、`time.sleep`)。
- SQLAlchemy 2.0 `AsyncSession` 查詢關聯表必須顯式使用 `selectinload` 或 `joinedload`,禁止觸發隱式惰性加載。

## 必跑驗收命令
1. `ruff check app tests`
2. `mypy app`
3. `pytest --cov=app --cov-report=term-missing`

二、常見 FastAPI 異步與類型坑點排查決策

當服務在高並發壓測變慢或測試突然拋出 MissingGreenlet、Event loop is closed 時,可對照下面決策圖直接鎖定排查切入點:

FastAPI 與異步數據庫排錯決策

圖:本站根據 Pydantic 文檔 與 SQLAlchemy 2.0 文檔 整理的示意圖

訂閱與帳號準備提示:編寫完整的異步接口層、多模型校驗規則加上全套邊界 Pytest 覆蓋,往往會在短時間內密集觸發多輪代碼生成與測試迴歸(額度規則見 /guides/codex-usage-limits)。重度 Python 後端開發推薦按需選購 ChatGPT Pro 5x iOS 可覆蓋檔 或 ChatGPT Pro 5x 信用卡不可覆蓋檔;新帳號註冊遇到手機驗證步驟可查看 Codex 註冊手機驗證服務。

三、實戰提示詞:一次跑通接口實現、異步查詢與 Pytest 覆蓋

下面是一個可直接複製給 Codex 的端到端功能切片提示詞,要求模型先審 Schema 契約再落庫,並用真實異步測試把所有邊界鎖死:

text
請先通讀 AGENTS.md、app/db/session.py 和現有 app/api/ 路由風格,為「訂閱訂單管理」模組實現以下功能並完成測試覆蓋:
1. 在 Plan Mode 下先列出新增的 Pydantic v2 Request/Response Schema、SQLAlchemy 異步查詢方案(標明預加載策略)與測試清單,等我確認後再寫代碼;
2. 確認後實現 `POST /api/v1/orders`(含嚴格字段範圍與電郵/金額格式校驗)和 `GET /api/v1/orders/{order_id}`(含明細關聯預加載,不暴露內部敏感字段);
3. 編寫異步 Pytest 用例(使用 httpx.AsyncClient + ASGITransport 與 dependency_overrides 注入隔離測試會話),覆蓋:正常創建與讀取、非法入參返回 422、重複冪等鍵返回 409、不存在資源返回 404;
4. 依次運行 `ruff check app tests`、`mypy app` 與 `pytest --cov=app/api/orders --cov-report=term-missing`,確認全部通過且核心分支無遺漏後彙報結果。

如果你的接口還需與前端 TypeScript 嚴格對齊,可以順手利用 FastAPI 自動生成的 OpenAPI Schema,按照 /guides/codex-fullstack-api-openapi-contract-type-alignment-guide 的流程把前後端類型完全鎖死。

常見問題

問:項目裏某些第三方 SDK 只有同步客戶端,沒有異步版本,在 FastAPI 裏該怎麼讓 Codex 正確處理?

答:官方 FastAPI 機制支持普通 def 路徑操作函數自動放到外部線程池裏執行,不會阻塞主事件循環;如果該路由本身必須是 async def(例如同時還要 await 異步數據庫),則要求 Codex 用 anyio.to_thread.run_sync(...) 或 asyncio.to_thread(...) 包裹那段同步 SDK 調用,並明確超時控制,嚴禁直接在 async def 中裸調阻塞網絡請求。

問:測試環境用 SQLite 內存庫替代生產 PostgreSQL 跑異步 Pytest,會不會埋雷?

答:測純 Pydantic 校驗和簡單 CRUD 時 SQLite(aiosqlite)確實快,但 PostgreSQL 特有的 JSONB、數組列、部分唯一索引和行級鎖語義在 SQLite 下根本測不出來。本站建議單元測試測邏輯與 422 校驗,涉及真實 SQL 約束和並發事務的集成測試配合本地 Docker Compose 起真實 Postgres 容器執行。

問:日常用 Codex 寫 Python FastAPI 接口和全套異步測試很消耗額度,個人或團隊怎麼開通高配額訂閱、能否開增值稅發票?

答:可前往本站 AI 會員充值總覽 按需選購 ChatGPT Plus 充值、ChatGPT Plus 自助卡密 或更高額度的 ChatGPT Pro 充值,團隊集中採購可了解 ChatGPT Business 團隊定製。支持支付寶、微信支付和 AlipayHK,自助卡密無需提供帳號密碼,並支持開具增值稅發票;實時價格與規格以頁面展示為準,售後執行掉訂閱按剩餘天數折退、封號不在質保範圍規則。

相關教學

參考資料

  • FastAPI 官方文檔:Request Body — https://fastapi.tiangolo.com/tutorial/body/
  • Pydantic 官方文檔:Models — https://docs.pydantic.dev/latest/concepts/models/
  • SQLAlchemy 2.0 官方文檔:Asynchronous I/O — https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html
  • OpenAI Codex 官方文檔:Custom instructions with AGENTS.md — https://learn.chatgpt.com/docs/agent-configuration/agents-md

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同產品的其他教學

  1. 01

    用 ChatGPT 整理家庭裝修預算明細、隱蔽工程驗收清單與主材優缺點對比表實戰

    第一次裝修面對幾十頁施工報價單、密密麻麻的水電防水隱蔽項目與五花八門的主材參數,極易踩坑增項。本文梳理用 ChatGPT 審查裝修報價漏項、生成帶公式的預算明細表、定製工地隱蔽工程驗收單與主材對比表的實戰提示詞。

    ChatGPT0
  2. 02

    用 ChatGPT 做費曼學習法讀書共讀:反向追問檢驗自己是否真讀懂專業書籍與整理書單筆記

    讀完一本專業硬書常感覺「合上書就忘」,直接讓 AI 概括全書又容易產生懂了的錯覺。本文介紹用 ChatGPT 結合 Study Mode 與費曼學習法做反向追問共讀,通過通俗複述、挑刺盲區到沉澱書單卡片的完整流程與提示詞。

    ChatGPT0
  3. 03

    用 ChatGPT 做外貿產品多語種目錄、展會邀約與客戶跟進節奏表(附脫敏與本地化提示詞)

    做外貿展會與海外推廣時,手工翻譯十幾款產品目錄費時且容易留下一堆中式英文,展後客戶跟進也常缺節奏。本文梳理用 ChatGPT 先脫敏建術語庫、再批量產出多語種目錄、展前邀約函與展後 21 天跟進節奏表的實戰流程與提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫高質素技術專欄文章、開源項目 Release Notes 與版本更新日誌實戰

    讓 AI 直接憑空寫技術文章容易滿篇空洞套話,直接甩 Git 記錄寫更新日誌又常常漏掉破壞性變更。本文整理用 ChatGPT 結合真實代碼片段、壓測數據與 PR 摘要,高效產出深度技術專欄、GitHub Release Notes 與 CHANGELOG 的實戰工作流。

    ChatGPT0
  5. 05

    用 ChatGPT 做產品用戶訪談紀要編碼、提煉高頻痛點需求池與 RICE 優先級打分實戰

    手頭攢了十幾份用戶訪談逐字稿,手工貼便利貼歸納痛點耗時又容易帶入主觀偏見。本文分享用 ChatGPT 完成脫敏檢查、逐份開放式編碼、跨樣本聚類高頻痛點並搭建 RICE 優先級打分表的 5 步實戰流,附可直接複製的三段核心提示詞。

    ChatGPT0
  6. 06

    ChatGPT 網頁版上載超過 10 個文件或回形針附件按鈕變灰怎麼辦:打包合併與配額限制排查

    在 ChatGPT 網頁版批量分析文檔時,常遇到一次選超 10 個文件被攔截或輸入框回形針按鈕變灰。本文依據 OpenAI 文件上載與存儲說明,梳理 6 類常見報錯的分流排查法,提供 ZIP 打包、本地合併與 Projects 複用方案及可直接複製的解包提示詞。

    ChatGPT0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~