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

圖:本站根據 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 時,可對照下面決策圖直接鎖定排查切入點:

圖:本站根據 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,自助卡密無需提供帳號密碼,並支持開具增值稅發票;實時價格與規格以頁面展示為準,售後執行掉訂閱按剩餘天數折退、封號不在質保範圍規則。
相關教學
- 用 Codex 批量排查並修復 TypeScript / ESLint / Python Ruff 靜態檢查報錯
- 用 Codex 自動補全缺失的單元測試與 Playwright E2E 用例:避免寫出假測試
- 用 Codex 做全棧接口聯調與前後端類型對齊:先生成 OpenAPI 契約再改代碼
- Codex 寫代碼時愛刪測試或亂改無關文件怎麼辦:5 條 AGENTS.md 硬約束護欄
參考資料
- 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
0 條評論
還沒有評論,來搶沙發~