GraphQL完全ガイド2025：RESTを超えて — スキーマ設計からFederation、パフォーマンス最適化まで

# 1回のリクエストで必要なデータだけを正確に取得
query GetUserWithPosts {
  user(id: "123") {
    name
    email
    posts(first: 5) {
      title
      commentCount
    }
  }
}

# スカラー型: String, Int, Float, Boolean, ID
# ! はNon-nullを意味します

type User {
  id: ID!
  name: String!
  email: String!
  age: Int
  posts: [Post!]!
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
  tags: [String!]
  publishedAt: DateTime
}

type Comment {
  id: ID!
  body: String!
  author: User!
  post: Post!
  createdAt: DateTime!
}

type Query {
  # データ取得
  user(id: ID!): User
  users(filter: UserFilter, pagination: PaginationInput): UserConnection!
  post(id: ID!): Post
  searchPosts(query: String!): [Post!]!
}

type Mutation {
  # データ変更
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
  createPost(input: CreatePostInput!): Post!
  likePost(postId: ID!): Post!
}

type Subscription {
  # リアルタイム更新
  postCreated: Post!
  commentAdded(postId: ID!): Comment!
  userStatusChanged(userId: ID!): User!
}

input CreateUserInput {
  name: String!
  email: String!
  age: Int
  role: UserRole = USER
}

input UserFilter {
  role: UserRole
  nameContains: String
  createdAfter: DateTime
}

input PaginationInput {
  first: Int = 20
  after: String
}

enum UserRole {
  ADMIN
  EDITOR
  USER
  GUEST
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

// Resolverの4つの引数: parent, args, context, info
const resolvers = {
  Query: {
    user: async (parent, args, context, info) => {
      const { id } = args;
      const { dataSources, currentUser } = context;
      return dataSources.userAPI.getUser(id);
    },

    users: async (_, { filter, pagination }, { dataSources }) => {
      return dataSources.userAPI.getUsers(filter, pagination);
    },

    searchPosts: async (_, { query }, { dataSources }) => {
      return dataSources.postAPI.search(query);
    },
  },

  Mutation: {
    createUser: async (_, { input }, { dataSources, currentUser }) => {
      if (!currentUser?.isAdmin) {
        throw new ForbiddenError('Admin access required');
      }
      return dataSources.userAPI.createUser(input);
    },

    likePost: async (_, { postId }, { dataSources, currentUser }) => {
      if (!currentUser) {
        throw new AuthenticationError('Login required');
      }
      return dataSources.postAPI.likePost(postId, currentUser.id);
    },
  },

  // 型Resolver - リレーションフィールドの解決
  User: {
    posts: async (user, _, { dataSources }) => {
      return dataSources.postAPI.getPostsByAuthor(user.id);
    },
  },

  Post: {
    author: async (post, _, { dataSources }) => {
      return dataSources.userAPI.getUser(post.authorId);
    },
    comments: async (post, _, { dataSources }) => {
      return dataSources.commentAPI.getByPost(post.id);
    },
  },
};

import { ApolloServer } from '@apollo/server';
import { expressMiddleware } from '@apollo/server/express4';

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

await server.start();

app.use(
  '/graphql',
  expressMiddleware(server, {
    context: async ({ req }) => {
      const token = req.headers.authorization || '';
      const currentUser = await getUserFromToken(token);
      return {
        currentUser,
        dataSources: {
          userAPI: new UserDataSource(),
          postAPI: new PostDataSource(),
          commentAPI: new CommentDataSource(),
        },
      };
    },
  })
);

Query: posts(first: 10)        → 1回のクエリ（投稿10件）
  Post.author (post 1)         → 2回目のクエリ
  Post.author (post 2)         → 3回目のクエリ
  ...
  Post.author (post 10)        → 11回目のクエリ

import DataLoader from 'dataloader';

// バッチ関数: ID配列を受け取り、同じ順序で結果を返す
const userLoader = new DataLoader(async (userIds: string[]) => {
  const users = await db.users.findMany({
    where: { id: { in: userIds } },
  });

  // リクエストされたID順に結果をマッピング
  const userMap = new Map(users.map((u) => [u.id, u]));
  return userIds.map((id) => userMap.get(id) || null);
});

// Resolverで使用
const resolvers = {
  Post: {
    author: (post, _, { loaders }) => {
      return loaders.userLoader.load(post.authorId);
    },
  },
};

Query: posts(first: 10)                     → 1回のクエリ
  DataLoader batch: users([1,2,3,...,10])    → 2回のクエリ（バッチ）

// リクエストごとに新しいDataLoaderインスタンスを生成
function createLoaders() {
  return {
    userLoader: new DataLoader((ids) => batchGetUsers(ids)),
    postLoader: new DataLoader((ids) => batchGetPosts(ids)),
    commentLoader: new DataLoader((ids) => batchGetComments(ids)),
    // 1:Nリレーション用loader
    postsByAuthorLoader: new DataLoader(async (authorIds) => {
      const posts = await db.posts.findMany({
        where: { authorId: { in: authorIds } },
      });
      const grouped = groupBy(posts, 'authorId');
      return authorIds.map((id) => grouped[id] || []);
    }),
  };
}

// contextでリクエストごとに新規生成
context: async ({ req }) => ({
  currentUser: await getUser(req),
  loaders: createLoaders(),
}),

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { makeExecutableSchema } from '@graphql-tools/schema';

const schema = makeExecutableSchema({
  typeDefs,
  resolvers,
});

const server = new ApolloServer({
  schema,
  plugins: [
    // 本番環境でイントロスペクション無効化
    ApolloServerPluginLandingPageDisabled(),
    // 使用量レポーティング
    ApolloServerPluginUsageReporting(),
  ],
  formatError: (formattedError, error) => {
    // エラーフォーマット - 内部情報を隠す
    if (formattedError.extensions?.code === 'INTERNAL_SERVER_ERROR') {
      return { message: 'Internal server error' };
    }
    return formattedError;
  },
});

const { url } = await startStandaloneServer(server, {
  listen: { port: 4000 },
  context: async ({ req }) => ({
    currentUser: await authenticateUser(req),
    loaders: createLoaders(),
  }),
});

console.log(`Server ready at ${url}`);

import {
  ApolloClient,
  InMemoryCache,
  ApolloProvider,
  useQuery,
  useMutation,
  gql,
} from '@apollo/client';

const client = new ApolloClient({
  uri: 'https://api.example.com/graphql',
  cache: new InMemoryCache({
    typePolicies: {
      Query: {
        fields: {
          posts: {
            // Relayスタイルカーソルページネーションマージ
            keyArgs: ['filter'],
            merge(existing, incoming, { args }) {
              if (!args?.after) return incoming;
              return {
                ...incoming,
                edges: [...(existing?.edges || []), ...incoming.edges],
              };
            },
          },
        },
      },
    },
  }),
  defaultOptions: {
    watchQuery: {
      fetchPolicy: 'cache-and-network',
    },
  },
});

// Reactコンポーネントでの使用
const GET_POSTS = gql`
  query GetPosts($first: Int!, $after: String) {
    posts(first: $first, after: $after) {
      edges {
        node {
          id
          title
          author {
            name
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
`;

function PostList() {
  const { data, loading, error, fetchMore } = useQuery(GET_POSTS, {
    variables: { first: 10 },
  });

  if (loading) return <p>Loading...</p>;
  if (error) return <p>Error occurred</p>;

  return (
    <div>
      {data.posts.edges.map(({ node }) => (
        <PostCard key={node.id} post={node} />
      ))}
      {data.posts.pageInfo.hasNextPage && (
        <button
          onClick={() =>
            fetchMore({
              variables: { after: data.posts.pageInfo.endCursor },
            })
          }
        >
          Load More
        </button>
      )}
    </div>
  );
}

# --- Users Subgraph ---
type User @key(fields: "id") {
  id: ID!
  name: String!
  email: String!
  role: UserRole!
}

type Query {
  user(id: ID!): User
  me: User
}

# --- Posts Subgraph ---
type Post @key(fields: "id") {
  id: ID!
  title: String!
  content: String!
  author: User!
  publishedAt: DateTime
}

# 他のsubgraphのUser型を拡張
type User @key(fields: "id") {
  id: ID!
  posts: [Post!]!        # Postsサービスが追加するフィールド
  postCount: Int!
}

type Query {
  post(id: ID!): Post
  feed(first: Int = 20, after: String): PostConnection!
}

# --- Reviews Subgraph ---
type Review @key(fields: "id") {
  id: ID!
  rating: Int!
  comment: String
  author: User!
  post: Post!
}

type Post @key(fields: "id") {
  id: ID!
  reviews: [Review!]!     # Reviewsサービスが追加
  averageRating: Float
}

# router.yaml
supergraph:
  listen: 0.0.0.0:4000

subgraphs:
  users:
    routing_url: http://users-service:4001/graphql
  posts:
    routing_url: http://posts-service:4002/graphql
  reviews:
    routing_url: http://reviews-service:4003/graphql

headers:
  all:
    request:
      - propagate:
          named: authorization

// Posts Subgraph
const resolvers = {
  User: {
    // FederationがUserをresolveする際に呼び出される
    __resolveReference: async (user, { loaders }) => {
      // user.idのみが渡される
      return loaders.postsByUserLoader.load(user.id);
    },
    posts: async (user, _, { dataSources }) => {
      return dataSources.postAPI.getByAuthor(user.id);
    },
    postCount: async (user, _, { dataSources }) => {
      return dataSources.postAPI.countByAuthor(user.id);
    },
  },
};

import { createServer } from 'http';
import { WebSocketServer } from 'ws';
import { useServer } from 'graphql-ws/lib/use/ws';
import { PubSub } from 'graphql-subscriptions';

const pubsub = new PubSub();

const httpServer = createServer(app);
const wsServer = new WebSocketServer({
  server: httpServer,
  path: '/graphql',
});

useServer(
  {
    schema,
    context: async (ctx) => {
      const token = ctx.connectionParams?.authorization;
      const user = await authenticateUser(token);
      return { currentUser: user, pubsub };
    },
  },
  wsServer
);

// Resolver
const resolvers = {
  Subscription: {
    commentAdded: {
      subscribe: (_, { postId }) => {
        return pubsub.asyncIterator(`COMMENT_ADDED_${postId}`);
      },
    },
    postCreated: {
      subscribe: () => pubsub.asyncIterator('POST_CREATED'),
    },
  },

  Mutation: {
    createComment: async (_, { input }, { pubsub, currentUser }) => {
      const comment = await db.comments.create({
        data: { ...input, authorId: currentUser.id },
      });

      // 購読者に通知
      pubsub.publish(`COMMENT_ADDED_${input.postId}`, {
        commentAdded: comment,
      });

      return comment;
    },
  },
};

import { useSubscription, gql } from '@apollo/client';

const COMMENT_SUBSCRIPTION = gql`
  subscription OnCommentAdded($postId: ID!) {
    commentAdded(postId: $postId) {
      id
      body
      author {
        name
      }
      createdAt
    }
  }
`;

function CommentFeed({ postId }) {
  const { data, loading } = useSubscription(COMMENT_SUBSCRIPTION, {
    variables: { postId },
  });

  // 新しいコメントが来るたびにdataが自動更新される
  if (data?.commentAdded) {
    return <NewComment comment={data.commentAdded} />;
  }

  return null;
}

# カスタムdirective定義
directive @auth(requires: Role = USER) on FIELD_DEFINITION | OBJECT

enum Role {
  ADMIN
  EDITOR
  USER
  GUEST
}

type Query {
  publicPosts: [Post!]!
  me: User! @auth
  adminDashboard: Dashboard! @auth(requires: ADMIN)
  userManagement: [User!]! @auth(requires: ADMIN)
}

type Mutation {
  createPost(input: CreatePostInput!): Post! @auth
  deletePost(id: ID!): Boolean! @auth(requires: ADMIN)
  updateProfile(input: UpdateProfileInput!): User! @auth
}

import { mapSchema, getDirective, MapperKind } from '@graphql-tools/utils';
import { defaultFieldResolver } from 'graphql';

function authDirectiveTransformer(schema) {
  return mapSchema(schema, {
    [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
      const authDirective = getDirective(schema, fieldConfig, 'auth')?.[0];

      if (authDirective) {
        const requiredRole = authDirective.requires || 'USER';
        const originalResolve = fieldConfig.resolve || defaultFieldResolver;

        fieldConfig.resolve = async (source, args, context, info) => {
          const { currentUser } = context;

          if (!currentUser) {
            throw new AuthenticationError('Not authenticated');
          }

          if (!hasRole(currentUser, requiredRole)) {
            throw new ForbiddenError('Insufficient permissions');
          }

          return originalResolve(source, args, context, info);
        };
      }

      return fieldConfig;
    },
  });
}

import { createComplexityLimitRule } from 'graphql-validation-complexity';

const server = new ApolloServer({
  schema,
  validationRules: [
    createComplexityLimitRule(1000, {
      scalarCost: 1,
      objectCost: 2,
      listFactor: 10,
      formatErrorMessage: (cost) =>
        `Query too complex: cost ${cost} exceeds maximum 1000`,
    }),
  ],
});

import depthLimit from 'graphql-depth-limit';

const server = new ApolloServer({
  schema,
  validationRules: [depthLimit(7)],
});

// サーバー
import { ApolloServerPluginCacheControl } from '@apollo/server/plugin/cacheControl';

const server = new ApolloServer({
  schema,
  plugins: [ApolloServerPluginCacheControl({ defaultMaxAge: 60 })],
  persistedQueries: {
    cache: new KeyValueCache(), // Redisなど
  },
});

// クライアント
import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';
import { sha256 } from 'crypto-hash';

const link = createPersistedQueryLink({ sha256 });

const client = new ApolloClient({
  link: link.concat(httpLink),
  cache: new InMemoryCache(),
});

type Query {
  posts: [Post!]! @cacheControl(maxAge: 300)
  user(id: ID!): User @cacheControl(maxAge: 60)
  me: User @cacheControl(maxAge: 0, scope: PRIVATE)
}

type Post @cacheControl(maxAge: 600) {
  id: ID!
  title: String!
  author: User! @cacheControl(inheritMaxAge: true)
  viewCount: Int! @cacheControl(maxAge: 30)
}

import { KeyvAdapter } from '@apollo/utils.keyvadapter';
import Keyv from 'keyv';
import KeyvRedis from '@keyv/redis';

const server = new ApolloServer({
  schema,
  cache: new KeyvAdapter(new Keyv({ store: new KeyvRedis('redis://localhost:6379') })),
});

// DataSourceレベルのキャッシュ
class CachedUserAPI {
  private cache: RedisClient;
  private ttl = 300; // 5分

  async getUser(id: string): Promise<User> {
    const cacheKey = `user:${id}`;
    const cached = await this.cache.get(cacheKey);
    if (cached) return JSON.parse(cached);

    const user = await db.users.findUnique({ where: { id } });
    await this.cache.set(cacheKey, JSON.stringify(user), 'EX', this.ttl);
    return user;
  }
}

const cache = new InMemoryCache({
  typePolicies: {
    User: {
      keyFields: ['id'],
      fields: {
        fullName: {
          read(_, { readField }) {
            const first = readField('firstName');
            const last = readField('lastName');
            return `${first} ${last}`;
          },
        },
      },
    },
    Post: {
      keyFields: ['id'],
    },
    Query: {
      fields: {
        post(_, { args, toReference }) {
          return toReference({ __typename: 'Post', id: args?.id });
        },
      },
    },
  },
});

import { describe, it, expect, vi } from 'vitest';

describe('User Resolvers', () => {
  it('should return user by id', async () => {
    const mockUser = { id: '1', name: 'Test User', email: 'test@example.com' };
    const context = {
      dataSources: {
        userAPI: { getUser: vi.fn().mockResolvedValue(mockUser) },
      },
    };

    const result = await resolvers.Query.user(null, { id: '1' }, context, null);
    expect(result).toEqual(mockUser);
    expect(context.dataSources.userAPI.getUser).toHaveBeenCalledWith('1');
  });

  it('should throw if not admin for createUser', async () => {
    const context = {
      currentUser: { role: 'USER' },
      dataSources: { userAPI: { createUser: vi.fn() } },
    };

    await expect(
      resolvers.Mutation.createUser(null, { input: {} }, context, null)
    ).rejects.toThrow('Admin access required');
  });
});

import { ApolloServer } from '@apollo/server';

describe('GraphQL Integration', () => {
  let server: ApolloServer;

  beforeAll(async () => {
    server = new ApolloServer({ typeDefs, resolvers });
  });

  it('should execute GetUser query', async () => {
    const response = await server.executeOperation({
      query: `
        query GetUser($id: ID!) {
          user(id: $id) {
            id
            name
            email
          }
        }
      `,
      variables: { id: '1' },
    });

    expect(response.body.kind).toBe('single');
    expect(response.body.singleResult.errors).toBeUndefined();
    expect(response.body.singleResult.data?.user).toBeDefined();
  });
});