はじめに
Gakken LEAPのmizunoです。
現在、ベンダーから引き継いだRailsのプロジェクトの保守・機能開発を担当していますが、プロジェクトの構造が複雑で、特定の要件によっては実装の難易度が著しく変わる状況にあります。
以下に、その主な課題と、それに対する解決策を詳細に説明します。
課題
1. RESTful設計の欠如
本プロジェクトのAPI設計では、RESTful設計が十分に徹底されていません。
具体的には、index、show、create、update、destroyといった標準的なアクション以外にも多数のカスタムアクションが、1つのコントローラ内に集中して記述されています。このような構造の問題点は以下の通りです。
- 保守性の低下: カスタムアクションが増えるほど、ロジックの依存関係が複雑化し、既存機能に手を加える際のリスクが高まる。
- コードの見通しの悪化: 開発者がコントローラを読解する際に全体像を掴むのに時間がかかる。
- テストの煩雑化: 膨らんだコントローラ内の各アクションに対する適切なテストケースを用意するのが困難。
解決策への布石
APIの構造を見直し、各リソースごとに専用のコントローラを作成するなどのリファクタリングを進めます。ただし、既存システムの互換性を保つ必要があるため、後述の解決策を併用します。
2. コールバックの過剰な利用
現在のシステムでは、before_actionによる権限チェックやフィルタリングが多用されています。
例えば、管理者、業者、ユーザーなどの権限ごとに異なる処理が必要な場合でも、それらを1つのコントローラで対応しているため、以下の問題が発生しています。
- 視認性の低下: コールバックが多すぎて、どのアクションでどの処理が実行されるか追跡しづらい。
-
重複処理の発生: 複数の
before_actionで同様の認証ロジックが繰り返され、システム全体のパフォーマンスが悪化。 - デバッグの難しさ: コールバックの流れが明確でないため、問題の特定に時間がかかる。
解決策への布石
コールバックの使用を最小限に抑え、共通化できるものはベースのコントローラに記述し継承することで、権限管理のロジックを各コントローラから切り離します。
これにより、各コントローラの責務が明確化され、処理の重複を避けることが可能です。
3. 複雑なJSONレスポンス生成
ユーザーの役割（例: 管理者、業者、エンドユーザー）によって異なる情報をAPIで返す必要があるため、現在はActiveModelSerializersを利用しています。しかし、この手法にもいくつかの課題があります。
- 複雑な条件分岐: JSON生成時に多くの条件分岐が必要となり、可読性が低下。
-
統一性の欠如: 一部のAPIエンドポイントでは
ActiveModelSerializersを使用せず、独自ロジックでJSONを生成しており、メンテナンスが煩雑。 - 設計書の不足: APIのレスポンス形式が明確に文書化されておらず、新たな開発者が仕様を把握するのに時間がかかる。
解決策への布石
ActiveModelSerializersの利用箇所を段階的に見直し、統一されたフォーマットを策定することで、複雑な条件分岐を回避します。また、API仕様を明確にするために、OpenAPI（後述）を活用した設計書を作成します。さらに、新規API設計時にはベストプラクティスを取り入れ、APIが一貫性のあるレスポンスを返すように設計を行います。
解決策
APIをV2として新たに作成する
既存APIを全面的にリファクタリングする方法も検討しましたが、このアプローチでは以下の課題が予想されました。
- フロントエンドとの同期が必要: 既存のフロントエンドアプリケーションがAPIに依存しているため、同時に修正・リリースを行う必要がある。
- 運用中の影響: 一度に大規模な変更を加えると、予期せぬ不具合が発生する可能性が高い。
そこで、既存APIをそのまま運用しながら、上記の課題を解決したV2のAPIを新たに設計する方針を採用しました。
実施プロセス
- 事前合意: 設計段階でフロントエンドチームと綿密に連携し、V2のAPI仕様に合意。
- 先行リリース: V2のAPIを単独でリリースし、後からフロントエンドの接続先を切り替え可能にする。
- 柔軟な移行: フロントエンド側は既存のV1 APIを使用し続けながら、新しいAPIに段階的に移行可能。
OpenAPIでのAPI設計書作成
V2のAPI開発では、設計書をOpenAPIで管理する方針としました。この方法の利点は以下の通りです。
- 明確な仕様定義: APIのエンドポイントやレスポンス形式が一目で分かる。
- 自動生成の活用: テストコードやモックサーバーを自動生成できるため、効率的な開発が可能。
- 引き継ぎの容易化: ドキュメントが標準化されるため、新たな開発者が迅速にプロジェクトを理解できる。
Apidogの採用
OpenAPI設計書の作成にはApidogを利用しました。このツールは以下の点で非常に効果的でした。
- GUI操作: エンジニアリングスキルに依存せず、直感的にAPI設計が可能。
- スキーマ管理: 複雑なスキーマの定義や複製が容易。
- リアルタイム参照: APIの変更が即座に反映され、チーム間での情報共有が迅速化。
まとめと展望
プロジェクト引き継ぎにおける課題は、システムの複雑性が原因で保守性と拡張性に影響を及ぼしていました。しかし、以下の取り組みにより、これらの課題を解決できる見込みです。
- RESTful設計の徹底とコントローラの責務分離
- コールバックの簡素化とロジックの外部化
- 統一されたAPIレスポンス設計とドキュメントの整備
今後は、V2 APIのリリース後にパフォーマンスや保守性の向上を測定し、さらに継続的な改善を進めていきます。
エンジニア募集
Gakken LEAP では教育をアップデートしていきたいエンジニアを絶賛大募集しています！！
ぜひお気軽にカジュアル面談へお越しください！！