# Trpc Api 规则技巧 **模块化路由器结构：** * 按域/功能拆分路由器 * 使用`router()`定义路由器 * 使用 `mergeRouters()` 组合路由器 * 使用 `basePath()` 为路由添加前缀 // 服务器/路由器/user.ts 从 'zod' 导入 { z }；从 '../trpc' 导入 { router, publicProcedure, protectedProcedure }; 导出 const userRouter = 路由器({ getById: publicProcedure.input(z.object({ id: z.string() })).query(async ({ input, ctx }) => { 返回等待 ctx.db.user.findUnique({ 其中：{ id: input.id }, }); }), 创建：受保护的过程 .输入（ z. 对象({ 名称：z.string().min(1).max(100), 电子邮件：z.string().email(), }) ） .mutation(async ({ 输入, ctx }) => { 返回等待 ctx.db.user.create({ 数据：输入， }); }), }); // 服务器/路由器/post.ts 导出 const postRouter = 路由器({ 列表：公共程序 .输入（ z. 对象({ 限制：z.number().min(1).max(100).default(10), 光标：z.string().可选()， }) ） .query(async ({ 输入, ctx }) => { const posts = 等待 ctx.db.post.findMany({ 取：input.limit + 1，光标：输入.光标？ { id: input.cursor } : 未定义， }); 让 nextCursor: 字符串 |未定义； if (posts.length > input.limit) { const nextItem = posts.pop(); nextCursor = nextItem!.id; } 返回 { posts, nextCursor }; }), }); // 服务器/路由器/index.ts 从'../trpc'导入{路由器}；从 './user' 导入 { userRouter }；从 './post' 导入 { postRouter }；导出 const appRouter = 路由器({ 用户：用户路由器，帖子：帖子路由器， }); 导出类型 AppRouter = typeof appRouter; ### 类型安全程序 **程序类型：** * `query` \- 读取操作（类似 GET） * `mutation` \- 写入操作（类似 POST/PUT/DELETE） * `订阅` \- 实时更新（基于WebSocket） **使用 Zod 进行输入验证：** 从 'zod' 导入 { z }； // 定义可重用的模式 const CreateUserSchema = z.object({ 名称：z.string().min(1).max(100), 电子邮件：z.string().email(), 年龄：z.number().min(0).max(150).Optional(), }); const userRouter = 路由器({ 创建： protectedProcedure.input(CreateUserSchema).mutation(async ({ input, ctx }) => { // 输入完全键入为 { name: string, email: string,age?: number } 返回等待 ctx.db.user.create({ 数据: 输入 }); }), }); **输出验证（可选但推荐）：** const UserOutputSchema = z.object({ id: z.string(), 名称： z.string(), 电子邮件：z.string(), 创建时间：z.date(), }); const userRouter = 路由器({ getById：公共过程 .input(z.object({ id: z.string() })) .output(用户输出架构) .query(async ({ 输入, ctx }) => { const user = wait ctx.db.user.findUnique({ 其中: { id: input.id } }); 返回用户； // 根据 UserOutputSchema 进行验证 }), }); ### 错误处理 **一致错误的 TRPCError：** 从'@trpc/server'导入{TRPCError}； const userRouter = 路由器({ getById: publicProcedure.input(z.object({ id: z.string() })).query(async ({ input, ctx }) => { const 用户 = 等待 ctx.db.user.findUnique({ 其中：{ id: input.id }, }); 如果（！用户）{ 抛出新的 TRPCError({ 代码：'NOT_FOUND'， message: `未找到 id ${input.id} 的用户`, }); } 返回用户； }), }); **错误代码：** * `BAD_REQUEST` \- 无效输入 (400) * `UNAUTHORIZED` \- 未经过身份验证 (401) * `FORBIDDEN` \- 经过身份验证但没有权限 (403) * `NOT_FOUND` \- 未找到资源 (404) * `TIMEOUT` \- 请求超时 (408) * `CONFLICT` \- 资源冲突 (409) * `PRECONDITION_FAILED` \- 不满足先决条件 (412) * `PAYLOAD_TOO_LARGE` \- 请求太大 (413) * `TOO_MANY_REQUESTS` \- 速率限制 (429) * `CLIENT_CLOSED_REQUEST` \- 客户端关闭请求 (499) * `INTERNAL_SERVER_ERROR` \- 服务器错误 (500) **全局错误处理：** 从 '@trpc/server' 导入 { initTRPC, TRPCError }; 导出 const t = initTRPC.context().create({ errorFormatter({ 形状, 错误 }) { 返回{ ...形状，数据：{ ...形状.数据， zodError：错误。导致 ZodError 实例？ error.cause.flatten() : null, }, }; }, }); ### 中间件模式 **身份验证中间件：** const isAuthenticated = t.middleware(async ({ ctx, next }) => { if (!ctx.session || !ctx.session.user) { 抛出新的 TRPCError({ 代码: '未经授权' }); } 返回下一个（{ ctx：{ ...ctx, 会话：{ ...ctx.session，用户：ctx.session.user }， }, }); }); // 使用 auth 中间件保护过程导出 const protectedProcedure = t.procedure.use(isAuthenticated); **日志记录中间件：** constloggingMiddleware=t.middleware(async({path,type,next})=>{ const start = Date.now(); 常量结果=等待下一个（）； const periodMs = Date.now() - 开始； console.log(`[${type}] ${path} 花费了 ${durationMs}ms`); 返回结果； }); 导出常量 LoggedProcedure = t.procedure.use(loggingMiddleware); **权限中间件：** const hasProjectAccess = t.middleware(async ({ ctx, 输入, 下一个 }) => { // 假设输入有projectId字段 const projectId = (输入任意).projectId; if (!projectId) { 抛出新的 TRPCError({ 代码：'BAD_REQUEST'， message: '需要项目ID', }); } const hasAccess = 等待 ctx.db.projectMember.findFirst({ 其中：{ 项目ID, 用户Id：ctx.session.user.id， }, }); 如果（！hasAccess）{ 抛出新的 TRPCError({ 代码：“禁止”， message: '无法访问此项目', }); } 返回下一个（）； }); 导出 const projectProcedure = protectedProcedure.use(hasProjectAccess); ### React 查询集成 **客户端设置（反应）：** // utils/trpc.ts 从'@trpc/react-query'导入{createTRPCReact}；从 '../server/routers' 导入类型 { AppRouter }；导出 const trpc = createTRPCReact(); **提供商设置：** // _app.tsx 从 '@tanstack/react-query' 导入 { QueryClient, QueryClientProvider }; 从'@trpc/client'导入{httpBatchLink}；从 '../utils/trpc' 导入 { trpc } ； const queryClient = 新的 QueryClient({ 默认选项：{ 查询：{ staleTime: 5 * 60 * 1000, // 5 分钟重试：（失败计数，错误）=> { if (error.data?.httpStatus >= 400 && error.data?.httpStatus < 500) { 返回假； // 不要重试 4xx 错误 } 返回失败计数<3； }, }, }, }); const trpcClient = trpc.createClient({ 链接：[ httpBatchLink({ url: '/api/trpc', 标题（）{ 返回{ 授权： getAuthToken(), }; }, }), ], }); 函数 MyApp({ Component, pageProps }) { 返回（ <组件{...pageProps} /> ）； } **在组件中使用 tRPC：** // 组件/UserProfile.tsx 函数 UserProfile({ userId }: { userId: string }) { // 查询 const { data: user, isLoading, error } = trpc.user.getById.useQuery({ id: userId }); // 变异 const utils = trpc.useUtils(); const updateUser = trpc.user.update.useMutation({ 成功：() => { // 无效并重新获取 utils.user.getById.invalidate({ id: userId }); }, onError: (错误) => { toast.error(错误.消息); }, }); const handleUpdate = (数据: UpdateUserInput) => { updateUser.mutate({ id: userId, ...data }); }; if (isLoading) return

正在加载...

; if (error) return

错误: {error.message}

; 返回（

{用户名}

{用户.电子邮件}

）； } **乐观更新：** const utils = trpc.useUtils(); const createPost = trpc.post.create.useMutation({ onMutate: 异步 newPost => { // 取消传出重新获取等待 utils.post.list.cancel(); // 快照之前的值 const previousPosts = utils.post.list.getData(); // 乐观更新 utils.post.list.setData（未定义，旧=>（{ 帖子：[newPost，...（旧？.posts ?? []）]， nextCursor：旧的？.nextCursor， })); 返回 { 以前的帖子 }; }, onError: (err, newPost, 上下文) => { // 出错时回滚 utils.post.list.setData(未定义, context.previousPosts); }, 已解决：() => { // 错误或成功后重新获取 utils.post.list.invalidate(); }, }); ### 上下文管理 **创建上下文：** // 服务器/trpc.ts 从 '@trpc/server/adapters/next' 导入 { CreateNextContextOptions }；从'next-auth/react'导入{getSession}；导出异步函数 createContext({ req, res }: CreateNextContextOptions) { const session =等待 getSession({ req }); 返回{ 要求，资源，会议， db: prisma, // 或您的数据库客户端 }; } 导出类型 Context = Awaited>; 导出 const t = initTRPC.context().create(); **在过程中使用上下文：** const userRouter = 路由器({ 我： protectedProcedure.query(async ({ ctx }) => { // ctx.session 可用并已输入返回等待 ctx.db.user.findUnique({ 其中：{ id: ctx.session.user.id }, }); }), }); ### 批量请求 **自动批处理：** tRPC 在使用 `httpBatchLink` 时自动批处理请求： // 这 3 个查询将在单个 HTTP 请求中发送 const user = trpc.user.getById.useQuery({ id: '1' }); const posts = trpc.post.list.useQuery({ limit: 10 }); const comments = trpc.comment.list.useQuery({ limit: 5 }); **禁用批处理（如果需要）：** 从'@trpc/client'导入{httpLink}； const trpcClient = trpc.createClient({ 链接：[ http链接({ // 而不是 httpBatchLink url: '/api/trpc', }), ], }); ### 订阅模式（WebSocket） **服务器设置：** 从 '@trpc/server/observable' 导入 { observable } ； const postRouter = 路由器({ onNewPost: publicProcedure.subscription(() => { 返回 observable(emit => { const onPost = (post: Post) => { 发射.下一个（帖子）； }; eventEmitter.on('newPost', onPost); 返回（）=> { eventEmitter.off('newPost', onPost); }; }); }), }); **客户端使用情况：** 函数 PostFeed() { trpc.post.onNewPost.useSubscription(未定义, { onData（发布）{ // 将新帖子添加到 UI console.log('新帖子：', post); }, 错误（错误）{ console.error('订阅错误：', err); }, }); 返回

...

； } ### 最佳实践 **1\.对所有输入使用 Zod** * 提供运行时验证和TypeScript类型 * 定义一次模式，随处使用 **2\.按域组织路由器** * 将相关程序放在一起 * 对复杂域使用嵌套路由器 **3\.使用中间件解决跨领域问题** * 认证 * 日志记录 * 速率限制 * 权限 **4\.实施正确的错误处理** * 使用 TRPCError 和适当的代码 * 提供有用的错误消息 * 不要泄露敏感信息 **5\.使用 React Query 进行优化** * 设置适当的staleTime * 使用乐观的更新来获得更好的用户体验 * 实现分页和无限查询 **6\.类型安全第一** * 从服务器导出AppRouter类型 * 使用 inferRouterInputs 和 inferRouterOutputs 作为类型 * 切勿使用“any”类型 **7\.安全** * 验证所有输入 * 实现认证中间件 * 操作前检查权限 * 永远不要相信客户提供的数据 ## 内存协议（强制） **开始之前：** 猫.克劳德/上下文/内存/learnings.md **完成后：** 记录发现的任何新模式或异常。 > 假设中断：您的上下文可能会重置。如果它不在记忆中，那么它就没有发生。

Trpc API 规则

包含技能