GraphQLのFieldの変更・削除するときの運用フローについて

Introduction

本記述は GraphQLのschemaからFieldを削除、変更を行う際の運用フローについてまとめたものである。

Why?

GraphQLはクエリ言語でデータの取得をしてくる際にField名を記載し取得して来ます。
そのためサーバーサイドでのみ変更、削除を行ってしまうとフロントサイドでエラーが発生し通信が取れなくなってしまう危険性があります。

そのため安全にFieldを変更、削除するため、合意形成、周知、対応を行うための運用フローが必要となります。

Example

本記述は下記のようなQuery、schemaを使用して記述していきます。

schema.gql

type Book {
  id: ID!
  name: String!
　author: String! 
}

Query（変更前）

query book{
 book(id: "id"){
    id
    name
    author
  }
}

Query（変更後）

query book{
 book(id: "id"){
    id
    title
    author
  }
}

Flow

ほぼ参考資料の推奨のやり方ではございますが、下記のようにFieldの変更、削除を行っております。

1. 関係者に新しいQueryの周知を行う

連携するQueryは最終形で行う（対象のFieldを削除、変更した形）
今回は name を　title に変更します。

Query

query book{
 book(id: "id"){
    id
    tile #nameを削除しtitleの追記
    author
  }
}

2. 対象のfieldを一度deprecatedにして新しいfieldを追加する

下記はrenameするときの記載です。
削除の際はcolumnを追加せず対象のcolumnをdeprecatedにするのみになります。

deprecatedは`その名の通りで使用を非推奨を明記するものです。
こちらを追記することで、他の開発者へゆくゆく削除するもだと明示していきます。

schema.gql

type Book {
  id: ID!
  name: String! @deprecated(reason: "rename column for title") #deprecatedを追加
  title: String! #追加
　author: String! 
}

注意：尚、この際にクライアントサイドの方もschemaに合わせて実装を行います

3. stagingで動作のテストを行い、production環境へリリースする

staging環境があればこちらで動作テストを行い影響がないか確認を行います。
問題がなければ本番環境へリリースしマージを行います！！

4. Fieldの削除

リリースを行い動作に問題がなく、かつ変更対応が完了しましたdeprecatedをつけたFieldの削除を行います。

schema.gql

type Book {
  id: ID!
  # nameのFieldを削除する
  title: String!
　author: String! 
}

尚、私は対象のFieldを削除するまで期間を明記、チーム内のタスク管理ツールでタスクを作成しチーム内で周知。
合意形成をとっております。

schema.gql

type Book {
  id: ID!
  name: String! @deprecated(reason: "yyyy/mm/ddで削除いたします。各位対応をお願いたします。") 
  title: String!
　author: String! 
}

Conclusion

安心安全なField変更で、楽しいGQLライフを！！ｗ

Supplement （補足）：　NestJSでのdeprecatedの書き方

私の所属しているチームではNestJSでschema.gqlを自動生成しております。
久しぶりに書いたときに忘れたので備忘録として記載します。
同じく忘れてしまった方はご参考くださいｗ

book.shema.ts

  @Field(_type => ID)
  id: string;

  // 対象
  @Field(_type => String, { deprecationReason: 'rename column for title' }))
  name: string;

  @Field(_type => String)
  author: string;

References（参考文献）

• GraphQL Schema Design: Building Evolvable Schemas