# tRPC API架构技巧（T3堆栈）您可以在 **T3 风格** 项目（Next.js 15、tRPC、TanStack React Query、Zod、Prisma、BetterAuth）中实现和重构 tRPC API。您遵循用户的**路由器 + 控制器**架构及其过程命名（“authorizedProcedure”）。 ## 什么时候使用这个技能 * 创建新的 tRPC 路由器/过程/端点 * 将端点重构为控制器文件 * 添加 Zod 模式 + 打字模式 * 设计基于中间件的授权（工作区访问、角色门） * 客户端使用指导（服务器组件和客户端组件） ## 规范的项目模式（必须遵循） ### 过程类型在 `src/server/api/trpc.ts` 中定义： * `publicProcedure`：无需身份验证； `ctx.session` / `ctx.user` 可能为空。 * `authorizedProcedure`：需要有效的会话；保证 `ctx.user` 和 `ctx.session` 不为空；如果未登录，则抛出“UNAUTHORIZED”。 * `authorizedAdminProcedure`：需要管理员用户；保证`ctx.user.isAdmin === true`；如果不是管理员，则抛出“UNAUTHORIZED”。 ### 上下文形状每个处理程序都会收到： { 会议：会议 |空，用户：用户 |空，数据库：PrismaClient，标题：标题， } ### 路由器+控制器结构（域优先）路由器聚合程序；控制器实现业务逻辑。 src/服务器/api/<域>/ ├── 路由器.ts ├── 控制器/ │ ├── 创建.ts │ ├── 更新.ts │ ├── 删除.ts │ └── 列表.ts └── 中间件/ └── 访问.ts **路由器示例** 从“~/server/api/trpc”导入{createTRPCRouter}；从“./controller/create”导入创建；从“./controller/update”导入更新；从“./controller/delete”导入_delete；导出 const eventRouter = createTRPCRouter({ 创造, 更新， delete: _delete, // 保留关键字解决方法 }); **控制器示例** 从“zod”导入{类型z}；从“@trpc/server”导入{TRPCError}；从“~/server/api/trpc”导入{authorizedProcedure，类型Controller}；从“~/schemas/event”导入{CreateEventInputSchema}；从“../middleware/access”导入{ isWorkspaceAdminMiddleware }；常量处理程序：控制器< z.infer, { id: 字符串 } > = 异步 ({ ctx, 输入 }) => { 等待 isAdminMiddleware(input.workspaceId, ctx); const 创建 = 等待 ctx.db.event.create({ 数据：{ 工作空间Id：输入.工作空间Id，标题：输入.标题，开始日期：输入.开始日期，结束日期：输入.结束日期， }, 选择：{id：true}， }); 如果（！创建）{ 抛出新的 TRPCError({ 代码: "INTERNAL_SERVER_ERROR" }); } 返回已创建； }; 导出默认授权程序 .input（创建事件输入架构） .mutation(处理程序); ## 实施的最佳实践（tRPC + T3） ### 1) 始终使用 Zod 验证输入 * 每个过程都应该有`.input(SomeSchema)`，除非真正无输入。 * 将模式保留在 `src/schemas/` 中并对它们进行域分组（例如 `src/schemas/event.ts`）。 ### 2) 保持处理程序可测试且较小 * 没有内联 100 行 `.query(async () => ...)`。 * 控制器应该是纯业务逻辑+中间件调用+Prisma。 ### 3) 通过中间件授权（关注点分离） * 不要混合内联权限检查。 * 中间件应该是可重用的并且有针对性： * `hasAccessMiddleware`（任何角色） * 中间件应该抛出 `TRPCError({ code: "FORBIDDEN" | "UNAUTHORIZED" })`。 tRPC支持中间件链接和上下文扩展；用它来保持程序干净。（参见参考资料。） ### 4) 使用事务进行多步突变 * 使用 `ctx.db.$transaction(async (db) => { ... })` 进行原子多写流。 * 保持交易简短；避免写事务中的长读取。 ### 5) 输出输入规则 * 优选 Prisma 客户端的类型 * 如果返回子集，请使用“选择”并导出派生类型（从您的 Prisma 类型技能）。 ### 6) 错误处理和格式化 * 使用一致的代码/消息抛出`TRPCError`。 * 对于共享的类型化错误元数据，在根路由器上实现错误格式化程序（tRPC 支持类型化错误格式化）。（参见参考资料。） ### 7) Next.js 15 + RSC 指导 * tRPC 可以与 React Server 组件配合使用，但 RSC 通常不需要 API 层进行读取。 * 使用 tRPC 主要用于： * 已验证的突变 * 客户端驱动的读取需要缓存/分页 * 跨环境重用需要时遵循 tRPC 的 RSC 集成指南。（参见参考资料。） ## 客户端使用模式（TanStack React Query）使用 `~/trpc/react` 钩子（TanStack React Query）来实现交互式 UI： “使用客户端”；从“~/trpc/react”导入{api}；导出函数EventsManager（{workspaceId}：{workspaceId：字符串}）{ const ruter = useRouter(); const create = api.workspace.event.create.useMutation({ onSuccess: async () => { 等待路由器.refresh(); }, }); 返回（ <按钮 onClick={() => create.mutate({workspaceId, title: "演示", startDate: new Date(), endDate: new Date() })} > 创建）； } ## BetterAuth 集成期望此技能假设 BetterAuth 会话/用户在“ctx”中可用（通过“createContext”）。当客户端必须将身份验证 cookie/标头转发到 tRPC 链接时，请确保标头包含会话 cookie（批量链接标头）。（请参阅参考资料 - 社区注释。） ## 可交付成果格式（您应该如何回应）添加端点时，输出： 1. **新的/更新的 Zod 架构** 在 `src/schemas/.ts` 中 2. **控制器文件** : `src/server/api//controller/.ts` 3. **路由器更新** : `src/server/api//router.ts` 4. **客户端使用片段**（服务器组件+客户端组件钩子示例） 5. 任何必需的**中间件添加**以及原因 ## 要避免的反模式（硬规则） * ❌ `router.ts` 内没有内联大型处理程序 * ❌ 对于具有输入的端点，不会缺少 `.input()` 验证 * ❌ 业务逻辑内部没有分散的身份验证检查；使用中间件 * ❌ 没有事务就不能进行多步写入 ## 其他资源 * 有关完整的 TRPC 详细信息，请参阅 [reference.md]()

特尔普克

包含技能