TypeScript Academy · レッスン

ルーターとプロシージャの定義

Q: 「ルーターとプロシージャの定義」で何を学びますか？

入力バリデーション付きのクエリとミューテーションを構築します。 ブラウザで直接実行するハンズオンコードでTypeScript Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

入力バリデーション付きのクエリとミューテーションを構築します。

「ルーターとプロシージャの定義」はCoddyKit上の無料TypeScript Academyレッスンです。これはレッスン2/4です。下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。これはTypeScript Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 TypeScript Academyコースには全4レッスンが含まれています。

tRPCの初期化

すべてのtRPCバックエンドは、initTRPCでインスタンスを作成することから始まります。これにより、ルーターやプロシージャを構築するためのビルダーが返されます。通常は一度だけ作成し、必要な要素をエクスポートします。

import { initTRPC } from '@trpc/server';

const t = initTRPC.create();
export const router = t.router;
export const publicProcedure = t.procedure;

最初のプロシージャ

プロシージャは1つのAPIエンドポイントです。最も単純なものは、値を返すクエリです。publicProcedure.queryを使うと、入力を必要としない読み取り可能なエンドポイントを定義できます。

import { router, publicProcedure } from './trpc';

const appRouter = router({
  health: publicProcedure.query(() => 'ok'),
});

入力の検証

プロシージャでは、バリデーターを使って入力を宣言します。一般的にはzodスキーマを使用します。.input(schema)は実行時に入力を検証すると同時に、リゾルバーとクライアントで使う入力型を推論します。

import { z } from 'zod';

const greet = publicProcedure
  .input(z.object({ name: z.string() }))
  .query(({ input }) => 'Hello, ' + input.name);

入力の読み取り

リゾルバー内では、検証済みの入力をinputとして利用でき、スキーマに基づいて完全に型付けされています。手動でキャストする必要はありません。zodとtRPCが連携して形状を推論します。

const byId = publicProcedure
  .input(z.object({ id: z.number() }))
  .query(({ input }) => {
    // input.id is number
    return { id: input.id, name: 'Alice' };
  });

ミューテーション

データを変更する操作には.mutationを使用します。形はクエリと同じですが、書き込み操作であることを示すため、クライアントのキャッシュやHTTPメソッドに影響します。

const createUser = publicProcedure
  .input(z.object({ name: z.string() }))
  .mutation(({ input }) => {
    return { id: 1, name: input.name };
  });

App Routerの構築

router(...)にオブジェクトを渡すことで、プロシージャをルーターにまとめます。各キーが呼び出し可能なプロシージャ名になります。このappRouterがAPI全体です。

const appRouter = router({
  greet,
  byId,
  createUser,
});

ネストしたルーター

大規模なAPIを整理するために、ルーターをネストできます。ルーターオブジェクトの値自体をルーターにすると、user.byIdのような名前空間付きの呼び出しが生成されます。

const userRouter = router({ byId, createUser });

const appRouter = router({
  user: userRouter,
  greet,
});
// call paths: user.byId, user.createUser, greet

ルーター型のエクスポート

最も重要なエクスポートは、ルーターの型です。クライアントはこの型をインポートして、完全な型安全性を得ます。サーバーアダプターには値を、クライアントには型をエクスポートします。

export const appRouter = router({ user: userRouter });
export type AppRouter = typeof appRouter;

アダプターの接続

ルーターをHTTP経由で提供するには、アダプターを接続します。tRPCには、スタンドアロンNode、Express、Next.js、Fetchなどに対応したアダプターがあります。アダプターは受信したリクエストをプロシージャの呼び出しに変換します。

import { createHTTPServer } from '@trpc/server/adapters/standalone';

createHTTPServer({ router: appRouter }).listen(3000);

ファイルの構成

一般的な構成は、initTRPCとエクスポートするrouter/publicProcedureを含むtrpc.ts、機能ごとに分けたルーターファイル、それらを組み合わせるルートappRouterです。initTRPCを1か所にまとめることで、複数のインスタンスが作られるのを防げます。

// trpc.ts: initTRPC.create(), export router + publicProcedure
// routers/user.ts: userRouter
// router.ts: appRouter = router({ user: userRouter })

入力推論のまとめ

.input(schema)は検証と推論の両方を行うため、スキーマを1度記述するだけで、実行時のガードと静的な型を得られます。クライアントには、これらのスキーマから導出された、各プロシージャが必要とする入力が正確に認識されます。

const search = publicProcedure
  .input(z.object({ q: z.string(), page: z.number().optional() }))
  .query(({ input }) => ({ q: input.q, page: input.page ?? 1 }));

確認テスト

ルーターとプロシージャについての理解度を確認します。

まとめ

tRPCバックエンドを構築しました。

initTRPC.create()によって、routerとprocedureのビルダーが生成されます。
.input(schema)は入力を検証し、型を推論します。
.queryは読み取り、.mutationは書き込みを行います。
プロシージャをappRouterにまとめ、type AppRouter = typeof appRouterをエクスポートします。

次は、完全に型付けされたクライアントからAPIを利用します。

よくある質問

「ルーターとプロシージャの定義」レッスンは無料ですか？

はい。「ルーターとプロシージャの定義」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、TypeScript Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 TypeScript Academyコースには全4レッスンが含まれています。

「ルーターとプロシージャの定義」で何を学びますか？

入力バリデーション付きのクエリとミューテーションを構築します。ブラウザで直接実行するハンズオンコードでTypeScript Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。

TypeScript Academyを始めるのに経験は必要ですか？

事前経験は必要ありません。CoddyKitのTypeScript Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。これはレッスン2/4です。

「ルーターとプロシージャの定義」レッスンにはどのくらい時間がかかりますか？

ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。

このTypeScript Academyレッスンでコードを書いて実行できますか？

はい。すべてのTypeScript Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。

このコースのすべてのレッスン

← TypeScript Academyに戻る