Anwendungsfall für Codex
Ein Validierungsmodul migrieren
Aktualisiere ein Modul und weise nach, dass sich seine öffentliche Schnittstelle wie bisher verhält.
Gib Codex einen klar abgegrenzten Migrationsauftrag, Test-Fixtures für die Schnittstellenverträge und eine vorbereitete Cloud-Umgebung. Lass Codex ein einzelnes Validierungsmodul aktualisieren. Du erhältst die gezielte Codeänderung, einen Vorher-Nachher-Vergleich des Schnittstellenverhaltens, eine Übersicht der verbleibenden Unterschiede und eine Anleitung zum Zurücksetzen.
Besonders geeignet für
- Entwicklungsteams, die eine ältere Validierungskomponente migrieren.
- Migrationen mit klar definierten Schnittstellenverträgen und wiederholbaren Tests.
- Teams, die eine kleine, geprüfte Änderung benötigen, während die übrigen Module weiterlaufen.
Inhalt
Ein Validierungsmodul migrieren
Aktualisiere ein Modul und weise nach, dass sich seine öffentliche Schnittstelle wie bisher verhält.
Gib Codex einen klar abgegrenzten Migrationsauftrag, Test-Fixtures für die Schnittstellenverträge und eine vorbereitete Cloud-Umgebung. Lass Codex ein einzelnes Validierungsmodul aktualisieren. Du erhältst die gezielte Codeänderung, einen Vorher-Nachher-Vergleich des Schnittstellenverhaltens, eine Übersicht der verbleibenden Unterschiede und eine Anleitung zum Zurücksetzen.
Gib Codex einen klar abgegrenzten Migrationsauftrag, Test-Fixtures für die Schnittstellenverträge und eine vorbereitete Cloud-Umgebung. Lass Codex ein einzelnes Validierungsmodul aktualisieren. Du erhältst die gezielte Codeänderung, einen Vorher-Nachher-Vergleich des Schnittstellenverhaltens, eine Übersicht der verbleibenden Unterschiede und eine Anleitung zum Zurücksetzen.
Weiterführende Links
Besonders geeignet für
- Entwicklungsteams, die eine ältere Validierungskomponente migrieren.
- Migrationen mit klar definierten Schnittstellenverträgen und wiederholbaren Tests.
- Teams, die eine kleine, geprüfte Änderung benötigen, während die übrigen Module weiterlaufen.
Prompt für den Einstieg
Wann sich dieser Ablauf eignet
Nutze diesen Ablauf, wenn die Migration klar abgegrenzt ist und Tests das bisherige mit dem neuen Verhalten vergleichen. Gib Codex den Migrationsauftrag, das Modul und den Code, der es aufruft, festgeschriebene Fixtures für die Vertragstests und eine vorbereitete Cloud-Umgebung. Bitte Codex um eine gezielte Änderung, Belege für die Testergebnisse und eine Anleitung zum Zurücksetzen der Änderung.
Das Beispiel migriert ein einzelnes Validierungsmodell in einem Bestellservice von Pydantic v1 auf v2. Es enthält die ursprüngliche Implementierung, einen für die Umstellung vorbereiteten Zwischenstand und die endgültige Modulversion. Die Tests prüfen den tatsächlichen FastAPI-Router, die Fehlerbehandlung, die Serialisierung der Antworten, die benachbarte Legacy-Route und das öffentliche OpenAPI-Dokument. Eine Datenbankmigration oder ein Deployment ist nicht Teil des Beispiels.
Cloud-Umgebung vorbereiten
-
Wähle Arbeiten in > Cloud und dann eine veröffentlichte Umgebung aus.
-
Um eine Umgebung zu erstellen, wähle Umgebung erstellen und anschließend die GitHub-Repositorys aus. Bitte Codex, die Laufzeitumgebung, die Abhängigkeiten und die isolierten Testdienste vorzubereiten.
-
Prüfe den Setup-Bericht, behebe die Ursachen fehlgeschlagener Prüfungen und wähle Veröffentlichen, bevor du eine neue Aufgabe startest.
- Folge der Anleitung für Cloud-Umgebungen.
- Halte Anweisungen für das Repository in AGENTS.md fest.
Wenn sich Abhängigkeiten oder das Setup der Dienste ändern, passe die wiederverwendbare Umgebung an, teste sie und wähle Erneut veröffentlichen.
Prüfe die aktualisierte Umgebung in einer neuen Aufgabe. Beim Aktualisieren des Repositorys bleiben die zwischengespeicherten Abhängigkeiten erhalten. Installations- und Startbefehle werden dabei nicht erneut ausgeführt. Bestehende Aufgaben behalten ihren eigenen Zustand.
Konfiguriere die erforderlichen Netzwerkziele und Zugangsdaten separat.
Dokumentiere für jede Stufe die Referenz auf die Umgebung und ihr Setup, den Commit des Quellcodes, die Python-Patchversion, die Versionen des Frameworks und der Abhängigkeiten, die Version des Paketmanagers und den Hash der Lockdatei. Prüfe diese Versionen innerhalb der neuen Aufgabe, bevor du ihre Ergebnisse verwendest.
Beispiel ausführen
Lade das vollständige Migrationsbeispiel herunter. Es enthält drei eigenständige uv-Projekte, ihre uv.lock-Dateien mit den aufgelösten Abhängigkeiten, die Implementierungen der Anwendung, einen gemeinsamen Adapter für Fehler und Schemas, festgeschriebene HTTP-Fixtures und das Skript für die Vertragstests.
Verwende Python 3.11, 3.12 oder 3.13 und installiere uv. Führe dann die folgenden Befehle aus:
unzip sample.zip
cd migrate-a-validation-module
uv run --project support/target --python python3 --frozen python run.py --compare-stages --output evidence
Für den Vergleich erstellt das Skript für jede Stufe eine eigene .venv und installiert die Abhängigkeiten mit uv sync --frozen. Alle Stufen verwenden den Python-Interpreter, mit dem du das Skript aufrufst, sowie dieselben HTTP- und Schema-Fixtures. Die Versionen der Abhängigkeiten bleiben festgeschrieben.
Python 3.14 und neuere Versionen sind ausgeschlossen, weil die Kompatibilitätsschicht für Pydantic v1 sie nicht unterstützt. Ein erfolgreicher Lauf endet mit dieser Ausgabe:
PASS: legacy, prepared, target HTTP/schema/serialization contracts match
Native model schemas differ; the existing public schema adapter is preserved.
Sieh dir evidence/legacy.json, prepared.json, target.json und summary.json an. Sie enthalten die beobachteten Antworten, die Laufzeitversionen, die Hashes von Quellcode, Fixtures und Lockdateien, die ausgeführten Befehle, die Exitcodes und die Pfade zu den unverarbeiteten Protokollen.
Das Testskript prüft die HTTP-Endpunkte der Beispielanwendung mit dem in FastAPI integrierten TestClient im selben Prozess. Führe es in der gewählten Cloud-Aufgabe aus und bewahre die Nachweise aus dieser Aufgabe auf.
Führe python3 run.py ohne --compare-stages nur aus, wenn du das Zielmodell in einer Umgebung mit installiertem Pydantic v2 prüfen möchtest. Dieser eigenständige Modus prüft sieben Fälle zur Validierung und Serialisierung. Er führt weder HTTP-Tests noch Vergleiche zwischen den Stufen durch. Verwende den vollständigen Vergleichsbefehl oben, um eine Migration zu überprüfen.
Der vollständige Vergleich prüft in jeder Stufe 23 HTTP-Fälle, das öffentliche OpenAPI-Dokument und die Serialisierung der Antworten. Lokal war der Vergleich mit Python 3.11, 3.12 und 3.13 erfolgreich. Die mitgelieferte README.md dokumentiert die getesteten Versionen und die bisherigen Testläufe. Führe den aktuellen Vergleich in deiner Cloud-Umgebung aus, um die Ergebnisse dort zu dokumentieren.
Abhängigkeiten der einzelnen Stufen getrennt halten
| Stufe | Python / FastAPI / Pydantic |
Umfang der Migration |
|---|---|---|
| Ausgangsstand | 3.11–3.13 / 0.119.0 / 1.10.22 |
Die bestehenden Modelle importieren aus pydantic. |
| Vorbereiteter Ausgangsstand | 3.11–3.13 / 0.119.0 / 2.12.3 |
Beide Modelle verwenden pydantic.v1. Dokumentiere die tatsächlich mitgelieferte v1-Version. |
| Zielstand | 3.11–3.13 / 0.119.0 / 2.12.3 |
Nur OrderInput wechselt auf v2. Die benachbarte Route behält ihr eigenes v1-Modell. |
Die Lockdateien für den vorbereiteten Ausgangsstand und den Zielstand sind identisch. Die Migration des Moduls ändert das Modell und die Methode, mit der es direkt serialisiert wird. Die Abhängigkeiten bleiben gleich.
Die Vorbereitung ist eine eigenständige Änderung, die separat geprüft wird. Dabei werden auch die Adapter der verbleibenden v1-Routen so angepasst, dass sie vor der Antwortvalidierung mit dict(by_alias=True) Dictionaries mit Aliasnamen als Schlüsseln ausgeben. Gibt eine Route unter dem v2-Host das v1-Modell direkt zurück, können öffentliche Aliasnamen verloren gehen.
Im Zielstand verwendet der Adapter für Bestellungen model_dump(by_alias=True). Die benachbarte v1-Route behält den Adapter aus dem Vorbereitungsschritt.
Laut FastAPI-Migrationsleitfaden unterstützen nur die Versionen 0.119.0 bis 0.127.x vorübergehend den gemischten Betrieb von v1- und v2-Routen. Mit 0.128.0 entfiel diese Unterstützung.
Das Beispiel legt die Version bewusst auf 0.119.0 fest, um diesen Übergang zu zeigen. Verwende in einer neueren FastAPI-Anwendung im gesamten Migrationsbereich v2. Halte für die vorübergehende Kompatibilitätsschicht fest, wer verantwortlich ist und unter welcher Bedingung sie entfernt wird. Verschachtle v1- und v2-Modelle nicht miteinander. Diese Kompatibilitätsschicht eignet sich nicht für eine Migration auf Python 3.14.
Vertragstests prüfen
Die festgeschriebenen HTTP-Testfälle decken erfolgreiche Anfragen, eine weggelassene oder ausdrücklich auf null gesetzte Notiz, fehlende und ungültige IDs, mehrere unbekannte Felder, Kombinationen verschiedener Feldfehler und ungültige Notizen ab. Sie prüfen außerdem fehlerhaftes JSON, einen falschen Inhaltstyp, einen fehlenden Anfragekörper, Aliasnamen, Arrays und Zeichenketten als Anfragekörper sowie die benachbarte Legacy-Route. Die Tests vergleichen Statuscodes, den Content-Type-Header und die vollständigen geparsten JSON-Antworten. Dabei entfernen sie keine Fehlerfelder und ändern keine erwarteten Typen.
Der Dienst verwendet seit dem Ausgangsstand ein von der Anwendung vorgegebenes Format für Fehlerantworten und ein öffentliches OpenAPI-Dokument. Die Adapter für Fehler und Schemas bleiben erhalten. Im Zielstand erscheinen die Fehler in derselben Reihenfolge wie zuvor: zuerst die Fehler für deklarierte Felder, danach die unbekannten Schlüssel in alphabetischer Reihenfolge.
Die Tests vergleichen das gesamte Array error.fields in der vorliegenden Reihenfolge. Sie sortieren die beobachteten Antworten nicht. Das Testskript zeichnet das native Schema jedes Modells separat auf und prüft, dass sich die nativen Schemas unterscheiden. Auch wenn die öffentlichen Schemas übereinstimmen, können die von der Abhängigkeit generierten Schemas unterschiedlich sein.
Der Dienst verarbeitet Eingaben weiterhin wie im Ausgangsstand. Er akzeptiert ein Array aus Paaren wie [["order_id", "ord_123"]] als Objekt. Sowohl [] als auch eine leere JSON-Zeichenkette werden zu leeren Objekten und lösen einen Fehler wegen der fehlenden ID aus. Eine nicht leere Zeichenkette bleibt als Anfragekörper ungültig. Das Zielmodell übernimmt weiterhin alle Werte, die sich mit dict(value) erfolgreich umwandeln lassen. Soll es ausschließlich Objekte akzeptieren, muss die verantwortliche Person über diese Änderung des Vertrags entscheiden. Es reicht nicht, die erwarteten Testergebnisse umzuschreiben.
Halte für dein Repository vor jeder Änderung die tatsächlichen Antworten des bestehenden Systems als feste Testdaten fest. Behalte optionale Felder mit ihren expliziten Standardwerten bei. Achte darauf, dass die Validierung genauso streng bleibt und unbekannte Felder wie bisher behandelt werden. Teste die tatsächliche Fehlerbehandlung und die Serialisierung der Antworten.
Die unbearbeiteten Validierungsfehler unterscheiden sich je nach Version. Der Pydantic-Migrationsleitfaden beschreibt auch Änderungen an Aliasnamen, impliziten Typumwandlungen, optionalen Feldern und benutzerdefinierten Validierungsfunktionen. In v2 wird ein innerhalb dieser Funktionen ausgelöster TypeError nicht in einen ValidationError umgewandelt.
Testskript für den Vertragsvergleich ansehen
Dieser Ausschnitt stammt aus der mitgelieferten Datei run.py. Entpacke das ZIP-Archiv und führe die vollständigen Dateien aus. Das Archiv enthält die Stufen mit festgeschriebenen Abhängigkeiten und die HTTP-Fixtures.
Die drei Stufen vergleichen
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."
)Migration in deinem Repository durchführen
- Formuliere den Auftrag. Nenne das Modul, die direkten Aufrufstellen, die verantwortliche Person, die freigegebenen Versionen, die Vertragstests und den Code, der außerhalb des Auftrags liegt. Beschreibe, wie sich die Änderung zurücksetzen lässt. Brich ab, wenn der Migrationsschritt eine umfassendere Aktualisierung der Abhängigkeiten erfordert oder das öffentliche Verhalten ändert.
- Ermittle den Ausgangsstand. Lass Codex
AGENTS.md, den Auftrag, die offiziellen Migrationshinweise, die Lockdateien, die Aufrufstellen und die Tests lesen. Dokumentiere den Ausgangs-Commit und die installierten Versionen. Wenn Prüfungen schon im Ausgangsstand fehlschlagen, erkläre oder behebe die Ursache, bevor du von übereinstimmendem Verhalten sprichst. - Bereite die Kompatibilität separat vor. Wenn das Modul über gemeinsame Abhängigkeiten mit anderem Code gekoppelt ist, prüfe zuerst die vorbereitende Änderung. Weise nach, dass die Tests mit denselben Fixtures sowohl im ursprünglichen als auch im vorbereiteten Ausgangsstand erfolgreich sind.
- Migriere einen abgegrenzten Teil. Verwende den Einstiegsprompt auf dieser Seite. Ändere das Modul und seinen direkten Adapter. Lass unbeteiligte Module unverändert und benenne den Kompatibilitätscode, der bestehen bleibt.
- Führe dieselben Tests aus. Vergleiche Ausgangs- und Zielstand anhand der HTTP- und Schema-Fixtures, ohne die erwarteten Ergebnisse zu ändern. Führe die betroffenen Integrationstests, Lint- und Typprüfungen aus. Speichere die Ausgaben so, dass sie sich dem endgültigen Stand des Quellcodes und der Abhängigkeiten zuordnen lassen.
- Prüfe die Übergabe. Sieh dir den Diff, die dokumentierten Testergebnisse, ungeklärte Abweichungen, die verbleibende Kompatibilitätsschicht und die Anleitung zum Zurücksetzen an. Erstelle nur dann einen Pull Request als Entwurf, wenn die Werkzeuge und Berechtigungen im Repository das zulassen. Überlasse das Zusammenführen, das Deployment und den nächsten Migrationsschritt der Person, die die Änderung prüft.
Prüfergebnisse dokumentieren
Halte die Nachweise für jedes Kriterium einzeln fest:
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]
Ein erfolgreicher Import, eine bestandene Lint-Prüfung oder ein neu generierter Snapshot belegt noch nicht, dass sich die API wie zuvor verhält. Dokumentiere beabsichtigte Abweichungen separat und wiederhole die Prüfungen, wenn sich der endgültige Quellcode ändert. Wenn du das Beispiel anpasst, beziehe die Aufrufstellen und Dienste deiner Anwendung in die Vertragstests ein.
Verwandte Anwendungsfälle
Einen Vorfall untersuchen und die Fehlerbehebung testen
Stelle Codex Cloud bereinigte Unterlagen zum Vorfall und eine funktionsfähige Testumgebung...
Browserspiele entwickeln
Beschreibe deine Spielidee kurz. Codex kann daraus einen konkreten Plan entwickeln und ihn...
Code migrieren
Ordne mit Codex die Bestandteile eines Altsystems dem neuen Stack zu