如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .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 契约测试,确保测试请求经过实际使用的路由器,并按实际流程处理错误和序列化响应。对比状态码、契约规定的 HTTP 标头、哪些输入被接受或拒绝、对外返回的 JSON 键及其值的类型、默认值、null 值,以及完整的错误响应结构。还要运行受影响的集成测试、代码规范检查和类型检查。如果迁移需要扩大升级范围或改变对外行为,请先报告这一判断,再考虑扩大范围。不要批准新快照,不要通过归一化掩盖对外行为差异,也不要放宽断言。对每项检查,记录所用的代码修订版本、环境和软件版本,以及改动前后执行的命令、退出码和验证材料的路径。注明每项检查的状态(通过、失败、受阻或未运行)及其局限性。 返回代码差异、改动前后的验证材料、尚未解决的差异、依赖项和锁文件的变更、回滚步骤,以及 Pull Request 描述草稿。仅当已连接的代码仓库工具支持创建草稿 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 契约测试,确保测试请求经过实际使用的路由器,并按实际流程处理错误和序列化响应。对比状态码、契约规定的 HTTP 标头、哪些输入被接受或拒绝、对外返回的 JSON 键及其值的类型、默认值、null 值,以及完整的错误响应结构。还要运行受影响的集成测试、代码规范检查和类型检查。如果迁移需要扩大升级范围或改变对外行为,请先报告这一判断,再考虑扩大范围。不要批准新快照,不要通过归一化掩盖对外行为差异,也不要放宽断言。对每项检查,记录所用的代码修订版本、环境和软件版本,以及改动前后执行的命令、退出码和验证材料的路径。注明每项检查的状态(通过、失败、受阻或未运行)及其局限性。 返回代码差异、改动前后的验证材料、尚未解决的差异、依赖项和锁文件的变更、回滚步骤,以及 Pull Request 描述草稿。仅当已连接的代码仓库工具支持创建草稿 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 与模式测试数据,依赖项版本始终保持锁定。

    此示例不支持 Python 3.14 及更高版本,因为旧版 Pydantic v1 兼容层不支持这些版本。运行成功时,最后会输出:

    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 模型。此兼容层不适用于迁移到 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 和模式测试数据比较基线与最终结果,保持预期结果不变。对受影响的部分运行集成测试、代码风格检查和类型检查,保存输出,并注明对应的最终源代码和依赖状态。
    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]

    成功导入模块、通过代码风格检查或重新生成快照,都不足以证明迁移前后的 API 行为一致。单独记录有意保留的差异,并在最终源代码发生变化时重新运行检查。将此示例改用于您的应用时,请将应用的调用方和服务纳入契约测试。

    相关使用场景