名称: tRPC脚手架工具描述: 遵循DevPrep AI模式，脚手架式创建类型安全的tRPC路由器、过程和Zod模式允许工具: [读取, 写入, 编辑, Bash, Glob, Grep]

tRPC脚手架工具

自动化创建类型安全的tRPC端点，支持Zod验证。

摘要: 运行脚本创建路由器/模式，在_app.ts中注册，使用脚本验证。

自动触发

关键词自动触发：

“新端点”, “创建端点”, “tRPC过程”
“新路由器”, “API”, “Zod模式”

快速标准

文件位置

lib/trpc/routers/
  _app.ts          # 在此注册所有路由器 ⚠️
  {名称}.ts        # 路由器文件

lib/trpc/schemas/
  {实体}.schema.ts  # Zod模式文件

路由器模式

export const 名称路由器 = router({
  执行操作: publicProcedure
    .input(输入模式)
    .output(输出模式)
    .mutation(async ({ input }) => { /* 逻辑 */ }),
});

模式模式

export const 输入模式 = z.object({
  字段: z.string().min(1),
});

export type 输入类型 = z.infer<typeof 输入模式>;  // ⚠️ 必需！

注册（必需！）

// 在_app.ts中
export const appRouter = router({
  ai: aiRouter,
  名称: 名称路由器,  // ⬅️ 在此添加新路由器
});

运行脚本

创建路由器

./.claude/skills/trpc-scaffolder/scripts/create-router.sh 用户
# 创建: lib/trpc/routers/用户.ts
# ⚠️ 记得在_app.ts中注册！

添加过程

./.claude/skills/trpc-scaffolder/scripts/add-procedure.sh ai 获取提示 query
# 输出要添加到路由器的代码片段

创建模式

./.claude/skills/trpc-scaffolder/scripts/create-schema.sh 提示
# 创建: lib/trpc/schemas/提示.schema.ts

验证设置

./.claude/skills/trpc-scaffolder/scripts/validate-trpc.sh
# 检查: 路由器注册、类型导出

快速参考

查询 vs 变更

类型	用途	方法
查询	获取数据（GET）	`.query(async ({ input }) => ...)`
变更	修改数据（POST/PUT/DELETE）	`.mutation(async ({ input }) => ...)`

常见Zod模式

类型	模式	示例
字符串	`z.string().min(1).max(100)`	名称验证
数字	`z.number().int().min(0).max(10)`	难度0-10
邮箱	`z.string().email()`	邮箱验证
可选	`z.string().optional()`	可选字段
数组	`z.array(z.string()).min(1)`	至少1项
枚举	`z.enum(["a", "b", "c"])`	固定选项
对象	`z.object({ field: z.string() })`	嵌套对象

命名约定

路由器: {领域}路由器（例如：ai路由器, 用户路由器）
过程: camelCase（例如：生成问题, 获取提示）
模式: {操作}{实体}{输入\|输出}模式
文件: {实体}.schema.ts, {领域}.ts

错误代码

代码	何时使用	示例
`NOT_FOUND`	资源不存在	用户未找到
`BAD_REQUEST`	无效输入	验证失败
`UNAUTHORIZED`	未认证	需要登录
`FORBIDDEN`	未授权	访问被拒绝
`INTERNAL_SERVER_ERROR`	服务器错误	API失败

常见修复

路由器未注册

// ❌ 忘记此步骤
// ✅ 添加到_app.ts:
import { 用户路由器 } from "./用户";
export const appRouter = router({ ai: ai路由器, 用户: 用户路由器 });

缺少类型导出

// ❌ 没有类型的模式
export const 用户模式 = z.object({ 名称: z.string() });

// ✅ 始终导出推断类型
export type 用户 = z.infer<typeof 用户模式>;

错误的过程类型

// ❌ 使用变更获取数据
获取数据: publicProcedure.mutation(...)

// ✅ 对GET操作使用查询
获取数据: publicProcedure.query(...)

模式验证错误

// ❌ 无验证
字段: z.string()

// ✅ 添加约束
字段: z.string().min(1, "字段必填")

何时加载额外文档

SKILL.md自包含以下内容:

创建路由器和模式
运行脚本
修复常见错误

需要时加载额外文档:

需求	加载
分步教程	`docs/quick-start-guide.md`
高级Zod模式	`docs/trpc-patterns.md` (第1-80行)
错误处理策略	`docs/trpc-patterns.md` (第150-220行)
测试过程	`docs/trpc-patterns.md` (第220-270行)
上下文和中间件	`docs/trpc-patterns.md` (第80-150行)

代码示例:

✅ 完美: examples/good-router.ts, examples/good-schema.ts

完整项目文档: Docs/api-design.md, Docs/api-transition/trpc-migration.md

版本: 1.0.0 | 更新日期: 2025年10月模式: 遵循质量评审员结构（优化版）

名称: tRPC脚手架工具 描述: 遵循DevPrep AI模式，脚手架式创建类型安全的tRPC路由器、过程和Zod模式 允许工具: [读取, 写入, 编辑, Bash, Glob, Grep]