コード生成時代のAPI定義を支えるRequest Spec移行

北陸Ruby会議02
https://regional.rubykaigi.org/hokuriku02/index.html

1. 北陸Ruby会議02 コード生成時代の API定義を支える Request Spec移行 @pvcresin
2. 自己紹介 pvcresin（レジン） 仕事 SansanでEightのWebエンジニア 興味 フロントエンド／デザイン／型 出没 Asakusa-bashi.rbs／Omotesando.rb 恐竜 カルノタウルス
3. 話の中心 歴史ある大規模アプリケーションに残っていた 120個のController SpecをRequest Specに移行し 「API定義と実装の一致」をテストで担保した事例
4. 目次 - API定義の重要性 - 実装とのズレをどう防ぐか - Request Spec移行 - 継続的にズレを修正するための仕組み - 移行の結果
5. API定義の重要性
6. API定義の重要性 - スキーマ駆動開発で並行して実装が進められる - 自動生成ツールを用いてAPI定義から通信用コードを作れる - モックサーバーが利用できる
7. AI時代
8. AI時代 実装があれば API定義は不要？
9. AI時代 実装があれば API定義は不要？ → No - 正しいAPI定義は実装や調査の効率的な入口になる
10. AI時代 実装があれば API定義は不要？ → No - 正しいAPI定義は実装や調査の効率的な入口になる 自動生成ツールは不要？
11. AI時代 実装があれば API定義は不要？ → No - 正しいAPI定義は実装や調査の効率的な入口になる 自動生成ツールは不要？ → No - 確率論的な動作のAIより、決定論的なツールの方が出力が一定で、早く低コスト - そもそもAIと自動生成ツールを両方使うのが最強
12. © Sansan, Inc.
13. Eightにおける API定義 ほとんど、ただの参考ドキュメントだった iOS 参考 参考 Rails 参考 OpenAPI Android 自動生成 Web
14. ところが、その状況が一変
15. iOS／Androidでも自動生成にシフトすることに iOS 自動生成 参考 Rails 自動生成 OpenAPI Android 自動生成 Web
16. 開発中にモバイルアプリがクラッシュ 💥
17. API定義と実装のズレ レスポンス - 必須プロパティが返ってこない、定義上のenumにない値が返ってくる リクエスト - パラメータが必須なことが明記されていない その他 - 古いAPIが定義に起こされてない
18. 実装とのズレをどう防ぐか
19. Request Specによるスキーマ検証 - RSpecのテスト内でリクエストを送り、CommitteeでAPI定義との一致を検証 ＝ API定義と実装がズレていないことをテストで保証する
20. Controller SpecとRequest Spec Controller Spec Request Spec アクションを指定 エンドポイントを指定 ⭕ 挙動を絞って確認しやすい ⭕ 外部からのリクエストに近い ❌ ルーティングを含む検証に不向き ❌ 準備や失敗時の切り分けが大変
21. 古いController Specが120ファイル残っていた 長いものだと 1つ3000行...😇
22. Request Spec移行
23. 移行の方針 差分ノイズを先に取り除き、最後にファイル移動することで移行を最小差分に
24. つらみがいっぱい - 内部変数を見るテスト → レスポンスやDB、リダイレクト先で検証 - メソッドのスタブ → User Agentや認証ヘッダーでパターンを再現 - shared_context → metadata[:type]で内部分岐 - Viewに埋め込む JS変数 → HTMLから抽出
25. 3週間のサブタスクとして完了 ✅
26. スキーマ検証を組み込んで テストと API定義は噛み合った 🎉
27. まだエッジケースとか漏れてるかも
28. 継続的にズレを修正するための仕組み
29. 継続的にズレを改善するための仕組み - 開発環境にCommitteeのミドルウェアを導入して、実際のレスポンスを確認 - スキーマ違反だった場合はレスポンスを返しつつ、Slackにエラー通知 - 開発中のAPIはWIPタグをつけてエラーを抑制 → 定期的にエラーを確認して API定義と実装を揃えていく
30. スキーマ違反通知の Middleware - ignore_error: trueでスキーマ違反があっても元のレスポンスを返す - 違反があったらSlackにエラーメッセージを投稿
31. 移行の結果
32. API定義と実装が同期するように iOS 自動生成 同期 Rails 自動生成 OpenAPI Android ⾃動⽣成 実装に近い仕様として、 API定義だけレビューする戦略もアリかも Web
33. 組織として生まれた変化 - API定義の不正確さが浮き彫りになり、エンドポイントの洗い出しが進んだ - Slackのエラー通知を起点に、スキーマ違反の修正が継続的に行われるように - モバイルエンジニアによるAPI定義やバックエンド実装への越境
34. まとめ
35. まとめ - API定義と実装のズレは、テストと継続的な検証で発見できる - コードが高速に生成される時代にも、自動化・仕組み化は重要であり続ける - API定義は共通言語として、エンジニアの越境の手助けにもなる
36. Sansan 技術本部 採用情報 https://media.sansan-engineering.com/