はじめに

GraphQLを触るものの、基礎的な部分があまり理解できていないと感じたので、1から勉強しなおしていきます。

スキーマ

GraphQLのスキーマは、APIが提供するデータの構造を定義する。

スキーマには、APIで利用できる操作方法やデータ型が含まれている。クライアントはこのスキーマを基にクエリを作成してデータを取得する。

*.graphql

# User型を定義
type User {
  id: ID!
  name: String!
  email: String!
}

# Query型を定義
type Query {
  # 全てのユーザーを取得するクエリ
  users: [User]
  
  # 特定のユーザーをIDで取得するクエリ
  user(id: ID!): User
}

型

GraphQLの型にはいくつか種類がある。

オブジェクト型

1つ以上のフィールドを組み合わせたデータ型。

type Character {
  name: String! # String型（非null）
  appearsIn: [Episode!]! # リスト型（リスト自体が非nullかつ中身が非null）
}

引数

引数をつけることもでき、Javascript等と異なり名前付き引数で渡されることから引数の順番が異なっても良い。

type Starship {
  id: ID!
  name: String!
  length(unit: LengthUnit = METER): Float
}

Query、Mutation、Subscription

Query：データの取得
Mutation：データの更新
Subscription：イベントの監視

以下のように書くことができる。

type Query {
  droid(id: ID!): Droid
}

また、Query、Mutation、Subscription以外の名前をつけたい場合は、以下のように定義することで変えることができる。

schema {
  query: MyQueryType
  mutation: MyMutationType
  subscription: MySubscriptionType
}

スカラー型

Int：符号付き 32 ビット整数
Float：符号付き倍精度浮動小数点値
String：文字列
Boolean：trueまたはfalse
ID：一意の識別子。オブジェクトの再取得やキャッシュのキーとしてよく使われる。Stringと同じ方法でシリアル化（保存や転送が可能な形式に変換）されるが、人間が読める形式ではないことを意味する

また、カスタムスカラー型を定義することができ、例えばDate型は以下のように定義すれば良い。このとき、シリアル化・デシリアル化（シリアル化の逆）の定義も一緒にする。

scalar Date

以下はJavascriptでDate型の場合はタイムスタンプにする定義である。

const { GraphQLScalarType, Kind } = require('graphql');

const DateScalar = new GraphQLScalarType({
  name: 'Date',
  description: 'Custom Date scalar type',
  serialize(value) {
    // シリアル化: Dateオブジェクトをタイムスタンプに変換
    return value.getTime();
  },
  parseValue(value) {
    // デシリアル化: タイムスタンプをDateオブジェクトに変換
    return new Date(value);
  },
  parseLiteral(ast) {
    if (ast.kind === Kind.INT) {
      // リテラルからのデシリアル化: タイムスタンプをDateオブジェクトに変換
      return new Date(parseInt(ast.value, 10));
    }
    return null;
  },
});

module.exports = {
  Date: DateScalar,
};

module.exports = {
  Date: DateScalar,
};

Enum型

enum Episode {
  NEWHOPE
  EMPIRE
  JEDI
}

型修飾子

非Null型

!を型の後ろにつけると非Nullに設定できる。

type Character {
  name: String!
}

リスト型

指定した型の配列を返すときに使う型。

type Character {
  name: String!
  appearsIn: [Episode]! # 要素がEpisode型の配列
}

上記の非Null型を組み合わせると以下のようなパターンになる。

リスト	意味
[String]	String型またはnullを要素とするリストまたはnull
[String!]	nullではないString型の要素を持つリストまたはnull
[String]!	String型またはnullを要素とするnullではないリスト
[String!]!	nullではないString型の要素を持つnullではないリスト

参考