データベースを起点にAPI契約を生成
データベースを起点に、OpenAPI、44,076行の型付きTypeScriptクライアント、61個のモックハンドラー、UIが適用する制限を生成し、各段階に不一致で失敗する検査を設けた。
実施時期: 2025
44,076 DBから生成する型付きクライアントの行数
状況. フロントエンドとバックエンドは別々の速度で進み、リクエストのペイロードへの想定が、気づかないうちに食い違うことがある。通常は、不一致を公開したあと、ブラウザーの422応答で初めてわかる。最も修正費用が高い時点だった。同じ文書から両側を手で書いても、文書を読み直し忘れた人へ不一致の発生場所が移るだけだった。
課題. 両側で合意するのでなく単一の情報源から生成し、生成の各段階を信頼任せにせず検証する必要があった。
行動. 生成の連鎖をデータベースから外へ伸ばした。スキーマと関数が構造を、Goの型がAPIを定義し、HumaがOpenAPIを出力する。その記述から44,076行の型付きTypeScriptクライアントを生成し、61個のモックハンドラーも生成した。フロントエンドのテストは手書きの固定データではなく実際のAPI仕様に従う。フォームが適用する制限も検証器へ再入力せず、同じ場所から取得する。各段階に検査を設けた。CIで送信内容とAPIの期待値を比較し、不一致でビルドを止め、その下には記述でなく実際の構造を調べるスキーマ検査を置いた。特に「未指定」と「null」を混同しやすい任意の本文項目と、許容値が静かにずれやすいクエリ引数の列挙値を対象とした。
結果. 片側だけの項目変更は、気づいた最初の段階で、変更後数分のビルド中に失敗する。レビューでは見えず、実行時にしか現れなかった反復的で厄介なバグを除去した。代償は途中の再生成作業であり、連鎖の信頼性は最も守りの弱い箇所までしかない。そのため、各段階に検査を設けた。

写真: 422737 / Pixabay 
写真: rkit / Pixabay
前の実績: APIを100%の一致でHuma v2へ移行. 次に読む: 切り替えと配信ログを備えるメール機能を構築. すべての実績はこちら: 実績紹介.

