Tube - tRPC setup

tRPC的基本概念

• 一个用于构建全栈类型安全API的框架（端到端类型安全），让前端可以像调用本地函数一样调用后端api
• 可替代传统的api路由，前后端共用一份类型定义
• tRPC中有一个prefetch的概念，是提前获取（预取）数据的机制
• tRPC 和 React Query 的 prefetchQuery 是一个概念，本质上就是封装了 React Query
• prefetch的数据存储在React Query缓存中（Query Cache）
• 前端使用数据时，React Query会先差看缓存中是否有对应的数据，如果有则返回，没有就再去请求
• React Query 缓存是内存级别的，页面刷新后就会清除，非持久化缓存
• trpc/server 端负责后端api路由的创建、管理等，trpc/client 端负责在前端的部分像调用函数一样调用后端api

Server Component        
  prefetch(data、authenticated data)
↓
Data Cache
  preserve data
↓
HydrateClient 包裹 Client Component
  将服务端数据传递至客户端，避免客户端2次请求

将tRPC添加到现有项目

• 请点击，查看如何将tRPC添加进当前项目

1. Install

• bun add @trpc/server @trpc/client @trpc/react-query @tanstack/react-query@latest zod client-only server-only
• 版本信息

"@tanstack/react-query": "^5.84.2",
"@trpc/client": "^11.4.4",
"@trpc/react-query": "^11.4.4",
"@trpc/server": "^11.4.4",
"zod": "^4.0.16",
"client-only": "^0.0.1",
"server-only": "^0.0.1",

2. Create a tRPC router

• src/trpc/init.ts，使用 initTRPC()初始化 tRPC 后端
• src/trpc/routers/_app.ts， 用于放置tRPC总路由（将所有小路由集合起来并导出）
• src/app/api/trpc/[trpc]/route.ts，把HTTP请求（GET/POST）转交给 tRPC 的后端路由解析器，可以理解为 tRPC 的网关/适配器

3. Create a Query Client factory src/trpc/query-client.ts

• tRPC 的前端调用是基于@tanstack/react-query的（它负责缓存、请求状态管理、重试等）
• QueryClient 就是 React Query 的 "全局数据管理器"
• 在next.js中，需要支持 数据的 "脱水(dehydrate)" 和 "水化(hydrate)"
  • 脱水(dehydrate)：序列化服务器端请求到的数据 → 注入到HTML里发给浏览器
  • 水化(hydrate)：浏览器接收数据后反序列化 → 恢复到 QueryClient 的缓存中

4. Create a tRPC client for Client Components src/trpc/client.tsx

• 这一步记得在 src/app/layout.tsx 挂载 TRPCProvider

...
import { TRPCProvider } from "@/trpc/clent";
...
export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <ClerkProvider afterSignOutUrl='/'>
      <html lang="en">
        <body className={ inter.className }>
          <TRPCProvider>
            {children}
          </TRPCProvider>
        </body>
      </html>
    </ClerkProvider>
  );
}

5. Create a tRPC caller for Server Components src/trpc/server.tsx

• import 'server-only' 表示这个文件只能在服务端被调用

6. Using your API

• 使用 <ErrorBoundary> 处理错误状态，当前安装版本"react-error-boundary": "^6.0.0"
• 使用 <Suspense> 处理loading状态