GraphQL Schemaの破壊的変更をCIで検知する
ここ数年、私はGraphQL APIサーバーの開発を行っています。GraphQLは柔軟かつ強力なAPIクエリ言語で、Webフロントエンドからモバイルアプリなどいくつかのクライアントがそれぞれ画面に必要なデータをフェッチしており、フロントエンドの開発パフォーマンスが向上しました。
破壊的変更の問題
私のチームではGraphQLサーバーはRailsとGraphQL Rubyを用いてCode First[1]で開発しています。
しかし、複雑性が増すにつれてクライアントやクエリの全体像を把握できずに破壊的変更を引き起こすこともあり、その変更が既存のクライアントに影響を与えないように注意深くSchemaを管理する必要があります。
実際に最近、fieldやmutationの引数の変更がクライアントに不具合をもたらす事態に発生しました。
破壊的変更の検知
そもそもGraphQLは仕様が網羅されているSchemaがあります。そのSchemaを変更前と変更後で比較することで、破壊的変更を検知できるはずです。
調べてみたところ、GraphQL Inspectorというツールを見つけました。CLIやGitHub ActionsなどのCIで動かすことができるようです。
npm packageのCLIを使うと手元の開発環境でも手軽に使えるので、まずはこれを試してみるのがおすすめです。例えば、mainブランチのSchemaと開発中のブランチのSchemaを比較するコマンドを実行すると以下のように破壊的変更を検知してくれます。
Docs: https://the-guild.dev/graphql/inspector/docs/commands/diff
$ graphql-inspector diff 'git:origin/main:./schema.graphql' 'schema.graphql'
Detected the following changes (3) between schemas:
✖ Argument imageUrl: Url! added to field Mutation.createPost
✖ Field Post.Author changed type from User to String
✖ Field User.Posts changed type from [Post] to Post
error Detected 3 breaking changes
ちなみに、GraphQL InspectorのCLIは変更差分の検証だけでなく、Schemaからダミーデータを返すサーバーを実行したり、似ているTypeを見つける機能などもあります。
GitHub Actionsで動かす
私のチームではコードの管理にGitHubを、CI/CDにGitHub Actionsを使っているので、この環境で説明します。
導入は基本的に以下の手順でWorkflowファイルを追加して、好みに応じてオプションを変更するだけです。
Docs: https://the-guild.dev/graphql/inspector/docs/products/action
ちなみに、コードにコメントをするので、Actionsの実行権限を Read and write permissions にする必要があります。
今回は全てデフォルトのオプションで良さそうだったので以下のようになりました。
name: CI
on: [push]
jobs:
test:
name: Check Schema
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@master
- uses: kamilkisiela/graphql-inspector@master
with:
schema: 'master:schema.graphql'
そして、次のような破壊的変更を含んだ差分でPRを立ててみます。
その後、graphql-inspectorが破壊的変更箇所にコメントをしてくれて、CIのチェックが失敗になります。
このタイミングで意図せぬ破壊的変更に気がつくことができれば、リリース前に修正をすることができますね！
また、GraphQLを利用するクライアントの利用箇所がなく大丈夫であることが分かれば、 expected-breaking-change のようなラベルをつけることで、そのままPRをマージすることも可能です。
以上の通り、簡単に導入ができて人間のコードレビューよりも機械的に行えるので、より安全かつ効率的にGraphQLサーバーの開発が実現できるかと思います！
Discussion