tRPC Procedure: 深入解析与实践

tRPC 是一个专为 TypeScript 设计的远程过程调用（Remote Procedure Call, RPC）框架。它的主要目的是在服务器和客户端之间构建类型安全的 API，无需额外的代码生成或复杂的配置。在传统的 REST 或 GraphQL 中，开发者需要维护独立的类型定义文件，而 tRPC 利用 TypeScript 的类型推断能力，将类型从服务端自动传递到客户端，从而消除了重复劳动，提升了开发效率。

在 tRPC 中，procedure 是其核心概念之一。它表示定义和调用特定功能的基本单元。通过 procedure，开发者可以组织逻辑、处理数据传输，并保障 API 的类型安全。

什么是 tRPC 的 Procedure

tRPC 的 procedure 是一组函数或逻辑的抽象表示，它主要由以下几个部分组成：

1. 输入验证：对用户请求的输入参数进行验证，确保数据符合预期格式。
2. 业务逻辑：包含核心功能实现，如数据处理、数据库查询等。
3. 输出类型：规定返回值的格式和类型，以确保客户端能够正确解析。

通过 procedure，tRPC 将 API 的定义与实现紧密结合，使得代码在整个开发周期中保持一致性与可维护性。

Procedure 的实现结构

tRPC 的 procedure 通常包括以下几个步骤：

1. 输入定义

在定义 procedure 时，可以使用 zod（一个 TypeScript 的数据验证库）来校验输入参数。zod 提供了强大的验证功能，能够捕获用户输入中的潜在错误。

示例代码：

import { z } from 'zod';

const inputSchema = z.object({
  id: z.string(),
  age: z.number().min(18),
});

在上述例子中，输入参数被限制为具有 id（字符串类型）和 age（大于等于 18 的数字类型）的对象。通过这种方式，服务器可以确保接收到的数据符合预期。

2. 核心逻辑

核心逻辑是 procedure 的主要部分，负责处理业务需求。例如，查询数据库或处理复杂计算。

示例代码：

const procedureLogic = async (input: { id: string; age: number }) => {
  const user = await database.findUserById(input.id);
  if (!user) {
    throw new Error('User not found');
  }

  return { message: `Welcome, ${user.name}! You are ${input.age} years old.` };
};

在此代码中，函数接收验证后的输入参数，并使用这些参数查询数据库以返回特定用户的数据。

3. 输出类型

输出类型定义了返回值的结构，这部分信息会自动被客户端捕获并利用，以确保前后端类型一致。

示例代码：

import { createRouter, publicProcedure } from '@trpc/server';

const userRouter = createRouter()
  .query('getUser', publicProcedure
    .input(inputSchema)
    .resolve(procedureLogic)
  );

通过以上代码，定义了一个名为 getUser 的 procedure。它的输入参数会被验证，业务逻辑会被调用，返回的结果会自动推断类型并传递到客户端。

真实世界案例

tRPC 的 procedure 在实际项目中有许多应用场景。例如，构建一个在线书店的 API 服务。以下是具体的场景和实现步骤：

场景描述

在线书店需要一个 API 来获取用户收藏的书籍列表。客户端发送用户 ID，服务器返回与该用户关联的所有书籍信息。

tRPC Procedure 的实现

输入验证：

const getUserBooksInput = z.object({
  userId: z.string().uuid(),
});

通过 zod 确保 userId 是有效的 UUID 字符串。

核心逻辑：

const getUserBooksLogic = async (input: { userId: string }) => {
  const books = await database.findBooksByUserId(input.userId);
  if (!books.length) {
    return { books: [], message: 'No books found for this user' };
  }

  return { books, message: `Found ${books.length} books` };
};

Router 定义：

const bookRouter = createRouter()
  .query('getUserBooks', publicProcedure
    .input(getUserBooksInput)
    .resolve(getUserBooksLogic)
  );

客户端调用：

客户端可以通过如下方式调用该 procedure：

const { data } = await trpc.bookRouter.getUserBooks.query({ userId: '123e4567-e89b-12d3-a456-426614174000' });

console.log(data.books);

客户端的返回结果类型会自动推断为包含 books 和 message 的对象。

tRPC Procedure 的优势

1. 类型安全：服务端和客户端共享类型定义，避免了传统 API 开发中可能出现的类型不一致问题。
2. 高效开发：无需手动生成或维护类型文件，开发者可以专注于业务逻辑。
3. 易于扩展：通过路由器（Router）组织 procedure，可以轻松管理和扩展复杂的项目。
4. 灵活验证：利用 zod 或其他验证库，开发者可以轻松定义和校验复杂的输入规则。

深度思考

通过 tRPC 的 procedure，可以看出现代 API 开发的趋势逐渐向类型安全、易于维护的方向发展。这种方式不仅提升了开发效率，还减少了潜在错误的可能性。

真实世界中的应用案例表明，tRPC 适合需要快速迭代和严格类型要求的项目，例如 SaaS 平台、实时数据分析工具等。未来，随着 TypeScript 的普及，像 tRPC 这样的工具可能会成为行业标准。