Codex 應用案例
遷移驗證模組
升級單一模組,並以測試證明其對外行為與升級前一致。
為 Codex 提供範圍明確的遷移說明、契約測試資料,以及已設定好的雲端環境。讓 Codex 升級單一驗證模組,只交付本次遷移所需的變更,並提供升級前後的行為比對證據、列出尚存的差異,以及說明如何還原變更。
最適合的對象
- 準備遷移舊有驗證元件的工程團隊。
- 有明確契約且可重複執行測試的遷移作業。
- 需要交付經過審查的小幅變更,同時維持其他模組正常運作的團隊。
目錄
遷移驗證模組
升級單一模組,並以測試證明其對外行為與升級前一致。
為 Codex 提供範圍明確的遷移說明、契約測試資料,以及已設定好的雲端環境。讓 Codex 升級單一驗證模組,只交付本次遷移所需的變更,並提供升級前後的行為比對證據、列出尚存的差異,以及說明如何還原變更。
為 Codex 提供範圍明確的遷移說明、契約測試資料,以及已設定好的雲端環境。讓 Codex 升級單一驗證模組,只交付本次遷移所需的變更,並提供升級前後的行為比對證據、列出尚存的差異,以及說明如何還原變更。
相關連結
最適合的對象
- 準備遷移舊有驗證元件的工程團隊。
- 有明確契約且可重複執行測試的遷移作業。
- 需要交付經過審查的小幅變更,同時維持其他模組正常運作的團隊。
入門提示詞
適用時機
如果遷移範圍明確,且有測試可以比較遷移前後的行為,就適合使用這個工作流程。請提供 Codex 遷移說明、模組及呼叫該模組的程式碼、已固定的契約測試資料,以及準備好的雲端環境。請 Codex 完成一項範圍明確的變更,並提供驗證紀錄和回復步驟。
這個範例將訂單服務中的一個驗證模型從 Pydantic v1 遷移到 v2。範例包含原始實作、相容性準備階段,以及遷移後的模組。測試會實際使用 FastAPI 路由器和錯誤處理常式,並檢查回應序列化、相鄰的舊版路由和公開的 OpenAPI 文件。範例不包含資料庫遷移或部署。
準備雲端環境
-
選擇 工作位置 > 雲端,然後選取已發布的環境。
-
如要建立環境,請選取 建立環境,選擇 GitHub 程式碼庫,並請 Codex 準備執行環境、相依套件和隔離的測試服務。
-
檢閱設定報告,修正未通過的檢查項目,並在開始新任務前選取 發布。
如果相依套件或服務設定有變更,請編輯可重複使用的環境,測試後選取 重新發布。
請在新任務中驗證更新後的環境。重新整理程式碼庫時,系統會保留相依套件快取,不會重新執行安裝或啟動指令。既有任務也會保留各自的狀態。
請另外設定需要連線的網路目的地和認證資訊。
在每個階段記錄環境及其設定的參照資訊、原始碼提交、Python 修補版本、框架和相依套件版本、套件管理工具版本,以及鎖定檔的雜湊值。採用新任務的結果前,請先在該任務中確認這些版本。
執行範例
下載完整遷移範例。其中包含三個獨立的 uv 專案、各專案已解析相依版本的 uv.lock 檔案、應用程式實作、共用的錯誤與結構描述轉接器、已固定的 HTTP 測試資料,以及契約測試執行程式。
請使用 Python 3.11、3.12 或 3.13,安裝 uv,然後執行:
unzip sample.zip
cd migrate-a-validation-module
uv run --project support/target --python python3 --frozen python run.py --compare-stages --output evidence
執行比較時,程式會為每個階段建立獨立的 .venv,並使用 uv sync --frozen 安裝相依套件。所有階段都使用啟動比較程式的 Python 直譯器,以及同一組 HTTP 和結構描述測試資料。相依套件版本維持鎖定。
舊版 Pydantic v1 相容層不支援 Python 3.14 及更新版本,因此範例不適用於這些版本。執行成功時,最後會顯示:
PASS: legacy, prepared, target HTTP/schema/serialization contracts match
Native model schemas differ; the existing public schema adapter is preserved.
請查看 evidence/legacy.json、prepared.json、target.json 和 summary.json。這些檔案記錄了實際收到的回應、執行環境版本、原始碼、測試資料與鎖定檔各自的雜湊值、執行的指令、結束代碼,以及原始記錄檔的路徑。
執行程式透過 FastAPI 的 TestClient,在同一個程序內測試範例應用程式的 HTTP 端點。請在選定的雲端任務中執行,並保留該任務的驗證紀錄。
執行 python3 run.py 時若不加上 --compare-stages,只適合在已安裝 Pydantic v2 的環境中單獨檢查目標模型。此獨立模式會檢查七個驗證與序列化案例,不會執行 HTTP 測試或比較各階段的行為。驗證遷移時,請使用上方的完整比較指令。
完整比較會在每個階段檢查 23 個 HTTP 案例、公開的 OpenAPI 文件,以及回應序列化結果。這些檢查已在本機使用 Python 3.11、3.12 和 3.13 執行並通過。下載檔案中的 README.md 記載了測試過的版本和執行歷程。請在自己的雲端環境中執行目前的比較程式,並記錄該環境的結果。
各階段分別管理相依套件
| 階段 | Python / FastAPI / Pydantic |
遷移範圍 |
|---|---|---|
| 舊版 | 3.11–3.13 / 0.119.0 / 1.10.22 |
現有模型從 pydantic 匯入所需項目。 |
| 準備後的基準 | 3.11–3.13 / 0.119.0 / 2.12.3 |
兩個模型都使用 pydantic.v1。請記錄套件內附的實際 v1 版本。 |
| 目標 | 3.11–3.13 / 0.119.0 / 2.12.3 |
只有 OrderInput 遷移到 v2。相鄰路由繼續使用其獨立的 v1 模型。 |
準備階段和目標階段的相依套件鎖定檔完全相同。模組遷移只變更模型和直接用於序列化該模型的方法,不涉及相依套件環境。
準備步驟是一項需單獨審查的變更。在此步驟中,其餘 v1 路由的轉接器也會改為在驗證回應前,透過 dict(by_alias=True) 輸出以別名為鍵的字典。在 v2 執行環境中直接傳回 v1 模型,可能會遺失對外使用的別名。
目標階段的訂單轉接器使用 model_dump(by_alias=True),相鄰的 v1 路由則保留準備階段的轉接器。
根據 FastAPI 遷移指南,只有 0.119.0 到 0.127.x 暫時支援 v1 和 v2 路由並存。0.128.0 已移除這項支援。
本範例刻意將版本固定在 0.119.0,以示範這段過渡期的遷移方式。較新版的 FastAPI 應用程式應在遷移範圍內全面使用 v2。若使用暫時的相容層,請明確指定負責人和移除條件。請勿在 v1 模型中嵌入 v2 模型,或在 v2 模型中嵌入 v1 模型。這個相容層無法用於遷移至 Python 3.14。
檢閱契約測試
已固定的 HTTP 測試案例涵蓋成功的請求、省略備註或明確將備註設為 null、ID 遺漏或無效、多個未知欄位、不同欄位錯誤同時出現、無效備註、JSON 格式錯誤、內容類型錯誤、缺少請求主體、別名、以陣列或字串作為請求主體,以及相鄰的舊版路由。測試會比較狀態碼、Content-Type 標頭和解析後的完整 JSON 回應,不會移除錯誤欄位或變更預期型別。
從舊版階段起,這項服務就由應用程式自行定義錯誤回應的外層格式和公開的 OpenAPI 文件。錯誤與結構描述轉接器都會保留。目標階段沿用舊版的錯誤順序:先列出已宣告欄位的錯誤,再依字母順序列出未知鍵。
測試會按照原有順序比較完整的 error.fields 陣列,不會重新排序實際收到的回應。執行程式會分別記錄每個模型的原生結構描述,並確認這些結構描述確實有差異。公開結構描述一致,不代表相依套件產生的結構描述完全相同。
服務保留了舊版處理輸入的方式:它接受由鍵值對組成的陣列,例如 [["order_id", "ord_123"]],並將其視為物件。[] 和空的 JSON 字串都會轉為空物件,因而產生缺少 ID 的錯誤。非空字串仍會被判定為無效的請求主體。目標模型仍接受可透過 dict(value) 成功轉換的輸入。若要改為只接受物件,必須由負責人決定是否變更契約,不能只改寫測試的預期結果。
修改自己的程式碼庫之前,請先將目前的實際回應固定為測試資料。請為選填欄位明確指定預設值,保留既有的驗證嚴格程度與未知欄位處理方式,並測試實際使用的錯誤處理常式和回應序列化流程。
不同版本產生的原始驗證錯誤會有所不同。Pydantic 遷移指南也說明了別名、型別強制轉換、選填欄位和自訂驗證函式的變更。v2 不會將這些函式內引發的 TypeError 轉換為 ValidationError。
檢視契約測試執行程式
以下片段取自下載檔案中的 run.py。請解壓縮 ZIP 後執行完整檔案。壓縮檔內含各階段的相依套件鎖定檔和 HTTP 測試資料。
比較三個階段
class OrderInput(BaseModel):
internal_order_id: StrictStr = Field(alias="order_id")
customer_note: StrictStr | None = None
model_config = ConfigDict(extra="forbid", populate_by_name=False)
@model_validator(mode="before")
@classmethod
def preserve_legacy_mapping(cls, value):
# v1 tries dict(value), so pairs, [] and "" can become objects.
# Preserve successful conversions without changing failed-input errors.
if not isinstance(value, dict):
try:
return dict(value)
except (TypeError, ValueError):
return value
return value
def serialize_order(payload):
return OrderInput(**payload).model_dump(by_alias=True)
def preserve_legacy_error_order(fields):
# v1 reports declared-field errors first and unknown keys alphabetically.
# v2 keeps unknown keys in input order; preserve the existing HTTP contract.
known = [field for field in fields if field["code"] != "extra_forbidden"]
extra = sorted(
(field for field in fields if field["code"] == "extra_forbidden"),
key=lambda field: field["path"],
)
return known + extra
def check_target_model():
for payload, expected in (
({"order_id": "ord_123"}, {"order_id": "ord_123", "customer_note": None}),
(
{"order_id": "ord_123", "customer_note": "Leave at desk"},
{"order_id": "ord_123", "customer_note": "Leave at desk"},
),
(
{"order_id": "ord_123", "customer_note": None},
{"order_id": "ord_123", "customer_note": None},
),
):
assert serialize_order(payload) == expected
for payload, expected in (
({}, [("order_id", "missing")]),
({"order_id": 123}, [("order_id", "string_type")]),
(
{"order_id": "ord_123", "customer_note": 17},
[("customer_note", "string_type")],
),
(
{"order_id": "ord_123", "unexpected": True},
[("unexpected", "extra_forbidden")],
),
):
try:
OrderInput(**payload)
except ValidationError as error:
assert [
(item["loc"][0], item["type"]) for item in error.errors()
] == expected
else:
raise AssertionError(f"Accepted invalid order: {payload}")
print("PASS: target model validation and serialization (7 cases)")
print("Model-only checks; use --compare-stages for HTTP migration parity.")
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--output", type=Path, default=ROOT / "evidence")
parser.add_argument("--compare-stages", action="store_true")
args = parser.parse_args()
if not args.compare_stages:
check_target_model()
return
args.output.mkdir(parents=True, exist_ok=True)
reports = []
commands = []
for stage in ("legacy", "prepared", "target"):
project = Path("support") / stage
stage_commands = [
[
"uv",
"sync",
"--project",
str(project),
"--python",
sys.executable,
"--frozen",
],
[
"uv",
"run",
"--project",
str(project),
"--python",
sys.executable,
"--frozen",
"python",
"test/run_stage.py",
stage,
str(args.output / f"{stage}.json"),
],
]
for command in stage_commands:
completed = subprocess.run(
command, cwd=ROOT, capture_output=True, text=True
)
label = f"{stage}-{len(commands)}"
(args.output / f"{label}.log").write_text(
completed.stdout + completed.stderr
)
commands.append(
{
"command": command,
"exit_code": completed.returncode,
"log": f"{label}.log",
}
)
(args.output / "commands.json").write_text(
json.dumps(commands, indent=2, sort_keys=True) + "\n"
)
if completed.returncode:
print(completed.stdout + completed.stderr, file=sys.stderr)
raise SystemExit(completed.returncode)
print(completed.stdout, end="")
reports.append(json.loads((args.output / f"{stage}.json").read_text()))
assert all(report["python"] == platform.python_version() for report in reports)
for report in reports[1:]:
for key in (
"observations",
"public_openapi",
"direct_call",
"fixture_sha256",
"schema_fixture_sha256",
):
assert report[key] == reports[0][key], f"Parity failed: {key}"
assert reports[1]["lock_sha256"] == reports[2]["lock_sha256"]
native_schema_differs = (
reports[0]["native_model_schema"] != reports[2]["native_model_schema"]
)
assert native_schema_differs, "The example should expose native schema drift"
manifest = {
str(path.relative_to(ROOT)): digest(path)
for path in sorted(ROOT.rglob("*"))
if path.is_file()
and not path.resolve().is_relative_to(args.output.resolve())
and not any(
part in {".venv", "__pycache__", "evidence", ".ruff_cache"}
for part in path.relative_to(ROOT).parts
)
}
summary = {
"status": "pass",
"scope": "synthetic in-process FastAPI TestClient execution",
"stages": [report["stage"] for report in reports],
"http_cases_per_stage": reports[0]["http_cases"],
"native_model_schema_differs": native_schema_differs,
"public_http_and_schema_parity": True,
"commands": commands,
"source_sha256": manifest,
}
(args.output / "summary.json").write_text(
json.dumps(summary, indent=2, sort_keys=True) + "\n"
)
print("PASS: legacy, prepared, target HTTP/schema/serialization contracts match")
print(
"Native model schemas differ; the existing public schema adapter is preserved."
)在自己的程式碼庫中執行工作流程
- 撰寫遷移說明。 列出模組、直接呼叫該模組的程式碼、負責人、已核准的版本、契約測試、不在範圍內的程式碼,以及回復步驟。如果這部分遷移需要擴大相依套件的升級範圍,或會改變對外行為,請停止遷移。
- 建立基準。 請 Codex 閱讀
AGENTS.md、遷移說明、官方遷移指南、鎖定檔、呼叫端程式碼和測試。記錄起始提交和已安裝的版本。在判定遷移前後行為一致之前,請先說明基準檢查失敗的原因,或修正問題。 - 單獨準備相容性變更。 如果共用的相依套件讓模組與其他程式碼相互牽連,請先審查準備階段的變更。使用同一組測試資料,確認原始基準和準備後的基準都能通過測試。
- 一次遷移一個部分。 使用本頁提供的起始提示詞。修改模組和直接處理該模組的轉接器,保留不相關的模組,並列出仍保留的相容性程式碼。
- 執行相同的測試。 使用相同的 HTTP 和結構描述測試資料比較基準與最終結果,維持原有的預期結果。執行受影響的整合測試、lint 檢查和型別檢查,儲存輸出並註明對應的最終原始碼和相依套件狀態。
- 檢閱交接內容。 檢視程式碼差異、實測紀錄、尚未解決的差異、仍保留的相容層和回復步驟。只有在程式碼庫的工具和權限允許時,才建立 PR 草稿。合併、部署及下一部分的遷移交由審查者處理。
記錄已驗證的項目
請為每項驗證準則留下紀錄:
Criterion: [behavior and test]
Environment: [setup reference; actual runtime and dependency versions]
Before: [commit/diff ID; command; exit code; observed result; evidence path]
After: [final commit/diff ID; command; exit code; observed result; evidence path]
Status: [pass / fail / blocked / not run]
Limits: [untested behavior, missing prerequisite, or required owner decision]
成功匯入模組、通過 lint 檢查或重新產生快照,都不足以證明 API 行為一致。請單獨記錄有意為之的差異。最終原始碼如有變更,請重新執行檢查。將範例套用到自己的應用程式時,請將實際的呼叫端和服務納入契約測試。
相關應用案例
調查事故並測試修正
將已移除敏感資訊的事故資料與可正常運作的測試環境交給 Codex 雲端,讓它檢視證據、重現證據所指向的程式碼缺陷,並提供針對該缺陷的修正、迴歸測試證據,以及部署與回復至先前版本的交接說明。
執行程式碼遷移
使用 Codex 釐清舊系統與新技術堆疊的對應關係,分階段完成遷移,並在每次切換前確認新舊系統的行為一致。
建立 Codex 可使用的 CLI
請 Codex 建立一套 CLI,讓它能在任何資料夾中執行 CLI 指令、搭配程式碼庫中的指令碼使用,也能下載檔案。再請它建立配套技能,讓 Codex 日後記得如何使用這套 CLI。