あえてスキーマ駆動開発を見送った話

「泥くさい課題と向き合うフロントエンド KINTOテクノロジーズ with MixLeap Study」で発表したスライドです。
https://kinto-technologies.connpass.com/event/352670/

1. あえてスキーマ駆動開発を見送った話 2025/05/14 〜泥臭く手書き型定義で完走して気づいたこと〜
2. 自己紹介 楢林 祐輝 / Yuki Narabayashi KINTO テクノロジーズ株式会社 フロントエンドエンジニア
3. 本日の話について前置き 全体的に、何か理論的にもとづいたものではなく、 あくまでわたし自身の経験にもとづく話になります。 そのため必ずしもみなさんの状況や ご意見と合わない箇所があると思います。 ご了承のほどお願いします また、この話の「スキーマ駆動開発」は 「OpenAPI からフロントエンドのコード生成を行うこと」 を意味しています。
4. Agenda 1 スキーマ駆動開発で気になったこと 2 見送り→手書きのわけ 3 見送って気づいたこと 4 まとめ 5 6 アジェンダ
5. スキーマ駆動開発で気になったこと 1
6. 過去プロジェクトでスキーマ駆動開発導入のきっかけ Web アプリの新規開発プロジェクトがスタート。 フロントエンドとバックエンドは分業で、わたしはフロントエンド担当でした。 ただでさえ UI を作るのは大変なので、可能なところはできる限り省力化したい。。。 という思いがありました。
7. プロジェクトの状況 • スクラム開発（2 週間スプリント） • フロントエンド・バックエンドで人員が別れており、スキーマファーストな進め方 • 各人員、とにかく時間が取れない ⇒フロントエンドも OpenAPI を活用しよう！ と決断 スキーマ駆動開発を採用し、生成したコードをがんがん使っていく方針を取る
8. Orval で OpenAPI からコード生成
9. Orval はいろいろ対応している
10. スキーマ駆動開発を採用した結果 • 型とカスタムフック生成で開発速度はバッチリ！ • 日々進化する API の変更も楽々追従！
11. ……と思いきや？ • 型とカスタムフック生成で初速はバッチリ！ • 日々進化する API の変更も楽々追従！ あれ……？ ちょっとずつ API の変更がつらくなってきたぞ…… なんで……？
12. なぜ API の変更がつらくなってきたのか？ • Orval の出力したコードがいろんなところに点在→変更のたびに修正箇所が増える • 感覚的に、なんとなくゆるやかに負債になっているような。。。 • しかし本当に負債なのか確信は持てず、問題にもできず。。。
13. その他、運用面のつらみもいくつか • バックエンドとフロントエンドで出力結果が微妙に異なる場合があった • この時のやりとりは非常に面倒…… • 納得してもらうためには何が正しいかだけでなく「なぜ正しいか」を提示しなければならない • OpenAPI をそのまま書いていたこともあり、OpenAPI 自体のチェックが大変
14. スキーマ駆動開発を実践した感想 めちゃくちゃ便利だけど、 API と強く結びついてしまうような感覚を どうしても拭えない。。。 でも使っているプロジェクトでは やめるほどの強い問題でもないし 便利なのは確かだし。。。 うーん。。。難しい
15. 見送り→手書きのわけ 2
16. その後、時は流れて新たなプロジェクトへ • 社内向けの管理システムの新規開発 • PJ の進め方はウォーターフォール寄り • 人員の都合で、設計や技術選定・開発環境構築などは自分が行う
17. その時に採用したもの（一部）
18. プロジェクトでの OpenAPI の状態 • 設計フェーズで OpenAPI を作成 • つまり開発時点で OpenAPI が存在していた • 開発後はバックエンドから OpenAPI を出力し、最新化していく • いわゆるコードファーストな形 • なので、フロントエンドはいつでも OpenAPI からコード生成できる状態だった ⇒スキーマ駆動開発のチャンス
19. プロジェクトでの OpenAPI の状態 • 設計フェーズで OpenAPI を作成 • つまり開発時点で OpenAPI が存在していた • 開発後はバックエンドから OpenAPI を出力し、最新化していく • いわゆるコードファーストな形 • なので、フロントエンドはいつでも OpenAPI からコード生成できる状態だった ⇒スキーマ駆動開発のチャンス しかしこのプロジェクトでは スキーマ駆動開発を見送ることにしました
20. スキーマ駆動開発を見送った理由 • 過去 PJ で感じた懸念を解決できていない • 方針を定めようにも、どういう形がベストなのかを落とし込めていない。 • 泥臭いが、いっそのこと手動で型定義した方がキレイかつ進めやすいのでは？ • スキーマ駆動ゆえのトラブルを避けられる。 • 本当に必要な型定義を用意できる。 • スピードは落ちるが、長い目で見ても愚直に書いたほうがメリットなのでは。。。？ • メンバー構成を見ても、自分がある程度変更を把握・コントロールできるので、逆に安全かも。。。
21. 見送って気づいたこと 3
22. スキーマ駆動開発を見送った結果、どうだったか？ 開発速度の不安が強かったが、案外問題なかった。 その１ 型定義が至るところに散らばることもなかった。 その２ API 仕様の変更にも問題なく追従できた。 その３
23. スキーマ駆動開発を見送った結果、どうだったか？ 開発速度の不安が強かったが、案外問題なかった。 その１ 型定義が至るところに散らばることもなかった。 その２ API 仕様の変更にも問題なく追従できた。 その３ 手書きサイコー！
24. スキーマ駆動開発を見送った結果、どうだったか？ 開発速度の不安が強かったが、案外問題なかった。 その１ 型定義が至るところに散らばることもなかった。 その２ API 仕様の変更にも問題なく追従できた。 その３ 手書きサイコー！ そんなわけなくない……？ 手書きしただけで なんでこんなに絶大な効果があるの……？ 手書きを決断した自分が言うのもなんだけど、 これはさすがにおかしい…… 前回と今回の違いから 何がうまくいったのかを考えてみたい
25. 前回と今回のプロジェクトの比較 前回 • スクラム開発で変更が多い • フロントエンド・バックエンドが分業で 共通言語が必要→OpenAPI が必要 • だからスキーマ駆動開発は間違いではな かったし、非常に効果があった ⇒負債化の懸念はさておき、スキーマ駆動 開発でなければ厳しかった 今回 • ウォーターフォールで変更が多くない • 自分が両方の開発に介在していた →OpenAPI がなくとも会話できる • 手書きにしたことで依存をなくし、上記 理由で開発スピードも落とさずに済んだ ⇒プロジェクトの特性と取った選択がうま くマッチした
26. 前回と今回のプロジェクトの比較 前回 • スクラム開発で変更が多い • フロントエンド・バックエンドが分業で 共通言語が必要→OpenAPI が必要 • だからスキーマ駆動開発は間違いではな かったし、非常に効果があった ⇒負債化の懸念はさておき、スキーマ駆動 開発でなければ厳しかった 今回 • ウォーターフォールで変更が多くない • 自分が両方の開発に介在していた →OpenAPI がなくとも会話できる • 手書きにしたことで依存をなくし、上記 理由で開発スピードも落とさずに済んだ ⇒プロジェクトの特性と取った選択がうま くマッチした
27. 前回と今回のプロジェクトの比較 前回 • スクラム開発で変更が多い • フロントエンド・バックエンドが分業で 共通言語が必要→OpenAPI が必要 • だからスキーマ駆動開発は間違いではな かったし、非常に効果があった ⇒負債化の懸念はさておき、スキーマ駆動 開発でなければ厳しかった 今回 • ウォーターフォールで変更が少ない • 自分が両方の開発に介在していた →OpenAPI がなくとも会話できる • 手書きにしたことで依存をなくし、上記 理由で開発スピードも落とさずに済んだ ⇒プロジェクトの特性と取った選択がうま くマッチした では前回のプロジェクトで感じた スキーマ駆動開発による負債化していく感覚は なんだったのだろう……？ 今回のプロジェクトの効果を考えてみる
28. （再掲）スキーマ駆動開発を見送った結果、どうだったか？ 開発速度の不安が強かったが、案外問題なかった。 その１ 型定義が至るところに散らばることもなかった。 その２ API 仕様の変更にも問題なく追従できた。 その３
29. （再掲）スキーマ駆動開発を見送った結果、どうだったか？ 開発速度の不安が強かったが、案外問題なかった。 その１ なぜ 自分で設計できて、かつ設計時点で OpenAPI ができあがっていたことが良かっ たのでは？ ウォーターフォール寄りのプロジェクトであり、設計段階から頻繁な変更は発 生しなかった（なかったとは言わない）。
30. （再掲）スキーマ駆動開発を見送った結果、どうだったか？ Feature-Sliced Design というディレクトリ構成 で型定義を一箇所にまとめた。 また、ベースになるエンティティから Pick・ Omit を使うなどして必要な情報だけ渡し、 API 変更に強く影響しないように工夫した。 型定義が至るところに 散らばることもなかった。 その ２ API 仕様の変更にも 問題なく追従できた。 その ３ Remix の clientLoader/clientAction 関数経由で fetch 関数を呼び出すようにしたことで、 腐敗防止層になってくれていた。
31. （再掲）スキーマ駆動開発を見送った結果、どうだったか？ Feature-Sliced Design というディレクトリ構成 で型定義を一箇所にまとめた。 また、ベースになるエンティティから Pick・ Omit を使うなどして必要な情報だけ渡し、 API 変更に強く影響しないように工夫した。 型定義が至るところに 散らばることもなかった。 その ２ API 仕様の変更にも 問題なく追従できた。 その ３ Remix の clientLoader/clientAction 関数経由で fetch 関数を呼び出すようにしたことで、 腐敗防止層になってくれていた。
32. （再掲）スキーマ駆動開発を見送った結果、どうだったか？ Feature-Sliced Design というディレクトリ構成 で型定義を一箇所にまとめた。 また、ベースになるエンティティから Pick・ Omit を使うなどして必要な情報だけ渡し、 API 変更に強く影響しないように工夫した。 型定義が至るところに 散らばることもなかった。 その ２ API 仕様の変更にも 問題なく追従できた。 その ３ Remix の clientLoader/clientAction 関数経由で fetch 関数を呼び出すようにしたことで、 腐敗防止層になってくれていた。 ということは、 自分にとってスキーマ駆動開発で ほしかったものは手書き型定義じゃなく、 ただの腐敗防止層的な役割だった……？
33. 腐敗防止層の役割 API の レスポンス コンポーネン トなど API をコール fetch など API に依存する箇所 変換処理 (腐敗防止層) API への依存を 最小限に 安全な領域
34. 今回のプロジェクトにあてはめると？ API の レスポンス コンポーネン トなど fetch 関数 API に依存する箇所 Remix loader/action フロントエンドが 要求する型 （手書きの型定義）に 変換 安全な領域
35. 今回のプロジェクトにあてはめると？ API の レスポンス コンポーネン トなど fetch 関数 API に依存する箇所 Remix loader/action フロントエンドが 要求する型 （手書きの型定義）に 変換 安全な領域 たまたまうまくハマっただけだった…… 手書きだからうまくいったのではなくて、 いろんな要素が たまたまうまくハマっただけだった……
36. では手書き型定義は無意味だった？ やってみて感じたこと • 今回のような頻繁に API が変化するような状況でなければ選択肢としてアリ。 • （Copilot のようなコード補完があればそんなにつらくもない） • 特に OpenAPI からのコード生成にまつわるトラブルはなくなった。 • コードジェネレータへの依存をなくせた、と考えることもできる。
37. スキーマ駆動開発か手書きか どちらを選ぶかは諸々の状況で決めれば良いのでは？ • フロントエンド・バックエンドでエンジニアが異なる→スキーマ駆動開発 • フロントエンド・バックエンドで同じエンジニアが対応する→好きな方で 経験上、どちらを選んでもスキーマに依存しすぎない対応が大事と感じる そこを対応できればスキーマ駆動開発は「大は小を兼ねる」選択と考えて良さそう
38. そして両方ためして気づけたスキーマ駆動開発のメリット • 具体的な I/F をもとにコミュニケーションできること • そして、その設計（＝OpenAPI）をそのままコードとして活用できること
39. そして次のプロジェクトへ…… • あらためてスキーマ駆動開発を取り入れる • フロントエンド・バックエンドで設計・開発が分業されている • OpenAPI ができた時点で一度 Orval のコード生成→正しい型になることを確認 • Orval の恩恵を最大限受けられるよう TanStack Query を採用 • 型とカスタムフックは直接使わず、ラッパーおよび型変換処理を通して疎結合にする ⇒今後、どの程度の負担になるかは未知数だが、いまのところ大きな問題は起きていない スキーマ駆動開発のメリットも得られているのでそこまでの心配はない
40. まとめ 4
41. まとめ • スキーマ駆動開発の採用→見送りを経験したらそれぞれの良さに気づくことができた • 大抵の場面ではやはりスキーマ駆動開発の方が便利 • しかしそれも絶対ではなく様々な事情や状況によるので、都度良い選択をしていきたい • あらためて API への依存は強くしない方が良いと感じた
42. Thank you !