1905 字

10 分钟

通过 tRPC 实现全栈 typesafe

2025-01-06

介绍#

tRPC 在 Next.js 中用于创建类型安全的API，它允许客户端直接调用服务器端的函数（API），并享受完整的 TypeScript 类型推断。

实现客户端与服务端的 api 同步，可以帮我们在客户端同步server api，并且同步调用 server api。
使用 tRPC 不用关心请求方式，tRPC 全都封装好了，使用的是 tRPC 的 api client。
tRPC 在原生http请求上有很多优化，比如原生请求三个数据，tRPC 会把他汇聚成一个http请求。

tRPC 在 Next 中使用#

1. 安装依赖#

1
npm install @trpc/server @trpc/client

2. 创建路由器#

首先，让我们初始化 tRPC router。

1
import { initTRPC } from "@trpc/server";
2

3
const t = initTRPC.create();
4
export const router = t.router;
5
export const procedure = t.procedure;

接下来，我们将初始化主路由器实例（这里用 appRouter 举例）。

1
import { initTRPC } from "@trpc/server";
2

3
const t = initTRPC.create();
4
export const router = t.router;
5
export const procedure = t.procedure;
6

7
export const appRouter = router({
8
  getUser: procedure.query(async () => {
9
    return { name: "xiaohu" };
10
  }),
11
});
12

13
export type AppRouter = typeof appRouter;

3. 通过 handler 配置 Next API 路由#

tRPC 作为一个 API 框架，需要集成到现有的服务器环境中运行，例如 Next.js API Route、Express 或 Node.js 原生 HTTP 服务器。其核心价值在于提供类型安全的远程过程调用（RPC）能力，而与此底层服务器无关。

为了适配不同的后端环境，tRPC 提供了特定的 “适配器”（Adapter），例如 @trpc/server/adapters/fetch 或 @trpc/server/adapters/express。这些适配器中的 **handler** 函数充当了关键的桥梁角色，它负责：

标准化输入/输出：将不同服务器框架（如 Next Request/Response）的特定请求/响应对象，转换为 tRPC 能够处理的统一格式。
路由调度：接收传入的 HTTP 请求，并将其分派给正确的 tRPC 过程（Procedure）进行处理。
上下文创建：为每个请求生成上下文（Context），可以在其中注入身份验证信息、数据库连接等。

下面我们通过 fetchhandler 创建 api route。

1
import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
2
import { appRouter } from "@/utils/trpc";
3
import { NextRequest } from "next/server";
4

5
export const handler = (request: NextRequest) => {
6
  return fetchRequestHandler({
7
    endpoint: "/api/trpc",
8
    req: request,
9
    router: appRouter,
10
    createContext: () => ({}),
11
  });
12
};
13

14
export { handler as GET, handler as POST };

4. 在客户端使用#

我们已经创建好了 api route，接下来要如何使用呢？

4.1 创建 tRpc 客户端。#

创建 tRPC 客户端的主要目的是为了我们你能在前端（如 React 组件中）像调用本地函数一样，安全、方便地调用后端 API。手动构造 HTTP 请求，比如 fetch('/api/user/123')。

1
import type { AppRouter } from "@/utils/trpc";
2

3
export const trpcClient = createTRPCClient<AppRouter>({
4
  links: [
5
    httpBatchLink({
6
      url: "http://localhost:3000/api/trpc",
7
    }),
8
  ],
9
});

4.2 在客户端页面中调用 api#

1
"use client";
2
import { Button } from "@/components/ui/button";
3
import { Input } from "@/components/ui/input";
4
import { Textarea } from "@/components/ui/textarea";
5
import { useEffect } from "react";
6
// 1. 引入trpc的client
7
import { trpcClient } from "@/utils/api";
8

9
export default function Home() {
10
  useEffect(() => {
11
    // 2. 调用trpc的 app api
12
    trpcClient.getUser.query();
13
  }, []);
14
  return (
15
    <div className="h-screen flex items-center justify-center">
16
      <form className="w-full max-w-md flex flex-col" action="">
17
        <h1 className="text-center text-2xl font-bold">Create App</h1>
18
        <Input name="name" placeholder="App Name" />
19
        <Textarea name="description" placeholder="Description" />
20
        <Button type="submit">Submit</Button>
21
      </form>
22
    </div>
23
  );
24
}

这时打开页面可以看到我们调用 getUser api 发送的请求，及返回数据。

tRPC api Context 及 Middleware#

tRPC handler 可以向我们的 api router 传递 Context，和 express middleware 类似。

首先创建 createContextInner 函数，用于获取上下文。

1
// 创建 createContextInner
2
export async function createContextInner() {
3
  const session = await getServerSession();
4
  if (!session) {
5
    // TRPCError 会自动处理 401 状态码
6
    throw new TRPCError({
7
      code: "UNAUTHORIZED",
8
      message: "session is null",
9
    });
10
  } else {
11
    return {
12
      session,
13
    };
14
  }
15
}

给我们的 tRPc handler route 设置 createContext。

1
import { fetchRequestHandler } from "@trpc/server/adapters/fetch";
2
import { createContextInner, appRouter } from "@/utils/trpc";
3
import { NextRequest } from "next/server";
4

5
export const handler = (request: NextRequest) => {
6
  return fetchRequestHandler({
7
    endpoint: "/api/trpc",
8
    req: request,
9
    router: appRouter,
10
    // 传入 createContextInner
11
    createContext: createContextInner,
12
  });
13
};
14

15
export { handler as GET, handler as POST };

调用此 api 时就可以在 createContextInner 进行 context 处理。下面是 middleware 使用方法。

1
// 1. 创建 middleware
2
const middleware = t.middleware(async (opts) => {
3
  const start = Date.now();
4
  const result = await opts.next();
5
  const durationMs = Date.now() - start;
6

7
  const meta = { path: opts.path, type: opts.type, durationMs };
8
  result.ok
9
    ? console.log("OK request timing:", meta)
10
    : console.error("Non-OK request timing", meta);
11
  return result;
12
});
13

14
// 2. 应用 middleware，定义新的 procedure
15
const loggedProcedure = procedure.use(middleware);
16

17
// 4. 可以定义专门用于校验用户登录的 middleware
18
const checkedLoginMiddleware = t.middleware(async ({ ctx, next }) => {
19
  if (!ctx.session?.user) {
20
    throw new TRPCError({
21
      code: "UNAUTHORIZED",
22
      message: "session is null",
23
    });
24
  }
25
  return next();
26
});
27
const checkedProcedure = procedure.use(checkedLoginMiddleware);
28

29
export const appRouter = router({
30
  // 3. 更换路由上的 procedure
31
  getUser: loggedProcedure.query(async ({ ctx }) => {
32
    console.log("%c Line:38 🍏 ctx", "color:#7f2b82", ctx);
33
    return { ...ctx };
34
  }),
35
  // 5. 校验登录后才能访问的路由
36
  hello: checkedProcedure.query(async ({ ctx }) => {
37
    return { hello: "Hello world" };
38
  }),
39
});

访问页面触发调用 api ，可以看到控制台输出 context log及 middleware 内的log。

tRPC 在 React 客户端集成#

在 React 项目中，可以使用 TanStack Query 进行客户端集成。

TanStack Query 的核心作用是，它专门负责高效地管理、缓存和同步你的应用中的【异步数据】（尤其是来自服务器端的数据）。

设置 tRpc context#

1
import { createTRPCClient, httpBatchLink } from "@trpc/client";
2
import type { AppRouter } from "@/utils/trpc";
3
import { createTRPCContext } from "@trpc/tanstack-react-query";
4

5
export const trpcClient = createTRPCClient<AppRouter>({
6
  links: [
7
    httpBatchLink({
8
      url: "http://localhost:3000/api/trpc",
9
    }),
10
  ],
11
});
12

13
// 定义 TRPC 上下文
14
const trpcContext = createTRPCContext<AppRouter>();
15
export const TRPCProviderReact = trpcContext.TRPCProvider;
16
export const { useTRPC, useTRPCClient } = trpcContext;

然后，创建一个 TRPCProvider客户端组件，并将页面包裹在TRPCProvider中。

1
"use client";
2
import { ReactNode } from "react";
3
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
4
import { TRPCProviderReact, trpcClient } from "@/utils/api";
5

6
export function TRPCProvider({ children }: { children: ReactNode }) {
7
  const queryClient = new QueryClient();
8
  return (
9
    <QueryClientProvider client={queryClient}>
10
      <TRPCProviderReact trpcClient={trpcClient} queryClient={queryClient}>
11
        {children}
12
      </TRPCProviderReact>
13
    </QueryClientProvider>
14
  );
15
}

在 app/layout.tsx 中, 用 TRPCProvider 组件包裹子组件。

1
import type { Metadata } from "next";
2
import { Geist, Geist_Mono } from "next/font/google";
3
import "./globals.css";
4
import { TRPCProvider } from "./TRPCProvider";
5

6
// ... 其他代码
7
export default function RootLayout({
8
  children,
9
}: Readonly<{
10
  children: React.ReactNode;
11
}>) {
12
  return (
13
    <html lang="en">
14
      <body
15
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
16
      >
17
        <TRPCProvider>{children}</TRPCProvider>
18
      </body>
19
    </html>
20
  );
21
}

在 client 调用 api#

使用 tanstack 的 useQuery hook 发起一个 tRPC 查询请求，useQuery 返回的对象中，包含该请求的 data/isLoading/error 等状态。

1
"use client";
2
import { Button } from "@/components/ui/button";
3
import { useTRPC } from "@/utils/api";
4
import { useQuery } from "@tanstack/react-query";
5

6
export default function Home() {
7
  // 获取已配置好的 tRPC 客户端实例和工具函数
8
  // 这个 useTRPC 必须在使用了 TRPCProvider 包裹的 客户端 组件内使用
9
  const trpc = useTRPC();
10
  // 使用 tanstack 的 useQuery hook 发起一个 tRPC 查询请求
11
  // trpc.hello.queryOptions() 生成一个包含查询键(key)和查询函数(queryFn)的选项对象
12
  // useQuery 返回的对象中，包含该请求的 data/isLoading/error 等状态
13
  const { data, isLoading, error } = useQuery(trpc.hello.queryOptions());
14
  return (
15
    <div className="h-screen flex items-center justify-center">
16
      <Button type="submit">{isLoading ? "Loading" : data?.hello}</Button>
17
    </div>
18
  );
19
}

服务器端调用#

当我们从 server component 在请求 api 时，由于 server component 和 api 在同一服务器上，这时我们期望无需重新建立 http 连接，可以直接调用服务端函数。

createCallerFactory() 可以帮我们实现此功能，它是 tRPC 服务器端的一个高级工具函数，它的主要目的是在你的服务器端代码中，创建一个能够直接调用你定义的 tRPC 过程（procedures）的“调用器”（caller），而无需发起一个 HTTP 请求。

创建一个 tRPC createCallerFactory() ，它基于已定义的应用路由器(appRouter)，这个createCallerFactory 可以用来创建能够直接调用路由器中所有过程的调用器实例。

1
const t = initTRPC.create();
2
const { router, procedure, createCallerFactory } = t;
3

4
// ... appRouter
5
export const createCaller = createCallerFactory(appRouter);

在服务端，通过 createCaller 实例 caller 对服务端api进行调用。

1
import { Button } from "@/components/ui/button";
2
import { createContextInner, createCaller } from "@/utils/trpc";
3

4
export default async function Home() {
5
  const ctx = await createContextInner();
6
  const caller = createCaller(ctx);
7
  const data = await caller.hello();
8

9
  return (
10
    <div className="h-screen flex items-center justify-center">
11
      <Button type="submit">{data.hello}</Button>
12
    </div>
13
  );
14
}