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
kotlin
Server Component
prefetch(data、authenticated data)
↓
Data Cache
preserve data
↓
HydrateClient 包裹 Client Component
将服务端数据传递至客户端，避免客户端2次请求将tRPC添加到现有项目
1. Install
bun add @trpc/server @trpc/client @trpc/react-query @tanstack/react-query@latest zod client-only server-only- 版本信息
perl
"@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
javascript
...
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状态