TRPC教程：新手入门与实践指南

本文提供了详细的TRPC教程，涵盖了从环境搭建到创建第一个TRPC服务的全过程。此外，还介绍了TRPC客户端与服务端通信的方法以及高级功能的应用。文章还包括了实践案例分析和常见问题的解决方案，帮助读者更好地理解和使用TRPC。

TRPC是什么

TRPC（TypeScript Remote Procedure Calls）是一种基于TypeScript的远程过程调用框架，它利用现代JavaScript和TypeScript生态系统中的工具实现高效、类型安全的RPC通信。TRPC旨在简化分布式系统中的服务间通信，提供一种简单、易于扩展的方式，使后端开发人员可以专注于业务逻辑的实现。

TRPC的主要特点和优势

• 类型安全：TRPC利用TypeScript的静态类型系统来确保客户端和服务器之间的通信是类型安全的。这可以减少运行时错误，并提高代码的可维护性。
• 模块化：TRPC支持模块化的服务定义和实现方式，允许开发人员以组合的方式构建复杂的服务。
• 可扩展性：TRPC的设计允许开发人员轻松地添加新的服务端功能或扩展现有的服务端逻辑。
• 广泛的支持库：TRPC与各种现代Web框架（如Next.js、React、Vue.js等）紧密集成，允许开发人员无缝地将远程过程调用集成到现有的前端或后端项目中。
• 内置的错误处理机制：TRPC提供了强大的错误处理机制，以确保在服务端和客户端之间可以有效地处理和传递错误信息。
• 强大的配置选项：TRPC提供了灵活的配置选项来调整服务端和客户端的行为，包括但不限于日志记录、连接池大小和超时时间等。

TRPC的应用场景

TRPC适用于各种需要服务间通信的应用场景，包括但不限于：

• 微服务架构：在微服务架构中，不同的服务可以通过TRPC来实现高效、安全的通信。
• 前端与后端通信：利用TRPC，前端可以方便地调用后端服务，而无需担心类型不匹配或数据格式错误的问题。
• 跨域请求：当需要进行跨域请求时，TRPC可以提供一种类型安全的方式来处理这些请求。

安装Node.js和必要的工具

为了开始使用TRPC，首先需要确保环境已经安装了Node.js和一些必要的工具。以下是安装和配置环境的基本步骤：

1. 安装Node.js：

   • 访问Node.js官方网站（https://nodejs.org/）并下载适合你操作系统的最新版本。
   • 按照官方文档的指引完成安装。
   • 验证Node.js是否成功安装，可以通过在命令行中输入以下命令来检查Node.js的版本：

     node -v

   • 同样验证npm（Node Package Manager）的版本：

     npm -v

2. 安装TypeScript：

   • 使用npm安装TypeScript：

     npm install -g typescript

   • 验证TypeScript是否安装成功：

     tsc -v

3. 安装TRPC：
   • 使用npm安装TRPC相关的依赖：

     npm install @trpc/server @trpc/client @trpc/react-query @trpc/next

初始化TRPC项目

1. 创建项目目录：

   • 在命令行中创建新的项目目录并进入该目录：

     mkdir my-tRPC-project
     cd my-tRPC-project

2. 初始化项目：
   • 使用npm初始化一个新的Node.js项目：

     npm init -y

   • 安装必要的依赖：

     npm install express @trpc/server @trpc/client @trpc/next @trpc/react-query

配置项目环境变量

1. 创建.env文件：

   • 在项目根目录下创建一个名为.env的文件，用于存储环境变量。
   • 例如：

     PORT=3000
     DATABASE_URL=your-database-url

2. 使用环境变量：
   • 在项目中引用这些环境变量。可以使用process.env来访问这些变量：

     const port = process.env.PORT || 3000;
     const databaseUrl = process.env.DATABASE_URL;

定义服务接口

TRPC服务接口定义了服务提供的所有操作或方法。这些接口通常定义在src/router.ts文件中。以下是一个简单的示例：

import { router, procedure } from '@trpc/server';
import { z } from 'zod';

export const appRouter = router({
  hello: procedure
    .input(z.object({ text: z.string() }))
    .output(z.string())
    .query(({ input }) => {
      return `Hello ${input.text}`;
    }),
});

实现服务逻辑

服务逻辑通常在定义接口的同时实现。在上面的例子中，hello接口接收一个字符串输入，并返回一个包含输入文本的响应。为了实现服务逻辑，你可以使用各种异步函数和中间件。

例如，你可以在服务中实现数据库调用，并根据数据库返回的数据生成响应：

import { router, procedure } from '@trpc/server';
import { z } from 'zod';
import { db } from './database';

export const appRouter = router({
  getUsers: procedure
    .input(z.object({ id: z.number() }))
    .output(z.object({ id: z.number(), name: z.string() }))
    .query(async ({ input }) => {
      const user = await db.users.findUnique({ where: { id: input.id } });
      return user;
    }),
});

启动服务并进行测试

1. 创建服务启动文件：

   • 创建一个名为server.ts的文件来启动服务：

     import express from 'express';
     import { createTRPCExpressMiddleware } from '@trpc/server/adapters/express';
     import { appRouter } from './src/router';
     
     const app = express();
     
     const trpcMiddleware = createTRPCExpressMiddleware({
     router: appRouter,
     createContext: () => ({}), // 创建上下文
     });
     
     app.use(trpcMiddleware);
     app.listen(3000, () => {
     console.log('HTTP server running on http://localhost:3000');
     });

2. 运行服务：

   • 使用以下命令启动服务：

     node server.ts

3. 测试服务：
   • 使用Postman或任何其他HTTP客户端向服务发送请求。
   • 例如，向http://localhost:3000/trpc/hello发送一个GET请求，并在请求体中包含{"text": "World"}。

创建TRPC客户端

TRPC客户端用于从客户端发送请求到服务端。客户端通常定义在客户端代码中，例如React或Next.js应用。

以下是如何在React应用中创建TRPC客户端的示例：

// src/trpc.ts
import { createTRPCReact } from '@trpc/react-query';

import superjson from 'superjson';

import type { appRouter } from '../src/router';

const trpc = createTRPCReact<appRouter>({
  transformer: superjson,
});

export default trpc;

发送请求到服务端

在客户端代码中，你可以使用创建的TRPC客户端来发送请求到服务端。以下是一个简单的示例：

// src/pages/index.tsx
import { trpc } from '../trpc';
import { useQuery } from '@trpc/react-query';
import { appRouter } from '../src/router';

function Home() {
  const { data, isLoading } = useQuery(appRouter.query.hello, {
    input: { text: 'World' },
  });

  if (isLoading) return <div>Loading...</div>;

  return <div>Hello {data}</div>;
}

export default Home;

处理服务端响应

客户端代码可以根据服务端响应进行相应的处理。在上面的示例中，根据请求的结果显示相应的文本：

function Home() {
  const { data, isLoading } = useQuery(appRouter.query.hello, {
    input: { text: 'World' },
  });

  if (isLoading) return <div>Loading...</div>;

  return <div>Hello {data}</div>;
}

错误处理与异常捕获

TRPC提供了强大的错误处理机制，在服务端和客户端都可以捕获和处理错误。以下是如何在服务端进行错误处理的示例：

appRouter.query.hello.middleware(async ({ input, next }) => {
  if (input.text === 'Error') {
    throw new Error('Something went wrong');
  }
  return await next();
});

在客户端，可以使用useQuery的onError选项来处理错误：

useQuery(appRouter.query.hello, {
  input: { text: 'Error' },
  onError: (err) => console.error(err),
});

数据流控制与长连接

TRPC支持流式的响应和长连接。以下是如何在服务端实现流式响应的示例：

appRouter.query.stream.middleware(async ({ input, next }) => {
  const readable = new Readable({
    read() {
      // Noop
    },
  });

  const interval = setInterval(() => {
    readable.push(`tick\n`);
  }, 1000);

  readable.on('end', () => {
    clearInterval(interval);
  });

  return readable;
});

在客户端，可以使用useInfiniteQuery来处理流式响应：

useInfiniteQuery(appRouter.query.stream, {
  onSuccess: (data) => console.log(data),
});

服务端与客户端的优化技巧

• 缓存：使用createTRPCReact的cache选项来启用缓存。例如：

  const trpc = createTRPCReact<appRouter>({
  transformer: superjson,
  cache: 'no-store', // 或者 'default'
  });

• 代码分割：使用createTRPCReact的isServer选项来实现代码分割。例如：

  const trpc = createTRPCReact<appRouter>({
  transformer: superjson,
  isServer: false, // 在客户端代码中设置
  });

• 懒加载：使用createTRPCReact的isClient选项来实现懒加载。例如：

  const trpc = createTRPCReact<appRouter>({
  transformer: superjson,
  isClient: true, // 在客户端代码中设置
  });

TRPC在实际项目中的应用

TRPC在实际项目中的应用案例包括但不限于：

• 微服务架构：在微服务架构中，不同的服务可以通过TRPC来实现高效、安全的通信。例如，定义服务端接口：

  // 示例：定义服务端接口
  export const appRouter = router({
  getUsers: procedure
    .input(z.object({ id: z.number() }))
    .output(z.object({ id: z.number(), name: z.string() }))
    .query(async ({ input }) => {
      const user = await db.users.findUnique({ where: { id: input.id } });
      return user;
    }),
  });

• 前端与后端通信：利用TRPC，前端可以方便地调用后端服务，而无需担心类型不匹配或数据格式错误的问题。
• 跨域请求：当需要进行跨域请求时，TRPC可以提供一种类型安全的方式来处理这些请求。

常见问题及解决方案

• 类型错误：确保在服务端和客户端定义的所有类型都匹配。例如，在服务端进行类型错误处理：

  // 示例：类型错误处理
  appRouter.query.hello.middleware(async ({ input, next }) => {
  if (input.text === 'Error') {
    throw new Error('Something went wrong');
  }
  return await next();
  });

• 性能问题：优化请求的处理逻辑，减少不必要的网络传输。
• 错误处理不完善：确保在服务端和客户端都正确捕获和处理错误。

TRPC社区资源推荐

• 官方文档：https://trpc.io/docs
• GitHub仓库：https://github.com/trpc/trpc
• Discord社区：https://discord.gg/trpc

以上是TRPC教程的完整内容，涵盖从环境搭建到高级功能的介绍。希望这个指南能够帮助你更好地理解和使用TRPC。