GraphQLとは？RESTful APIとの違いと実装方法

1. GraphQLとは

GraphQLは、APIのためのクエリ言語とランタイムシステムです。従来のRESTful APIとは異なり、クライアントが必要なデータを正確に指定して取得できるため、過剰なデータ取得や複数のエンドポイント呼び出しを避けることができます。

2. RESTful APIとの比較

RESTful APIとGraphQLの主な違いを理解することで、適切なAPI設計ができるようになります。RESTful APIでは複数のエンドポイントを呼び出す必要があり、過剰なデータ取得が発生しやすいという問題があります。

RESTful APIとGraphQLを比較することで、それぞれの特徴と使い分けが理解できます。

// 複数のエンドポイントを呼び出す必要がある
GET /api/users/123
GET /api/users/123/posts
GET /api/users/123/followers

// 過剰なデータ取得（不要なフィールドも含まれる）
GET /api/users/123
// レスポンス: { id, name, email, phone, address, ... } // 全てのフィールドが返る

# 1つのクエリで必要なデータのみ取得
query {
  user(id: 123) {
    name
    posts {
      title
      createdAt
    }
    followers {
      name
    }
  }
}

3. GraphQLスキーマの定義

GraphQLスキーマは、APIの構造と型を定義する重要な要素です。スキーマを先に設計することで、型安全なAPIを構築でき、クライアントとサーバー間の契約を明確にできます。

# schema.graphql
type User {
  id: ID!
  name: String!
  email: String!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String
  author: User!
  createdAt: String!
}

type Query {
  user(id: ID!): User
  users: [User!]!
  post(id: ID!): Post
  posts: [Post!]!
}

type Mutation {
  createUser(name: String!, email: String!): User!
  updateUser(id: ID!, name: String, email: String): User!
  deleteUser(id: ID!): Boolean!
}

4. Apollo Serverの実装

Apollo Serverは、GraphQLサーバーを簡単に構築できるNode.jsフレームワークです。スキーマ定義とリゾルバーを実装するだけで、本番環境で使用できるGraphQL APIを構築できます。

Apollo Serverを使用してGraphQLサーバーを実装する方法を説明します。

// npm install apollo-server graphql
const { ApolloServer, gql } = require('apollo-server');

// スキーマ定義
const typeDefs = gql`
  type User {
    id: ID!
    name: String!
    email: String!
  }
  
  type Query {
    users: [User!]!
    user(id: ID!): User
  }
`;

// リゾルバー
const resolvers = {
  Query: {
    users: () => users,
    user: (parent, args) => users.find(u => u.id === args.id)
  }
};

// サーバーの起動
const server = new ApolloServer({ typeDefs, resolvers });

server.listen().then(({ url }) => {
  console.log(`Server ready at ${url}`);
});

5. リゾルバーの実装

リゾルバーは、GraphQLクエリやミューテーションが実行された際に呼び出される関数です。リゾルバーでデータベースからデータを取得したり、ビジネスロジックを実行したりします。

const resolvers = {
  Query: {
    users: async () => {
      // データベースから取得
      return await User.find();
    },
    user: async (parent, args) => {
      return await User.findById(args.id);
    }
  },
  
  User: {
    posts: async (parent) => {
      // ユーザーの投稿を取得
      return await Post.find({ authorId: parent.id });
    }
  },
  
  Mutation: {
    createUser: async (parent, args) => {
      const user = new User({
        name: args.name,
        email: args.email
      });
      return await user.save();
    },
    
    updateUser: async (parent, args) => {
      return await User.findByIdAndUpdate(
        args.id,
        { name: args.name, email: args.email },
        { new: true }
      );
    },
    
    deleteUser: async (parent, args) => {
      await User.findByIdAndDelete(args.id);
      return true;
    }
  }
};

6. クエリの実行

GraphQLクエリは、クライアントが必要なデータを指定して取得するための構文です。変数を使用することで、動的なクエリを実行できます。

GraphQLクエリの基本的な書き方と、変数の使用方法を説明します。

# ユーザー一覧を取得
query {
  users {
    id
    name
    email
  }
}

# 特定のユーザーを取得
query {
  user(id: "123") {
    id
    name
    email
    posts {
      id
      title
    }
  }
}

query GetUser($userId: ID!) {
  user(id: $userId) {
    id
    name
    email
  }
}

# 変数
{
  "userId": "123"
}

7. ミューテーション

ミューテーションは、データの作成・更新・削除を行うためのGraphQL操作です。RESTful APIのPOST、PUT、DELETEに相当しますが、GraphQLでは1つのエンドポイントで全ての操作を実行できます。

ミューテーションを使用して、データの作成・更新・削除を行う方法を説明します。

# ユーザー作成
mutation CreateUser($name: String!, $email: String!) {
  createUser(name: $name, email: $email) {
    id
    name
    email
  }
}

# ユーザー更新
mutation UpdateUser($id: ID!, $name: String) {
  updateUser(id: $id, name: $name) {
    id
    name
    email
  }
}

# ユーザー削除
mutation DeleteUser($id: ID!) {
  deleteUser(id: $id)
}

8. 認証と認可

GraphQL APIでは、認証と認可を適切に実装することが重要です。コンテキストを使用して認証情報を管理し、リゾルバーで認可チェックを行います。

GraphQL APIで認証と認可を実装する方法を説明します。

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => {
    // トークンからユーザー情報を取得
    const token = req.headers.authorization?.split(' ')[1];
    const user = token ? verifyToken(token) : null;
    return { user };
  }
});

// リゾルバーで認証チェック
const resolvers = {
  Query: {
    profile: (parent, args, context) => {
      if (!context.user) {
        throw new Error('Authentication required');
      }
      return context.user;
    }
  }
};

9. エラーハンドリング

GraphQL APIでは、適切なエラーハンドリングが重要です。カスタムエラーを使用することで、クライアントに分かりやすいエラーメッセージを返すことができます。

GraphQL APIでエラーハンドリングを実装する方法を説明します。

class AuthenticationError extends Error {
  constructor(message) {
    super(message);
    this.extensions = {
      code: 'UNAUTHENTICATED'
    };
  }
}

class ValidationError extends Error {
  constructor(message, field) {
    super(message);
    this.extensions = {
      code: 'BAD_USER_INPUT',
      field
    };
  }
}

// リゾルバーでの使用
const resolvers = {
  Mutation: {
    createUser: async (parent, args) => {
      if (!args.email || !args.email.includes('@')) {
        throw new ValidationError('Invalid email', 'email');
      }
      // ...
    }
  }
};

10. データローダー

データローダーは、N+1問題を解決するための仕組みです。複数のリクエストをバッチ処理することで、データベースへのアクセス回数を削減し、パフォーマンスを向上させます。

データローダーを使用して、N+1問題を解決する方法を説明します。

// npm install dataloader
const DataLoader = require('dataloader');

// バッチローダー
const userLoader = new DataLoader(async (userIds) => {
  const users = await User.find({ _id: { $in: userIds } });
  return userIds.map(id => users.find(u => u.id === id));
});

// リゾルバーで使用
const resolvers = {
  Post: {
    author: async (parent) => {
      return await userLoader.load(parent.authorId);
    }
  }
};

11. サブスクリプション

サブスクリプションは、リアルタイムでデータの更新を受け取るためのGraphQL機能です。WebSocketを使用して、サーバーからクライアントへデータをプッシュできます。

サブスクリプションを使用して、リアルタイム更新を実装する方法を説明します。

type Subscription {
  postCreated: Post!
  userUpdated(userId: ID!): User!
}

const { PubSub } = require('apollo-server');
const pubsub = new PubSub();

const resolvers = {
  Subscription: {
    postCreated: {
      subscribe: () => pubsub.asyncIterator(['POST_CREATED'])
    }
  },
  
  Mutation: {
    createPost: async (parent, args) => {
      const post = await Post.create(args);
      pubsub.publish('POST_CREATED', { postCreated: post });
      return post;
    }
  }
};

12. ベストプラクティス

GraphQL APIを本番環境で使用する際は、いくつかのベストプラクティスに従うことで、パフォーマンスと保守性を向上させることができます。

GraphQL APIのベストプラクティスを説明します。

• スキーマファースト: スキーマを先に設計することで、型安全なAPIを構築でき、クライアントとサーバー間の契約を明確にできます。
• リゾルバーの最適化: データローダーを使用してN+1問題を解決し、パフォーマンスを向上させます。
• エラーハンドリング: 適切なエラーメッセージとコードを返すことで、クライアントがエラーを適切に処理できます。
• 認証・認可: コンテキストで認証情報を管理し、リゾルバーで認可チェックを行います。
• バリデーション: 入力データの検証を行い、不正なデータを防ぎます。
• パフォーマンス: クエリの複雑さを考慮し、過剰に複雑なクエリを防ぎます。