はじめに
自社で開発しSaasサービスを展開している企業様からのご依頼になります。サービスの拡大を図って人員増を計画しているものの新規参画者のオンボーディングに多くのコストがかかっており、また十分にフォローできないため早期に離職される方がいらっしゃるとのことで開発環境の整備をさせて頂くこととなりました。
いくつか開発環境の整備として支援しましたがその中でも特に効果があったGraphQLのスキーマ定義整理ついて支援内容をご紹介します。
支援内容
こちらのプロジェクトではGraphQLを活用していたのですが、機能が増えるたびに都度スキーマ定義を拡張していたという状況でした。また明確な設計担当者が不在で機能の実装担当者が都度定義を決めていたこともあり一貫性がない状態でした。
弊社では下記の3点を主に実施しました。
- 仕様に関する情報の集約
- スキーマ定義の視覚化
- 重複している定義の集約
仕様に関する情報の集約
EXCEL、PowerPoint、Github、社内Wikiなど様々なツールに仕様が書かれており、新規参画者にはキャッチアップが難しい状態でした。情報をまずは集約しスキーマごとにどのような仕様に基づいてできているか分かるようまとめました。
スキーマ定義の視覚化
個別のスキーマの情報が集約できたところで次に行ったのがスキーマ間のつながりです。100を超えるスキーマを一度で全体把握するのは難しいためツールを活用し全体把握ができるような環境を整えました。
引用元：https://graphql-kit.com/graphql-voyager/
重複している定義の集約
全体把握できるようになったことで似たような用途にも関わらずスキーマが別々に定義されているケースがありました。それらの定義をまとめることで、そのスキーマを使った後続の処理もまとめることができるようになりました。
ご依頼者様のメリット
バックエンド、フロントエンドの共通認識の確立
ある程度の規模のWebサービスとなるとバックエンド、フロントエンドで技術者が分かれるケースが多いと思います。（さらに規模が大きくなるとインフラエンジニアやデザイナーなどさらに細分化されていきますが）その多くで境界線となるのがGraphQL（GraphQLを使っていなければRestAPIなど）となるため、非常に重要な箇所となります。
スキーマ名、データ型などである程度の共通認識は取れますが、この2つだけでは表現しきれない情報もあるのでそれらの情報をまとめたことで双方の開発者が正しく実装できる環境が整いました。
新規参画者のサポート
何年もそのシステムに携わっている開発者であれば当たり前のように知っている仕様も新規に参画した開発者には知らないのが当然です。知っている必要がある仕様をどれだけ早くキャッチアップできるかで新規参画者の貢献度が大きく違ってきます。
これまで散らばっていた仕様に関する情報を集約し素早くキャッチアップできるようにしたことで、新規参画者が早くチームに貢献できる環境が整いました。
保守性の向上
様々なスキーマで何度も登場する共通のスキーマを集約することで、データ取得後の処理やデータ更新処理も同時に集約できるようになりました。それまで開発者個人個人で都度どう実装するか悩んでいた問題をある程度まとめることで設計コストを抑えることができました。また処理を共通化することで保守性も向上し開発のコストを抑えることができました。