tRPC 代码示例详细解析：逐行理解及编程思想探究

tRPC 代码示例详细解析：逐行理解及编程思想探究

引用

CSDN

1.

https://m.blog.csdn.net/i042416/article/details/144196251

在这篇文章中，我们将逐行分析并解释给定的 tRPC 示例代码。tRPC 是一个非常轻量级的远程过程调用 (RPC) 框架，专门用于 TypeScript 项目中。它非常适合构建全栈类型安全的 API。我们将通过对每一行代码的详细解释，探索它是如何工作的，如何与 zod 一起进行输入验证，并讨论其背后的设计哲学。

import { initTRPC } from '@trpc/server';
import { z } from 'zod';
 
const t = initTRPC.context<{ signGuestBook: () => Promise<void> }>().create();
 
export const router = t.router;
export const publicProcedure = t.procedure;
 
const appRouter = router({
  // Queries are the best place to fetch data
  hello: publicProcedure.query(() => {
    return {
      message: 'hello world',
    };
  }),
 
  // Mutations are the best place to do things like updating a database
  goodbye: publicProcedure.mutation(async (opts) => {
    await opts.ctx.signGuestBook();
 
    return {
      message: 'goodbye!',
    };
  }),
});

代码逐行解析

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

这两行代码分别导入 tRPC 和 zod。

• initTRPC 是 tRPC 提供的核心函数，用于初始化 tRPC 的基础设置。
• z 是 zod 提供的一个命名空间，zod 是用于模式验证的库，它提供了简单易用的数据验证和解析工具。

通过这两个导入，我们为后续开发 tRPC 路由和程序设置好了工具，并且能够通过 zod 确保输入的数据是有效的，避免潜在的数据错误问题。

const t = initTRPC.context<{ signGuestBook: () => Promise<void> }>().create();

这行代码通过 initTRPC 初始化了一个 t 对象，用于后续创建路由和定义程序。

• initTRPC.context 方法用于初始化一个上下文 (context)。这里的上下文 { signGuestBook: () => Promise<void> } 是一个对象，包含一个名为 signGuestBook 的函数。该函数的返回值是一个 Promise，也就是说它是一个异步函数。

上下文在 tRPC 中起到非常关键的作用，用来在请求之间共享信息，例如：用户信息、数据库连接等。

• create() 方法最终返回一个 tRPC 的核心对象 t。这个对象拥有 router 和 procedure 方法，这些方法用于定义路由和程序。

什么是上下文 (Context)

在 tRPC 中，context 可以被理解为所有程序共用的一部分。上下文通常会包含数据库连接实例、用户认证信息等。这样做的好处是：当每个请求触发相应操作时，所需的信息已经准备好，可以直接调用。例如，signGuestBook 可以理解为与某种服务的集成操作。

export const router = t.router;
export const publicProcedure = t.procedure;

这里导出了两个对象：router 和 publicProcedure。

• router 是通过 t.router 创建的，用于定义和组装路由的基本单位。tRPC 的路由可以理解为我们在 REST API 中定义的 endpoint，而每个 router 可以包含多个不同的 procedure。
• publicProcedure 是通过 t.procedure 创建的，用于定义可公开访问的操作。tRPC 中，procedure 是具体的操作单元，类似于传统 API 中的“方法”。它可以用来处理各种 API 请求，例如查询数据或者变更状态。

路由与操作程序的关系

在 tRPC 中，router 与 procedure 的关系可以理解为 API 与其内部方法之间的关系。比如 router 可以表示“用户模块”，而 procedure 则表示“查询用户数据”或者“更新用户信息”。这种结构化的设计能让开发者更好地管理和划分代码。

const appRouter = router({

这一行代码创建了一个 appRouter，它将包含多个具体的操作。通过 router({}) 的调用，我们在定义 tRPC 的操作方法。这些操作可以分为“查询（query）”和“变更（mutation）”两种类型。

Hello 路由定义

  hello: publicProcedure.query(() => {
    return {
      message: 'hello world',
    };
  }),

• hello 是一个定义在 appRouter 上的路由，表示我们创建了一个名为 hello 的公共程序。
• publicProcedure.query() 表示这是一个查询操作，用于从服务器获取数据。tRPC 中的 query 相当于 REST 中的 GET 请求。
• 回调函数 () => { return { message: 'hello world' }; } 是查询的处理函数。当客户端调用 hello 这个路由时，服务器会返回 { message: 'hello world' } 这样的结果。

在这个例子中，hello 路由的作用非常简单，只是返回一个固定的 JSON 对象 { message: 'hello world' }，这在很多应用中可以用作测试服务器是否正常运行或者作为健康检查 (health check) 的一个接口。

Goodbye 路由定义

  goodbye: publicProcedure.mutation(async (opts) => {
    await opts.ctx.signGuestBook();

    return {
      message: 'goodbye!',
    };
  }),

• goodbye 是一个 mutation 类型的路由。和 hello 不同，mutation 用于执行有副作用的操作，例如写入数据库、更新某些状态等。tRPC 中，mutation 相当于 REST 中的 POST 或 PUT 请求。
• async (opts) => { ... } 这个函数是 goodbye 路由的处理函数，它是异步的。这个函数接受一个参数 opts，包含了请求的上下文。
• await opts.ctx.signGuestBook(); 调用了上下文中的 signGuestBook 方法，await 表示这是一个异步操作，代码会等待 signGuestBook 执行完成后再继续执行下去。通过上下文，我们可以访问到请求级别的共享资源和服务，例如这里的 signGuestBook，可以理解为一个记录用户访问的服务。
• 在执行完 signGuestBook 之后，goodbye 处理函数返回 { message: 'goodbye!' }。这个 mutation 的最终结果是返回一个带有 message 属性的对象。

举例说明

为了更好地理解 hello 和 goodbye 路由的区别，我们可以假设有一个留言簿应用：

• 当用户访问 /hello 路由时，应用只是简单地显示“hello world”。这个操作并不会对服务器的状态产生任何影响，因此它是一个查询 (query) 操作。
• 当用户访问 /goodbye 路由时，应用会在服务器的数据库中记录用户的离开行为（例如写入访客留言簿），因此这是一个变更 (mutation) 操作。

完整的路由对象

});

到这里，整个 appRouter 对象的定义已经完成。它包含了两个路由：一个是 hello 查询，另一个是 goodbye 变更。appRouter 是 tRPC 应用的核心路由器，它将所有的公共程序组织在一起，形成一个可供客户端调用的 API 集合。

tRPC 编程思想与特点

类型安全与全栈共享类型

tRPC 的一个核心特点是类型安全。通过 TypeScript，tRPC 能够确保客户端和服务端之间的数据交互是类型安全的，这意味着我们在开发时能够得到更好的编译时错误检查，减少运行时错误。这种全栈共享类型的设计理念使得前后端开发人员可以使用相同的代码来验证输入和输出的数据结构，这极大地提升了开发效率和代码的可维护性。

在这个示例中，publicProcedure 中的数据操作都是经过 zod 模式验证的，这样可以确保输入数据符合预期类型。如果客户端发送的数据不符合要求，zod 会立即抛出错误，防止错误数据进入系统。

上下文的灵活性

上下文的使用是 tRPC 的另一个关键概念，它能够将公共的资源和服务注入到请求处理函数中。在这个示例中，上下文中包含了 signGuestBook 函数，这意味着每一个与 appRouter 交互的请求都可以使用该函数。这种设计非常适合于需要用户认证信息或者数据库连接的场景，能够让代码更加简洁，逻辑更加集中。

查询与变更的明确区分

tRPC 中通过 query 和 mutation 明确区分了不同类型的操作，这使得代码的意图非常清晰。查询 (query) 只负责获取数据，而变更 (mutation) 则负责更改状态。这种约定能够帮助开发者更好地理解和维护代码，并且能够防止一些常见的错误，例如在不应该更改状态的操作中引入副作用。

代码复用与组合

router 和 procedure 的设计使得代码非常易于复用与组合。我们可以将不同的 router 按照业务逻辑进行拆分，例如将用户相关的操作放在 userRouter，将产品相关的操作放在 productRouter，然后通过 mergeRouters 的方式将它们组合在一起。这种模块化的设计能够帮助开发者更好地组织代码，并且使得不同模块之间的依赖关系更加清晰。

异步编程与请求处理

在 goodbye 路由中，我们使用了 async/await 语法来处理异步操作。tRPC 本质上是基于 HTTP 的，而 HTTP 请求处理本身就是异步的。因此，tRPC 的 procedure 也通常是异步的，这样才能很好地与数据库请求、外部 API 调用等操作进行结合。在这个示例中，signGuestBook 被设计为异步操作是因为写入数据库、调用第三方服务这些操作通常需要一些时间，不能阻塞线程。

总结：tRPC 示例代码的设计哲学

• 模块化与清晰性 ：通过 router 和 procedure 的组合，我们可以非常方便地管理和扩展 API。这种设计使得代码更易维护，结构更清晰。
• 类型安全与验证 ：tRPC 与 TypeScript 和 zod 紧密结合，确保了数据传输的类型安全性，减少了运行时错误，增强了代码的健壮性。
• 查询与变更的分离 ：通过将 query 与 mutation 分开，tRPC 强制开发者明确数据请求与状态变更的区别，从而降低了错误的可能性。
• 上下文的共享性 ：上下文的设计使得在程序间共享数据与功能变得更加方便，例如用户信息、数据库实例等，可以直接通过 opts.ctx 访问，从而简化了代码的逻辑。

通过这段代码的分析，我们可以看到 tRPC 在简化前后端数据交互、保证类型安全、增强代码可维护性等方面的优势。在实际开发中，tRPC 可以与 React、Next.js 等前端框架非常好地结合，构建类型安全、性能优越的全栈应用。