技能名称: tRPC
详细描述:

tRPC

使用tRPC的专业协助 - 使用TypeScript构建端到端类型安全的API。

概述

tRPC 无需模式或代码生成即可构建完全类型安全的 API：

• - 从服务器到客户端的完整 TypeScript 类型推断
• 无需代码生成
• 具有自动补全和类型安全的出色开发者体验
• 与 Next.js、React Query 等完美配合

快速开始

安装

bash

核心包

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

对等依赖

npm install @tanstack/react-query@latest zod

基本设置 (Next.js App Router)

1. 创建 tRPC 路由器
typescript
// server/trpc.ts
import { initTRPC } from @trpc/server
import { z } from zod

const t = initTRPC.create()

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

2. 定义 API 路由器
typescript
// server/routers/_app.ts
import { router, publicProcedure } from ../trpc
import { z } from zod

export const appRouter = router({
hello: publicProcedure
.input(z.object({ name: z.string() }))
.query(({ input }) => {
return { greeting: 你好 ${input.name}! }
}),

createUser: publicProcedure
.input(z.object({
name: z.string(),
email: z.string().email(),
}))
.mutation(async ({ input }) => {
const user = await db.user.create({ data: input })
return user
}),
})

export type AppRouter = typeof appRouter

3. 创建 API 路由
typescript
// app/api/trpc/[trpc]/route.ts
import { fetchRequestHandler } from @trpc/server/adapters/fetch
import { appRouter } from @/server/routers/_app

const handler = (req: Request) =>
fetchRequestHandler({
endpoint: /api/trpc,
req,
router: appRouter,
createContext: () => ({}),
})

export { handler as GET, handler as POST }

4. 设置客户端 Provider
typescript
// app/providers.tsx
use client

import { QueryClient, QueryClientProvider } from @tanstack/react-query
import { httpBatchLink } from @trpc/client
import { useState } from react
import { trpc } from @/lib/trpc

export function Providers({ children }: { children: React.ReactNode }) {
const [queryClient] = useState(() => new QueryClient())
const [trpcClient] = useState(() =>
trpc.createClient({
links: [
httpBatchLink({
url: http://localhost:3000/api/trpc,
}),
],
})
)

return (


{children}


)
}

5. 创建 tRPC 客户端
typescript
// lib/trpc.ts
import { createTRPCReact } from @trpc/react-query
import type { AppRouter } from @/server/routers/_app

export const trpc = createTRPCReact()

6. 在组件中使用
typescript
use client

import { trpc } from @/lib/trpc

export default function Home() {
const hello = trpc.hello.useQuery({ name: 世界 })
const createUser = trpc.createUser.useMutation()

return (

)
}

路由器定义

基本路由器

typescript import { router, publicProcedure } from ./trpc import { z } from zod

export const userRouter = router({
// Query - 用于获取数据
getById: publicProcedure
.input(z.string())
.query(async ({ input }) => {
return await db.user.findUnique({ where: { id: input } })
}),

// Mutation - 用于创建/更新/删除
create: publicProcedure
.input(z.object({
name: z.string(),
email: z.string().email(),
}))
.mutation(async ({ input }) => {
return await db.user.create({ data: input })
}),

// Subscription - 用于实时更新
onUpdate: publicProcedure
.subscription(() => {
return observable((emit) => {
// 实现
})
}),
})

嵌套路由器

typescript import { router } from ./trpc import { userRouter } from ./routers/user import { postRouter } from ./routers/post import { commentRouter } from ./routers/comment

export const appRouter = router({
user: userRouter,
post: postRouter,
comment: commentRouter,
})

// 客户端使用：
// trpc.user.getById.useQuery(123)
// trpc.post.list.useQuery()
// trpc.comment.create.useMutation()

合并路由器

typescript import { router, publicProcedure } from ./trpc

const userRouter = router({
list: publicProcedure.query(() => {/ ... /}),
getById: publicProcedure.input(z.string()).query(() => {/ ... /}),
})

const postRouter = router({
list: publicProcedure.query(() => {/ ... /}),
create: publicProcedure.input(z.object({})).mutation(() => {/ ... /}),
})

// 合并到应用路由器
export const appRouter = router({
user: userRouter,
post: postRouter,
})

使用 Zod 进行输入验证

基本验证

typescript import { z } from zod

export const userRouter = router({
create: publicProcedure
.input(z.object({
name: z.string().min(2).max(50),
email: z.string().email(),
age: z.number().int().positive().optional(),
role: z.enum([user, admin]),
}))
.mutation(async ({ input }) => {
// input 是完全类型化的！
return await db.user.create({ data: input })
}),
})

复杂验证

typescript const createPostInput = z.object({ title: z.string().min(5).max(100), content: z.string().min(10), published: z.boolean().default(false), tags: z.array(z.string()).min(1).max(5), metadata: z.object({ views: z.number().default(0), likes: z.number().default(0), }).optional(), })

export const postRouter = router({
create: publicProcedure
.input(createPostInput)
.mutation(async ({ input }) => {
return await db.post.create({ data: input })
}),
})

可复用模式

typescript // schemas/user.ts export const userSchema = z.object({ id: z.string(), name: z.string(), email: z.string().email(), })

export const createUserSchema = userSchema.omit({ id: true })
export const updateUserSchema = userSchema.partial()

// 在路由器中使用
export const userRouter = router({
create: publicProcedure
.input(createUserSchema)
.mutation(({ input }) => {/ ... /}),

update: publicProcedure
.input(z.object({
id: z.string(),
data: updateUserSchema,
}))
.mutation(({ input }) => {/ ... /}),
})

上下文

创建上下文

typescript // server/context.ts import { inferAsyncReturnType } from @trpc/server import { FetchCreateContextFnOptions } from @trpc/server/adapters/fetch

export async function createContext(opts: FetchCreateContextFnOptions) {
// 从 cookie/header 获取会话
const session = await getSession(opts.req)

return {
session,
db,
}
}

export type Context = inferAsyncReturnType

在 tRPC 中使用上下文

typescript // server/trpc.ts import { initTRPC } from @trpc/server import { Context } from ./context

const t = initTRPC.context().create()

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

在过程中访问上下文

typescript export const userRouter = router({ me: publicProcedure.query((