Day 29｜Protocol の変更 — 型・JSON・意味の3層で見る

Rust の型かたが変かわっても JSON は同おなじかもしれません。逆ぎゃくに JSON が読よめても、操作そうさの意味いみが変かわればクライアントは壊こわれます。互換性ごかんせいは一ひとつのチェックで済すませず、三みっつの層そうで見みる必要ひつようがあります。

01｜図でつかむ

Source・Wire・Semantic の三みっつを別々べつべつに検証けんしょうする。

02｜3つのポイントで理解する

1. Source compatibility を見る

呼び出よびだし側がわが再さいコンパイルできるか、型名かためいやフィールドの変更へんこうがどこへ影響えいきょうするかを調しらべます。内部ないぶリネームだけなら通信上つうしんじょうの名前なまえが維持いじされる場合ばあいもあります。

2. Wire compatibility を見る

serde や型かた生成せいせいの設定せっていから、実際じっさいの JSON 名めい・必須ひっす項目こうもく・null の扱あつかいを確認かくにんします。Rust の before_turn_id が camelCase の beforeTurnId として流ながれる、といった変換へんかんも対象たいしょうです。

3. Semantic compatibility を見る

同おなじ JSON でも、対象たいしょう turn を含ふくめるか除外じょがいするか、返答へんとう時点じてんで何なにが完了かんりょうしているかが変かわれば、利用りよう側がわの期待きたいが壊こわれます。schema の差分さぶんに出でない意味いみもテストで確認かくにんします。

03｜ソースで確かめる

以下いかの検索けんさくは Codex リポジトリのルートで実行じっこうします。最初さいしょに対象たいしょう commit を記録きろくし、検索結果けんさくけっかから定義ていぎと呼び出よびだし元もとを一ひとつずつ開ひらいてください。

git rev-parse --short HEAD
rg -n "before_turn_id|rename_all" codex-rs
# schema の生成差分も確認する場合
just write-app-server-schema
just test -p codex-app-server-protocol

テスト用ようツールはリポジトリの手順てじゅんに従したがって用意よういします。ここに載のせたコマンドは学習用がくしゅうようで、この編集作業へんしゅうさぎょうで Codex 本体ほんたいのテストを実行じっこうしたという記録きろくではありません。

読よむ入口いりぐち： codex-rs/app-server-protocol/src/protocol/v2/thread.rs 。リンク先さきは照合しょうごうに使つかった固定こてい commit のファイルです。手元てもとの版はんと異ことなる場合ばあいは、上うえの検索語けんさくごから探さがし直なおします。

小さく試す

一ひとつの API フィールドを選えらび、Rust 名めい、JSON 名めい、実行時じっこうじの意味いみを三さん列れつで書かきます。

04｜30秒で復習

全ぜん30章しょうの目次もくじへ