GraphQLの命名規則ってどうしてる?GraphQL開発エキスパートの命名規則を紹介します😎

GraphQLの命名規則ってどうしてる?GraphQL開発エキスパートの命名規則を紹介します😎

こんにちは!

AppSync もしくは GraphQL に注目が集まっている昨今、使い始めてみてスキーマの命名規則について悩んだことはありませんでしょうか。

本記事では GraphQL の命名規則について解説していきます。ご参考になれば幸いです。

想定する読者

  • GraphQL を使い始めてみたが命名規則に悩んでいるヒト
  • GraphQL の命名規則が知りたいヒト

命名規則の重要性

GraphQL API のクライアントライブラリの1つである、Apollo のチームが運営している Explore GraphQL のサイトに投稿された、ベストプラクティスに関する記事では、命名規則について以下のようにまとめられています。

Naming matters. As soon as a client starts to make use of a field, it becomes much harder to change the name that they’re using. Names should be obvious and self-documenting for the benefit of newcomers to the code base, and flexible enough to accommodate future versions of your product.

Lessons From 4 Years of GraphQL

この文章を要約すると、「 GraphQL の使用を開始すると、名前を変更することが難しいため、柔軟性のある名前をつけることが重要」という内容になります。

つまり GraphQL の運用を始める前に、命名規則を十分に考えなければならないということです。

命名規則の概要

それでは命名規則についてQA方式で確認していきましょう。

キャメルケースかスネークケースか?

GraphQL の命名規則はキャメルケースが一般的です

GraphQL のドキュメントを確認するとサンプルコードでは、どんな型でもキャメルケースが利用されているからです。弊社でも GraphQL を利用する際はキャメルケースで命名しています。

語尾に型がわかるような名前をつけるか?

つける場合もあればそうでない場合もあります。

ただし型がわかるように名前をつけたほうが、何を指しているのか判別しやすいため、利用することが望ましいでしょう。例えば input 型の場合は、以下のように記述します。

input CreateUserInput {
  UserGroup: String
  UserName: String!
}

上記のように、input 型を示すため「CreateUser」の語尾に「Input」を記述しています。ちなみにフィールド名もアッパーキャメルケースで記述する場合が多いです(ルート型を除く、後述します)。

Mutationの命名規則は?

Mutationはデータの登録・削除・更新を行うため、動詞+名詞の形で命名します。Mutationのフィールド内での命名はローワーキャメルケースで宣言します。以下に例を示します。

schema {
  query: Query
  mutation: Mutation
}

type Mutation {
  createUser(
    input: CreateUserInput!
    condition: ModelAlarmConditionInput
  ): ModelUserMutationConnect @aws_auth(cognito_groups: ["Admin"])
  deleteUser(
    OrganizationId: String!
    OrganizationSubId: String!
    condition: ModelUserConditionInput
  ): ModelUserMutationConnect @aws_auth(cognito_groups: ["Admin"])
  updateUser(
    input: UpdateUserInput!
    condition: ModelAlarmConditionInput
  ): ModelUserMutationConnect @aws_auth(cognito_groups: ["Admin"])
}

Query の命名規則は?

Query も Mutation と同様に、動詞+名詞の形で命名します。フィールド内での命名も、Mutation と同様にローワーキャメルケースで行います。
以下に例を示します。

type Query {
  listUser(
    filter: ModelUserFilterInput
    limit: Int
    nextToken: String
  ): ModelUserConnection @aws_auth(cognito_groups: ["Admin"])
  getUser(OrganizationId: ID!, OrganizationSubId: String!): UserConnection
    @aws_auth(cognito_groups: ["Admin", "Staff"])
}

Subscription の命名規則は?

Subscription も Mutation と同様に、動詞+名詞の形で命名します。フィールド内での命名も、Mutation と同様にローワーキャメルケースで行います。
以下に例を示します。

type Subscription {
  commentAdded(postID: ID!): Comment
}

フィールド内の命名規則は?

上述したコードの通り、基本的にはアッパーキャメルケースで記述いたしますが、データソースに対する操作を行うルート型である Query・Mutation・Subscription については、ローワーキャメルケースで記述いたします。

関連記事

まとめ

必ずしもこうしなければならないという決まりはありませんが、公式ドキュメントなどに記載されているコードから学び、GraphQL の命名規則を決めている方が多いかと思います。

GraphQL の命名規則において重要なのは、「柔軟性のある名前」をつけることになりますので、その点を考慮してルールを決めていくことが大切です。

このブログでは、GraphQL や GraphQL のマネージドサービスである AWS AppSync の記事をどんどん公開しておりますので、ご興味のある方はほかの記事もご覧いただければと思います。

AppSync に関する開発は、お気軽にお問い合わせください。