GraphQLのスキーマ定義整理でオンボーディングコスト削減

はじめに

自社で開発しSaasサービスを展開している企業様からのご依頼になります。サービスの拡大を図って人員増を計画しているものの新規参画者のオンボーディングに多くのコストがかかっており、また十分にフォローできないため早期に離職される方がいらっしゃるとのことで開発環境の整備をさせて頂くこととなりました。

いくつか開発環境の整備として支援しましたがその中でも特に効果があったGraphQLのスキーマ定義整理ついて支援内容をご紹介します。

支援内容

こちらのプロジェクトではGraphQLを活用していたのですが、機能が増えるたびに都度スキーマ定義を拡張していたという状況でした。また明確な設計担当者が不在で機能の実装担当者が都度定義を決めていたこともあり一貫性がない状態でした。

弊社では下記の3点を主に実施しました。

仕様に関する情報の集約

• スキーマ定義の視覚化
• 重複している定義の集約

EXCEL、PowerPoint、Github、社内Wikiなど様々なツールに仕様が書かれており、新規参画者にはキャッチアップが難しい状態でした。情報をまずは集約しスキーマごとにどのような仕様に基づいてできているか分かるようまとめました。

スキーマ定義の視覚化

個別のスキーマの情報が集約できたところで次に行ったのがスキーマ間のつながりです。100を超えるスキーマを一度で全体把握するのは難しいためツールを活用し全体把握ができるような環境を整えました。

具体的には、同じ User に関するスキーマが複数の場所で定義されていたが、共通部分を BaseUser として抽象化し、拡張可能な設計に変更しました。

参考：https://graphql-kit.com/graphql-voyager/

重複している定義の集約

全体把握できるようになったことで似たような用途にも関わらずスキーマが別々に定義されているケースがありました。それらの定義をまとめることで、そのスキーマを使った後続の処理もまとめることができるようになりました。

ご依頼者様のメリット

バックエンド、フロントエンドの共通認識の確立

GraphQLスキーマの整理により、バックエンド・フロントエンド間でAPIの認識齟齬がなくなり、実装ミスが減少

新規参画者のサポート

何年もそのシステムに携わっている開発者であれば当たり前のように知っている仕様も新規に参画した開発者には知らないのが当然です。知っている必要がある仕様をどれだけ早くキャッチアップできるかで新規参画者の貢献度が大きく違ってきます。

これまで散らばっていた仕様に関する情報を集約し素早くキャッチアップできるようにしたことで、新規参画者が早くチームに貢献できる環境が整いました。

結果的にオンボーディングに必要な学習時間が20%程度短縮されました。

保守性の向上

様々なスキーマで何度も登場する共通のスキーマを集約することで、データ取得後の処理やデータ更新処理も同時に集約できるようになりました。それまで開発者個人個人で都度どう実装するか悩んでいた問題をある程度まとめることで設計コストを抑えることができました。また処理を共通化することで保守性も向上し開発のコストを抑えることができました。

補足

GraphQL Voyager の活用方法について

実際に GraphQL Voyager を使用すると、以下のような画面が表示されます。

このツールを活用することで、例えば以下のような関係性を一目で確認できるようになります。

• エンティティ間の関係性
  • Customer → Order → OrderLineItem という階層構造を視覚化し、どのデータがどのように関連しているのかを把握。
  • 例えば、Customer が Order を持ち、Order が OrderLineItem を持つ、といったつながりを簡単に確認。

• フィールドの詳細表示

  • 各エンティティをクリックすると、持っているフィールドやデータ型の詳細を確認可能。
  • 例えば、Order は id: ID!、orderNumber: Int!、lineItems: [OrderLineItem!]! というフィールドを持っていることが分かる。

• 不要なスキーマの特定

  • 似たような役割を持つスキーマが別々に定義されているケースを発見し、統合の判断が容易に。