如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Codex

Codex 應用案例

遷移驗證模組

升級單一模組,並以測試證明其對外行為與升級前一致。

難度 Advanced
任務時間跨度 Long-running

為 Codex 提供範圍明確的遷移說明、契約測試資料,以及已設定好的雲端環境。讓 Codex 升級單一驗證模組,只交付本次遷移所需的變更,並提供升級前後的行為比對證據、列出尚存的差異,以及說明如何還原變更。

最適合的對象

  • 準備遷移舊有驗證元件的工程團隊。
  • 有明確契約且可重複執行測試的遷移作業。
  • 需要交付經過審查的小幅變更,同時維持其他模組正常運作的團隊。

目錄

    ← 所有應用案例

    遷移驗證模組

    升級單一模組,並以測試證明其對外行為與升級前一致。

    為 Codex 提供範圍明確的遷移說明、契約測試資料,以及已設定好的雲端環境。讓 Codex 升級單一驗證模組,只交付本次遷移所需的變更,並提供升級前後的行為比對證據、列出尚存的差異,以及說明如何還原變更。

    Advanced
    Long-running
    準備雲端環境

    為 Codex 提供範圍明確的遷移說明、契約測試資料,以及已設定好的雲端環境。讓 Codex 升級單一驗證模組,只交付本次遷移所需的變更,並提供升級前後的行為比對證據、列出尚存的差異,以及說明如何還原變更。

    Advanced
    Long-running

    最適合的對象

    • 準備遷移舊有驗證元件的工程團隊。
    • 有明確契約且可重複執行測試的遷移作業。
    • 需要交付經過審查的小幅變更,同時維持其他模組正常運作的團隊。

    入門提示詞

    在這個雲端環境中,將 [repository] 裡的 [module] 從 [current pinned version] 遷移至 [approved target version]。 閱讀 AGENTS.md、[migration brief]、[official migration guide]、相依套件鎖定檔、呼叫此模組的程式碼,以及 [contract test locations]。記錄起始提交、環境與設定的參考資料、已安裝的 Python 版本,以及鎖定檔的雜湊值。也請分別記錄框架、Pydantic 和隨附 v1 的版本。確認基準版本與目標版本的相容性。若需預先調整共用相依套件或匯入陳述式,請將這些調整列為獨立變更,另行審查。 先執行 [baseline commands],盤點遷移涉及的程式碼,並將簡短計畫寫入 [plan file]。遵守 [public contracts],不要修改 [out-of-scope modules]。只在核准的範圍內移除過時的程式碼,並列出所有必須保留的相容性轉接器名稱。 如果這部分可以獨立遷移,且基準狀態可供測試,請在變更前後執行同一組內容固定的 HTTP 契約測試,讓測試請求經過實際的路由器,並涵蓋實際的錯誤處理常式與回應序列化流程。比對狀態碼、契約規定的標頭、哪些輸入會被接受或拒絕、對外 JSON 的鍵與型別、預設值與 null 值,以及錯誤回應的完整結構與內容。也請針對受影響的部分執行整合測試、lint 檢查與型別檢查。如果需要擴大升級範圍或改變對外行為,請在擴大範圍前先回報需要決定的事項。不要核准新的測試快照、透過正規化掩蓋對外行為的差異,或放寬斷言條件。針對每項檢查,記錄程式碼修訂版、環境、軟體版本、變更前後執行的指令、結束代碼與證據檔案路徑。將結果標示為「通過」、「失敗」、「受阻」或「未執行」,並說明限制。 請提供差異檔、變更前後的證據、尚未解決的差異、相依套件與鎖定檔的變更、還原步驟,以及 Pull Request 說明草稿。只有在已連線的程式碼庫工具支援此操作,且我具備所需權限時,才建立草稿 Pull Request。否則請提供修補檔與說明。不要合併、部署、變更正式環境資料,或開始遷移其他部分。
    在這個雲端環境中,將 [repository] 裡的 [module] 從 [current pinned version] 遷移至 [approved target version]。 閱讀 AGENTS.md、[migration brief]、[official migration guide]、相依套件鎖定檔、呼叫此模組的程式碼,以及 [contract test locations]。記錄起始提交、環境與設定的參考資料、已安裝的 Python 版本,以及鎖定檔的雜湊值。也請分別記錄框架、Pydantic 和隨附 v1 的版本。確認基準版本與目標版本的相容性。若需預先調整共用相依套件或匯入陳述式,請將這些調整列為獨立變更,另行審查。 先執行 [baseline commands],盤點遷移涉及的程式碼,並將簡短計畫寫入 [plan file]。遵守 [public contracts],不要修改 [out-of-scope modules]。只在核准的範圍內移除過時的程式碼,並列出所有必須保留的相容性轉接器名稱。 如果這部分可以獨立遷移,且基準狀態可供測試,請在變更前後執行同一組內容固定的 HTTP 契約測試,讓測試請求經過實際的路由器,並涵蓋實際的錯誤處理常式與回應序列化流程。比對狀態碼、契約規定的標頭、哪些輸入會被接受或拒絕、對外 JSON 的鍵與型別、預設值與 null 值,以及錯誤回應的完整結構與內容。也請針對受影響的部分執行整合測試、lint 檢查與型別檢查。如果需要擴大升級範圍或改變對外行為,請在擴大範圍前先回報需要決定的事項。不要核准新的測試快照、透過正規化掩蓋對外行為的差異,或放寬斷言條件。針對每項檢查,記錄程式碼修訂版、環境、軟體版本、變更前後執行的指令、結束代碼與證據檔案路徑。將結果標示為「通過」、「失敗」、「受阻」或「未執行」,並說明限制。 請提供差異檔、變更前後的證據、尚未解決的差異、相依套件與鎖定檔的變更、還原步驟,以及 Pull Request 說明草稿。只有在已連線的程式碼庫工具支援此操作,且我具備所需權限時,才建立草稿 Pull Request。否則請提供修補檔與說明。不要合併、部署、變更正式環境資料,或開始遷移其他部分。

    適用時機

    如果遷移範圍明確,且有測試可以比較遷移前後的行為,就適合使用這個工作流程。請提供 Codex 遷移說明、模組及呼叫該模組的程式碼、已固定的契約測試資料,以及準備好的雲端環境。請 Codex 完成一項範圍明確的變更,並提供驗證紀錄和回復步驟。

    這個範例將訂單服務中的一個驗證模型從 Pydantic v1 遷移到 v2。範例包含原始實作、相容性準備階段,以及遷移後的模組。測試會實際使用 FastAPI 路由器和錯誤處理常式,並檢查回應序列化、相鄰的舊版路由和公開的 OpenAPI 文件。範例不包含資料庫遷移或部署。

    準備雲端環境

    1. 選擇 工作位置 > 雲端,然後選取已發布的環境。

    2. 如要建立環境,請選取 建立環境,選擇 GitHub 程式碼庫,並請 Codex 準備執行環境、相依套件和隔離的測試服務。

    3. 檢閱設定報告,修正未通過的檢查項目,並在開始新任務前選取 發布。

    如果相依套件或服務設定有變更,請編輯可重複使用的環境,測試後選取 重新發布。

    請在新任務中驗證更新後的環境。重新整理程式碼庫時,系統會保留相依套件快取,不會重新執行安裝或啟動指令。既有任務也會保留各自的狀態。

    請另外設定需要連線的網路目的地和認證資訊。

    在每個階段記錄環境及其設定的參照資訊、原始碼提交、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."
        )

    在自己的程式碼庫中執行工作流程

    1. 撰寫遷移說明。 列出模組、直接呼叫該模組的程式碼、負責人、已核准的版本、契約測試、不在範圍內的程式碼,以及回復步驟。如果這部分遷移需要擴大相依套件的升級範圍,或會改變對外行為,請停止遷移。
    2. 建立基準。 請 Codex 閱讀 AGENTS.md、遷移說明、官方遷移指南、鎖定檔、呼叫端程式碼和測試。記錄起始提交和已安裝的版本。在判定遷移前後行為一致之前,請先說明基準檢查失敗的原因,或修正問題。
    3. 單獨準備相容性變更。 如果共用的相依套件讓模組與其他程式碼相互牽連,請先審查準備階段的變更。使用同一組測試資料,確認原始基準和準備後的基準都能通過測試。
    4. 一次遷移一個部分。 使用本頁提供的起始提示詞。修改模組和直接處理該模組的轉接器,保留不相關的模組,並列出仍保留的相容性程式碼。
    5. 執行相同的測試。 使用相同的 HTTP 和結構描述測試資料比較基準與最終結果,維持原有的預期結果。執行受影響的整合測試、lint 檢查和型別檢查,儲存輸出並註明對應的最終原始碼和相依套件狀態。
    6. 檢閱交接內容。 檢視程式碼差異、實測紀錄、尚未解決的差異、仍保留的相容層和回復步驟。只有在程式碼庫的工具和權限允許時,才建立 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 行為一致。請單獨記錄有意為之的差異。最終原始碼如有變更,請重新執行檢查。將範例套用到自己的應用程式時,請將實際的呼叫端和服務納入契約測試。

    相關應用案例