backend-dev-guidelines

后端开发指南

在 web/、worker/ 和 packages/shared/ 中的后端与 API 工作中使用本技能。

适用场景

• 创建或修改 tRPC router 和 procedure
• 创建或修改公共 API 端点
• 创建或修改队列处理器、生产者或基于队列的工作流
• 构建或重构后端服务和仓储
• 处理后端认证、中间件、校验或可观测性
• 更新 Prisma 或 ClickHouse 访问模式
• 向共享后端代码添加字段、选项、标志或枚举成员
• 添加或修复后端测试

如何阅读本技能

• 当任务横跨多个后端领域，或你需要端到端的参考地图时，使用本 SKILL.md。
• 当范围较窄时，只阅读与工作匹配的特定参考文件。
• 如果任务引入了用户提供的 URL、出站 HTTP 请求、新的集成，或涉及密钥、RBAC 或重定向处理，在设计或实现变更之前，还应加载共享的 security-review 技能。

添加新概念之前

在向共享 schema 或 payload 添加字段、在共享签名上添加选项或标志、添加枚举成员、环境变量开关，或为某个调用方添加分支之前——或者在断定无需变更之前——请阅读 references/new-concepts.md。

快速上手清单

UI：新增 tRPC 功能

• 在 features/[feature]/server/*Router.ts 中定义 router。
• 使用适当的受保护或公共 procedure。
• 使用感知 JWT 的中间件进行认证。
• 检查项目/资源访问权限和权益。
• 使用 Zod v4 校验输入。
• 将业务逻辑放在 service 文件中。
• 在相关处使用 traceException 处理错误。
• 在 __tests__/ 中添加单元测试或集成测试。
• 通过 env.mjs 访问配置。

现有端点：添加字段或过滤器

在编码之前，将变更归类为新端点、现有端点上的添加字段/过滤器，或语义替换/破坏性变更。

对于添加字段/过滤器：

• 复用规范谓词。对于已支持字段组选择的端点，复用其现有的字段组/投影路径。
• 保留端点现有的响应契约：对于字段组端点，使用常规的可选部分行 schema 和转换器路径；对于普通端点，保留严格的响应 schema 和转换器路径。
• 除非兼容性要求，否则不要创建特定 API 版本的字段集、类型转换或"必须被选择"的运行时断言。
• 扩展示例和契约；不要替换现有过滤器示例。
• 为每个唯一边界编写一个测试，而不是为每个涉及的文件编写一个测试。

SDK：新增公共 API 端点

• 在 pages/api/public/ 中创建路由。
• 用 withMiddlewares 和 createAuthedProjectAPIRoute 包装它。
• 在 features/public-api/types/ 中定义类型。
• 使用 basic auth 进行认证。
• 使用 Zod schema 校验 query、body 和 response。
• 在路径和 schema 中包含 API 版本控制。
• 更新 Fern API 定义以匹配 TypeScript 类型。
• 在 __tests__/async/ 中添加端到端测试。

Worker：新增队列处理器

• 在 worker/src/queues/ 中创建处理器。
• 在 packages/shared/src/server/queues 中定义队列类型。
• 将业务逻辑放在 features/ 或 worker/src/features/ 中。
• 区分失败的任务与应以记录错误方式成功的任务。
• 在 app.ts 的 WorkerManager 中注册队列。
• 添加 worker vitest 覆盖。

核心原则

• tRPC procedure、公共 API 路由和队列处理器将业务逻辑委托给服务。
• 通过 env.mjs 访问配置；不要在环境设置之外直接读取 process.env。
• 使用 Zod v4 校验所有外部输入。
• 简单 CRUD 直接使用 Prisma，复杂查询访问使用 repository。
• 用共享代码已有的词汇表达新需求；向共享抽象添加概念是最后手段，而不是首选。
• 使用 OpenTelemetry 和 DataDog 进行后端可观测性。
• 始终按 projectId 过滤项目范围内的数据库查询。
• 保持 Fern API 定义与公共 TypeScript API 契约同步。
• 保持后端测试独立且可并行安全运行。

实际示例

• 带项目认证和 Zod 输入的 tRPC 路由器： web/src/features/events/server/eventsRouter.ts。
• 带中间件和类型化请求/响应 schema 的公共 API 路由： web/src/pages/api/public/datasets/index.ts。
• 带类型化 job、日志和重试行为的 Worker 队列处理器： worker/src/queues/evalQueue.ts。
• Prisma 和 ClickHouse 的租户过滤器： references/database-patterns.md。

命名约定

• tRPC 路由器：camelCaseRouter.ts，例如 datasetRouter.ts。
• 服务：功能服务器目录中的 service.ts。
• 队列处理器：camelCaseQueue.ts，例如 evalQueue.ts。
• 公共 API 路由：kebab-case 文件名，例如 dataset-items.ts。

应避免的反模式

• 在路由或 procedure 中放置业务逻辑。
• 直接使用 process.env 而不是 env.mjs / env.ts。
• 缺少错误处理。
• 缺少输入校验。
• 在租户范围查询上缺少 projectId 过滤。
• 使用 console.log 而不是 logger / traceException。

参考地图

主题	何时阅读	文件
架构和包边界	你需要了解 web/worker/shared 拆分、请求流或队列生命周期	references/architecture-overview.md
路由和控制器	你正在编写 tRPC procedure、公共 API 路由或队列入口点	references/routing-and-controllers.md
中间件和认证	你正在更改请求认证、权限或中间件组合	references/middleware-guide.md
服务和 repository	你正在放置业务逻辑、repository 代码或 DI 模式	references/services-and-repositories.md
数据库访问	你正在接触 Prisma、ClickHouse、租户过滤器或查询模式	references/database-patterns.md
共享代码中的新概念	你正在向共享抽象添加字段、选项、标志或枚举成员	references/new-concepts.md
配置	你正在添加环境变量、启动配置或运行时开关	references/configuration.md
测试	你正在添加或更新后端测试	references/testing-guide.md