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 与模式测试数据,依赖项版本始终保持锁定。
此示例不支持 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."
)在您的代码仓库中运行工作流
- 编写迁移说明。 列出模块、直接调用方、负责人、已批准的版本、契约测试、不在迁移范围内的代码,以及回滚步骤。如果此次迁移需要扩大依赖升级范围或改变对外行为,请停止迁移。
- 建立基线。 让 Codex 阅读
AGENTS.md、迁移说明和官方迁移指南,并检查锁文件、调用方和测试。记录起始提交和已安装的版本。如果基线检查失败,请先说明原因或修复问题,再判断迁移前后的行为是否一致。 - 单独完成兼容性准备。 如果模块通过共享依赖项与其他代码耦合,请先审查兼容性准备所需的改动。用同一套测试数据验证原始基线和准备后的基线都能通过测试。
- 迁移一个范围明确的部分。 使用本页提供的起始提示词。修改模块及其直接使用的适配器,保留无关模块,并指出仍在使用的兼容性代码。
- 运行相同的测试。 使用同一套 HTTP 和模式测试数据比较基线与最终结果,保持预期结果不变。对受影响的部分运行集成测试、代码风格检查和类型检查,保存输出,并注明对应的最终源代码和依赖状态。
- 审查交接材料。 检查代码差异、实际测试证据、尚未解决的差异、仍在使用的兼容层和回滚方案。仅在代码仓库工具和权限支持时创建草稿 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 行为一致。单独记录有意保留的差异,并在最终源代码发生变化时重新运行检查。将此示例改用于您的应用时,请将应用的调用方和服务纳入契约测试。
相关使用场景
调查故障并测试修复方案
向 Codex 云端提供经过脱敏的故障资料和可用的测试环境,让它分析证据,复现有证据支持的代码缺陷,并提供针对性补丁、回归测试证据以及部署和回滚交接材料。
创建 Codex 能用的 CLI
请 Codex 创建一个可组合使用的 CLI。Codex 可以在任意文件夹中运行它,将它与代码仓库中的脚本配合使用,用它下载文件,并通过配套技能记住它的用法。
开发网页游戏
让 Codex 根据游戏设计概要制定清晰的开发计划,再按计划做出可玩的网页游戏。使用 imagegen 生成美术素材,让 Codex 在真实浏览器中试玩,逐步改进游戏操控和界面。