trpc-patterns

TRPC 模式

概述

使用 blogic-template-ts 中成熟的模式实现 TRPC 路由器，涵盖输入架构、过程选择、中间件组合和错误处理。

何时使用此技能

在实现或重构 TRPC 路由器和过程时使用此技能，尤其是在选择基础过程、添加授权中间件或统一错误处理时。

核心规则

1) 将简单架构内联

直接在过程中定义简单的输入架构。

使用项目枚举和共享类型，而不是硬编码字符串字面量。

protectedProcedure.input(z.object({ organizationId: z.string().min(1) }));

遵循以下规则：

• 将简单明了的架构内联。
• 复用项目包中的共享枚举／类型。
• 只有在复用需求或复杂度足以支持时，才提取架构常量。

在 references/simple-schemas.md 中查看详细示例。

2) 选择范围最窄的有效基础过程

按以下顺序选择基础过程：

1. 根据访问要求选择，而不是为了实现方便。
2. 无需身份验证时，选择 publicProcedure。
3. 任何已通过身份验证的用户都可以访问时，选择 protectedProcedure。
4. 需要全局管理员角色时，选择 adminProcedure。
5. 需要基于 organizationId 限定成员资格时，选择 protectedMemberAccessProcedure。
6. 只有在现有过程都无法表达所需访问规则时，才使用 .use() 构建自定义过程。

应用以下决策树：

• 无需身份验证 -> publicProcedure
• 需要身份验证，但不限定组织范围 -> protectedProcedure
• 仅限全局管理员执行的操作 -> adminProcedure
• 限定组织范围且需要检查成员资格的操作 -> protectedMemberAccessProcedure
• 还需检查角色／权限／资源 -> 在最接近的基础过程上添加中间件

在 references/custom-procedures.md 中查看完整的过程示例和上下文行为。

3) 使用上下文增强组合中间件

使用 .use() 创建可复用的中间件，并始终通过 opts.next(...) 继续执行。

const procedure = protectedProcedure.use(async (opts) => opts.next({ ctx: {} }));

遵循以下规则：

• 根据职责命名中间件函数。
• 仅使用下游处理程序所需的值来增强上下文。
• 优先基于现有基础过程构建，而不是引入新的过程。

在 references/middleware-patterns.md 中查看高级中间件模式。

4) 抛出标准化应用错误

从项目基础设施中导入并抛出标准化错误辅助函数。

if (!resource) throw notFoundError("Resource not found");

遵循以下规则：

• 抛出基于辅助函数的错误（badRequestError、unauthorizedError、forbiddenError、notFoundError）。
• 如果项目已有错误辅助函数，不要在路由和中间件代码中手动实例化 TRPCError。
• 错误消息应以操作为导向，并针对具体领域。

在 references/error-handling.md 中查看完整模式。

5) 将导入视为项目约定

对于 blogic-template-ts 仓库，请遵循以下约定：

• 从项目包中导入共享领域枚举／类型（例如 @project/common）。
• 从项目基础设施模块中导入标准化错误辅助函数（例如 @/infrastructure/errors）。

在此生态系统之外工作时，请将这些约定映射到目标代码库中的等效模块。

类型推断指南

依赖后端路由器定义提供的静态 TypeScript 推断。

遵循以下规则：

• 以一致的方式导出根路由器类型。
• 将路由器类型导入前端 TRPC 客户端配置。
• 避免手动定义与推断出的 TRPC 类型重复的端点响应／输入类型。

在 references/custom-procedures.md 中查看更多示例，并保持路由器导出方式一致。

范围边界

此技能专注于 TRPC 路由器结构、访问控制、中间件和错误处理。

将查询级性能调优（JOIN 策略、批量读取、减少 N+1、索引）交由 performance-optimization 技能处理。

资源

阅读长篇示例和实现细节：

• references/simple-schemas.md - 内联模式的完整示例
• references/custom-procedures.md - 基本过程的行为和上下文增强
• references/middleware-patterns.md - 高级中间件组合模式
• references/error-handling.md - 基于辅助函数的错误模式详解

如需查询和数据库性能方面的指导，请加载 performance-optimization 技能。