# データベースを起点にAPI契約を生成

データベースを起点に、OpenAPI、44,076行の型付きTypeScriptクライアント、61個のモックハンドラー、UIが適用する制限を生成し、各段階に不一致で失敗する検査を設けた。

2025

状況. フロントエンドとバックエンドは別々の速度で進み、リクエストのペイロードへの想定が、気づかないうちに食い違うことがある。通常は、不一致を公開したあと、ブラウザーの422応答で初めてわかる。最も修正費用が高い時点だった。同じ文書から両側を手で書いても、文書を読み直し忘れた人へ不一致の発生場所が移るだけだった。

課題. 両側で合意するのでなく単一の情報源から生成し、生成の各段階を信頼任せにせず検証する必要があった。

行動. 生成の連鎖をデータベースから外へ伸ばした。スキーマと関数が構造を、Goの型がAPIを定義し、HumaがOpenAPIを出力する。その記述から44,076行の型付きTypeScriptクライアントを生成し、61個のモックハンドラーも生成した。フロントエンドのテストは手書きの固定データではなく実際のAPI仕様に従う。フォームが適用する制限も検証器へ再入力せず、同じ場所から取得する。各段階に検査を設けた。CIで送信内容とAPIの期待値を比較し、不一致でビルドを止め、その下には記述でなく実際の構造を調べるスキーマ検査を置いた。特に「未指定」と「null」を混同しやすい任意の本文項目と、許容値が静かにずれやすいクエリ引数の列挙値を対象とした。

結果. 片側だけの項目変更は、気づいた最初の段階で、変更後数分のビルド中に失敗する。レビューでは見えず、実行時にしか現れなかった反復的で厄介なバグを除去した。代償は途中の再生成作業であり、連鎖の信頼性は最も守りの弱い箇所までしかない。そのため、各段階に検査を設けた。

役割: バックエンドエンジニア
=> /ja/categories/backend/ カテゴリー: バックエンド開発
=> /ja/categories/api/ カテゴリー: API・システム連携
=> /ja/categories/devops/ カテゴリー: DevOps
=> /ja/categories/automation/ カテゴリー: 自動化・CI/CD
=> /ja/categories/reliability/ カテゴリー: 信頼性・バックアップ
=> /ja/categories/testing/ カテゴリー: テスト・品質保証
=> /ja/services/backend-development/ サービス: バックエンド・API開発
=> /ja/services/ai-tools/ サービス: AIエージェント用ツール・MCPサーバー
=> /ja/services/devops-cicd/ サービス: DevOps・CI/CD自動化

=> https://software.engineer.company/ja/portfolio/generated-the-api-contract-from-the-database-out/ このページのウェブ版
