Antigravity + tRPC で型安全なフルスタックAPI開発 — エンドツーエンドの型推論で開発効率を劇的に向上させる

// tRPC の型推論の仕組み（概念図）
// サーバー側で定義した input/output がクライアントに自動伝播
//
// Server: router.user.getById({ id: string }) => { name: string, email: string }
//    ↓ TypeScript の型推論
// Client: trpc.user.getById.useQuery({ id: "123" })
//    → 戻り値の型が { name: string, email: string } と自動推論される

// src/server/trpc.ts — tRPC の初期設定
import { initTRPC, TRPCError } from "@trpc/server";
import { ZodError } from "zod";
 
const t = initTRPC.create({
  errorFormatter({ shape, error }) {
    return {
      ...shape,
      data: {
        ...shape.data,
        zodError:
          error.cause instanceof ZodError ? error.cause.flatten() : null,
      },
    };
  },
});
 
// ベースとなるルーターとプロシージャ
export const router = t.router;
export const publicProcedure = t.procedure;

// src/server/routers/user.ts — ユーザールーターの例
import { z } from "zod";
import { router, publicProcedure } from "../trpc";
 
export const userRouter = router({
  getById: publicProcedure
    .input(z.object({ id: z.string().uuid() }))
    .query(async ({ input }) => {
      // DB からユーザーを取得（例: Prisma）
      const user = await db.user.findUnique({
        where: { id: input.id },
      });
      if (!user) {
        throw new TRPCError({
          code: "NOT_FOUND",
          message: "ユーザーが見つかりません",
        });
      }
      return user;
      // 期待する出力: { id: string, name: string, email: string, createdAt: Date }
    }),
 
  create: publicProcedure
    .input(
      z.object({
        name: z.string().min(1).max(100),
        email: z.string().email(),
      })
    )
    .mutation(async ({ input }) => {
      const newUser = await db.user.create({ data: input });
      return newUser;
      // 期待する出力: { id: string, name: string, email: string, createdAt: Date }
    }),
});

// src/shared/schemas/user.ts — 共有バリデーションスキーマ
import { z } from "zod";
 
// 基本スキーマ（サーバー・クライアント両方で使用）
export const createUserSchema = z.object({
  name: z
    .string()
    .min(1, "名前は必須です")
    .max(100, "名前は100文字以内で入力してください"),
  email: z
    .string()
    .email("有効なメールアドレスを入力してください"),
  role: z.enum(["admin", "user", "viewer"]).default("user"),
});
 
export const updateUserSchema = createUserSchema.partial().extend({
  id: z.string().uuid(),
});
 
// 型を自動エクスポート（クライアントで使用）
export type CreateUserInput = z.infer<typeof createUserSchema>;
export type UpdateUserInput = z.infer<typeof updateUserSchema>;

// src/server/routers/user.ts での使用例
import { createUserSchema, updateUserSchema } from "@/shared/schemas/user";
 
export const userRouter = router({
  create: publicProcedure
    .input(createUserSchema)  // Zod スキーマをそのまま渡す
    .mutation(async ({ input }) => {
      // input は CreateUserInput 型に自動推論
      // input.name: string, input.email: string, input.role: "admin" | "user" | "viewer"
      return await db.user.create({ data: input });
    }),
 
  update: publicProcedure
    .input(updateUserSchema)
    .mutation(async ({ input }) => {
      // input.id は必須、他フィールドはオプショナル
      const { id, ...data } = input;
      return await db.user.update({ where: { id }, data });
    }),
});

// src/lib/trpc.ts — クライアント設定
import { createTRPCReact } from "@trpc/react-query";
import type { AppRouter } from "@/server/routers/_app";
 
export const trpc = createTRPCReact<AppRouter>();

// src/components/UserList.tsx — tRPC + React Query の実装例
"use client";
 
import { trpc } from "@/lib/trpc";
 
export function UserList() {
  // useQuery: 型安全なデータフェッチ
  const { data: users, isLoading, error } = trpc.user.list.useQuery(
    { limit: 20, offset: 0 },
    {
      staleTime: 5 * 60 * 1000,  // 5分間キャッシュ
      retry: 2,
    }
  );
 
  // useMutation: 型安全なデータ更新
  const utils = trpc.useUtils();
  const createUser = trpc.user.create.useMutation({
    onSuccess: () => {
      // 成功時にユーザーリストを再取得
      utils.user.list.invalidate();
    },
    onError: (err) => {
      // Zod バリデーションエラーの表示
      if (err.data?.zodError) {
        const fieldErrors = err.data.zodError.fieldErrors;
        console.error("バリデーションエラー:", fieldErrors);
      }
    },
  });
 
  if (isLoading) return <div>読み込み中...</div>;
  if (error) return <div>エラー: {error.message}</div>;
 
  return (
    <div>
      <ul>
        {users?.map((user) => (
          // user の型が自動推論される
          <li key={user.id}>{user.name} ({user.email})</li>
        ))}
      </ul>
      <button
        onClick={() =>
          createUser.mutate({
            name: "新しいユーザー",
            email: "new@example.com",
          })
        }
      >
        ユーザーを追加
      </button>
    </div>
  );
}
// 期待する出力: ユーザー一覧が表示され、ボタンクリックで新しいユーザーが追加される

// src/server/trpc.ts — 認証ミドルウェアの追加
import { initTRPC, TRPCError } from "@trpc/server";
import type { Context } from "./context";
 
const t = initTRPC.context<Context>().create();
 
// 認証チェックミドルウェア
const isAuthed = t.middleware(({ ctx, next }) => {
  if (!ctx.session?.user) {
    throw new TRPCError({
      code: "UNAUTHORIZED",
      message: "ログインが必要です",
    });
  }
  return next({
    ctx: {
      session: ctx.session,
      user: ctx.session.user,  // 以降のプロシージャで user にアクセス可能
    },
  });
});
 
// レート制限ミドルウェア
const rateLimit = t.middleware(async ({ ctx, next, path }) => {
  const key = `ratelimit:${ctx.ip}:${path}`;
  const allowed = await checkRateLimit(key, { max: 100, window: 60 });
  if (!allowed) {
    throw new TRPCError({
      code: "TOO_MANY_REQUESTS",
      message: "リクエスト制限に達しました。しばらく待ってから再試行してください",
    });
  }
  return next();
});
 
export const router = t.router;
export const publicProcedure = t.procedure;
export const protectedProcedure = t.procedure.use(isAuthed);
export const rateLimitedProcedure = t.procedure.use(rateLimit);