Node.jsにおけるGraphQLとtRPCの比較 - APIパラダイムの選択

堅牢でスケーラブルなAPIを構築することは、現代のWeb開発の礎です。Node.jsの広大なエコシステムにおいて、開発者はバックエンドとフロントエンドアプリケーション間のインターフェースを作成するための数多くの選択肢に直面しています。大きな注目を集めている2つの強力な候補が、Apollo Serverを実装したGraphQLとtRPCです。どちらもAPI開発に独自のアプローチを提供し、データ取得、型安全性、開発者エクスペリエンスなどの一般的な課題に対処しますが、それらは根本的に異なる哲学を通じて実現されます。それぞれのニュアンスを理解することは、プロジェクト固有のニーズと将来の成長に適合するインテリジェントな決定を下すために不可欠です。この記事では、これらの2つのパラダイムを掘り下げ、そのメカニズムを探求し、コード例で実践的な適用例を示し、最終的にNode.jsバックエンドに最も適したオプションを選択するように導きます。

コアコンセプト

比較に入る前に、議論の根底にあるコアコンセプトを簡単に定義しましょう。

GraphQL: APIのためのクエリ言語であり、既存のデータでそれらのクエリを履行するためのランタイムです。RESTよりも効率的で強力で柔軟な代替手段を提供します。クライアントは必要なデータのみを正確にリクエストできるため、過剰取得や過少取得が排除されます。

Apollo Server: GraphQLスキーマをデータソースに接続するのに役立つ、人気のあるオープンソースGraphQLサーバーです。スキーマ結合、キャッシング、さまざまなNode.jsフレームワークとの統合など、幅広い機能を提供します。

tRPC: "TypeScript Remote Procedure Call"の略です。スキーマやコード生成なしで、エンドツーエンドの型安全なAPIを自信を持って構築できるフレームワークです。TypeScriptの強力な推論能力を活用して、サーバーサイドの定義からクライアントサイドの呼び出しまで、型安全性を直接実現します。

Apollo Serverを備えたGraphQL

GraphQLは、本質的に、クライアントがクエリできるすべての可能なデータを記述するスキーマを定義することです。このスキーマは、クライアントとサーバー間の契約として機能します。

原則と実装

GraphQLのコア原則は、クライアントがまさに必要なデータを指定できるようにすることです。これは、クライアントが対話し、クエリを送信する単一のエンドポイントを通じて達成されます。

Apollo ServerでGraphQL APIをセットアップする基本的な例を次に示します。

まず、GraphQLスキーマを定義します。このスキーマは、GraphQLスキーマ定義言語（SDL）を使用して、型、クエリ、ミューテーションを指定します。

// src/schema.ts
import { gql } from 'apollo-server';

export const typeDefs = gql`
  type Book {
    id: ID!
    title: String!
    author: String!
  }

  type Query {
    books: [Book!]!
    book(id: ID!): Book
  }

  type Mutation {
    addBook(title: String!, author: String!): Book!
  }
`;

次に、スキーマの各フィールドのデータを取得する関数であるリゾルバーを実装します。

// src/resolvers.ts
const books = [
  { id: '1', title: 'The Great Gatsby', author: 'F. Scott Fitzgerald' },
  { id: '2', title: 'To Kill a Mockingbird', author: 'Harper Lee' },
];

export const resolvers = {
  Query: {
    books: () => books,
    book: (parent: any, { id }: { id: string }) => books.find(book => book.id === id),
  },
  Mutation: {
    addBook: (parent: any, { title, author }: { title: string, author: string }) => {
      const newBook = { id: String(books.length + 1), title, author };
      books.push(newBook);
      return newBook;
    },
  },
};

最後に、Apollo Serverをセットアップして起動します。

// src/index.ts
import { ApolloServer } from 'apollo-server';
import { typeDefs } from './schema';
import { resolvers } from './resolvers';

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

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

クライアントは次に、次のようなクエリを送信できます。

query GetBooks {
  books {
    id
    title
  }
}

またはミューテーション：

mutation AddNewBook {
  addBook(title: "1984", author: "George Orwell") {
    id
    title
    author
  }
}

GraphQLのアプリケーションシナリオ

GraphQLは、以下のような状況で優れています。

• 複雑なデータ構造: データモデルが複雑で、多くの相互接続されたリソースがあります。
• 複数のクライアント: さまざまなデータ要件を持つさまざまなクライアント（Web、モバイル、IoT）をサポートする必要があり、複数のRESTエンドポイントのバージョン管理を避けたい場合。
• 過剰/過少取得の防止: クライアントが受信するデータを正確に制御し、不要なデータ転送を最小限に抑えたい場合。
• 急速なイテレーション: 新しいフィールドを型に追加しても古いクエリに影響を与えないため、既存のクライアントを壊すことなくAPIを迅速に進化させる必要がある場合。

tRPC

tRPCは、根本的に異なるアプローチを取ります。個別のスキーマを定義する代わりに、TypeScriptを活用してバックエンドコードからAPIコントラクトを直接推論します。これは、API型がサーバーサイド関数から自動的に派生することを意味します。

原則と実装

tRPCのコア原則は、中間スキーマレイヤーやコード生成なしのエンドツーエンドの型安全性です。これは、サーバーでAPIルートをTypeScript関数として定義し、クライアントサイドライブラリを使用してそれらの関数を型安全な方法で呼び取ることで実現されます。

tRPC APIをセットアップする基本的な例を次に示します。

まず、サーバーでtRPCルーターとプロシージャを定義します。

// src/server.ts
import { initTRPC } from '@trpc/server';
import { z } from 'zod'; // 入力検証用

const t = initTRPC.create(); // tRPCの初期化

const books = [
  { id: '1', title: 'The Great Gatsby', author: 'F. Scott Fitzgerald' },
  { id: '2', title: 'To Kill a Mockingbird', author: 'Harper Lee' },
];

export const appRouter = t.router({
  book: t.router({
    list: t.procedure.query(() => {
      return books;
    }),
    byId: t.procedure
      .input(z.object({ id: z.string() }))
      .query(({ input }) => {
        return books.find(book => book.id === input.id);
      }),
    add: t.procedure
      .input(z.object({ title: z.string(), author: z.string() }))
      .mutation(({ input }) => {
        const newBook = { id: String(books.length + 1), ...input };
        books.push(newBook);
        return newBook;
      }),
  }),
});

export type AppRouter = typeof appRouter; // ルーターの型をエクスポート

次に、tRPCルーターを公開するためのHTTPアダプターをセットアップします。Node.jsの場合、@trpc/server/adapters/fastifyまたは@trpc/server/adapters/standaloneを使用できます。

// src/index.ts (簡潔にするために@trpc/server/adapters/standaloneを使用)
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { appRouter } from './server';

const server = createHTTPServer({
  router: appRouter,
  // オプション: createContextはすべてのプロシージャで`ctx`が利用可能であることを保証します
  createContext() {
    return {};
  },
});

server.listen(3000, () => {
  console.log('🚀 tRPC server listening on http://localhost:3000');
});

クライアント側では、tRPCクライアントを作成し、完全な型安全性でプロシージャを呼び出すことができます。

// src/client.ts (例: Reactコンポーネント内)
import { createTRPCProxyClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from './server'; // サーバーサイドの型をインポート

const trpcClient = createTRPCProxyClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'http://localhost:3000/trpc', // tRPCエンドポイント
    }),
  ],
});

async function fetchBooks() {
  const allBooks = await trpcClient.book.list.query();
  console.log('All books:', allBooks);

  const book = await trpcClient.book.byId.query({ id: '1' });
  console.log('Book by ID:', book);

  const newBook = await trpcClient.book.add.mutate({ title: 'Dune', author: 'Frank Herbert' });
  console.log('Added book:', newBook);
}

fetchBooks();

trpcClient.book.list.query()やtrpcClient.book.byId.query()が自動的に型安全であり、byIdのinput引数が厳密に強制されていることに注意してください。

tRPCのアプリケーションシナリオ

tRPCは、以下のようなコンテキストで輝きます。

• フルスタックTypeScript: フロントエンドとバックエンドの両方でTypeScriptを使用してフルスタックアプリケーションを構築している場合。
• 開発者エクスペリエンスが最優先: 途切れることのない型安全性とオートコンプリートによる比類のない開発者エクスペリエンスを優先する場合。
• ボイラープレートの削減: API定義とクライアントサイドの消費のためのボイラープレートコードを最小限に抑えたい場合。
• 内部モノレポ: フロントエンドとバックエンドが簡単に型を共有できるモノレポ設定で特に効果的です。
• RESTライクなシンプルさ、型安全な利点: よりシンプルで直接的なRPCスタイルの対話を好むが、堅牢な型チェックが必要な場合。

結論

Apollo Serverを備えたGraphQLとtRPCはどちらもNode.js APIを構築するための説得力のあるソリューションを提供しますが、それぞれ異なる哲学とユースケースに対応しています。GraphQLは、強力で柔軟なクエリ言語とスキーマ駆動のコントラクトを提供し、複雑なマルチクライアント環境での正確なデータ取得に優れています。一方、tRPCはTypeScriptを活用して比類のないエンドツーエンドの型安全性と開発者エクスペリエンスを提供し、特にモノレポ内でのフルスタックTypeScriptアプリケーションの優れた選択肢となります。シンプルさと開発速度が鍵となります。最終的な選択は、プロジェクト固有の要件、各テクノロジーに対するチームの習熟度、および柔軟性、型安全性、開発速度の望ましいバランスに依存します。どちらのツールもそれぞれの強みで非常に効果的であり、開発者が堅牢で保守性の高いAPIを構築できるようにします。