TypeScript Academy · 课时

定义路由器与过程

Q: 「定义路由器与过程」这节课中我会学到什么？

构建带输入验证的查询和变更操作。 你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

构建带输入验证的查询和变更操作。

定义路由器与过程 是 CoddyKit 上的免费 TypeScript Academy 课时。这是第 2 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 TypeScript Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 TypeScript Academy 课程共包含 4 节课。

初始化 tRPC

每个 tRPC 后端都从使用 initTRPC 创建实例开始。它会返回用于构建 router 和过程的构建器。通常您只需创建一次，然后导出所需的部分。

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

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

第一个过程

过程就是一个单独的接口端点。最简单的过程是返回一个值的 query。publicProcedure.query 定义了一个无需输入、可读取的端点。

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

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

验证输入

过程会使用验证器声明其输入，常见做法是使用 zod 模式。.input(schema) 既会在运行时进行验证，也会为解析器和 client 推断输入类型。

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

对于会更改数据的操作，请使用 .mutation。它的结构与 query 相同，但表示写入操作，这会影响 client 缓存和 HTTP 方法。

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

构建应用 router

将一个对象传给 router(...)，即可把多个过程收集到一个 router 中。对象中的每个键都会成为一个可调用的过程名称。这个 appRouter 就是您的完整接口。

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

嵌套路由器

router 可以嵌套，从而组织大型接口。router 对象中的值本身可以是另一个 router，进而生成带命名空间的调用，例如 user.byId。

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

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

导出 router 类型

最重要的导出内容是 router 的类型。client 会导入它，以获得完整的类型安全。为服务器适配器导出值，并为 client 导出类型。

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

连接适配器

要通过 HTTP 提供 router，需要连接一个适配器。tRPC 为独立 Node、Express、Next.js、Fetch 等环境提供适配器。适配器会将传入的请求转换为过程调用。

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

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

整理文件

一种常见的布局是：在 trpc.ts 中放置 initTRPC 以及导出的 router/publicProcedure，将功能 router 放在各自的文件中，再用一个根 appRouter 将它们组合起来。将 initTRPC 放在同一个位置，可以避免创建多个实例。

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

输入推断回顾

由于 .input(schema) 既能验证又能推断，因此您只需编写一次模式，就能同时获得运行时保护和静态类型。client 将准确获知每个过程所需的输入，而这些输入都来自相应模式。

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

快速检查

测试您对 router 和过程的理解。

回顾

您已经构建了一个 tRPC 后端。

initTRPC.create() 会生成 router 和 procedure 构建器。
.input(schema) 会验证并推断输入。
.query 读取数据；.mutation 写入数据。
将过程组合到 appRouter 中，并导出 type AppRouter = typeof appRouter。

下一步：使用完全类型化的 client 调用它。

常见问题解答

「定义路由器与过程」课时是免费的吗？

是的 — 「定义路由器与过程」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 TypeScript Academy 课程的其余内容，请升级到 CoddyKit PRO。 TypeScript Academy 课程共包含 4 节课。

「定义路由器与过程」这节课中我会学到什么？

构建带输入验证的查询和变更操作。你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 TypeScript Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 TypeScript Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 2 节课，共 4 节。

「定义路由器与过程」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 TypeScript Academy 课中编写并运行代码吗？

能。每节 TypeScript Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 TypeScript Academy