SuperAPI AI 工具集

backend-dev-guidelines

编程与开发

查看项目

更新于 10-15 23:31

技能介绍

用途:为 Langfuse 的 Next.js/tRPC/BullMQ/TypeScript 单体仓库提供统一后端开发指南,适用于跨多个后端区域的任务,或作为端到端参考索引;范围较窄时只读对应参考文件。

主要能力与约定:

  1. tRPC 功能:在 features/[feature]/server/*Router.ts 定义路由,选用 protected 或 public procedure,使用 JWT 感知中间件认证,校验项目/资源访问与权限,用 Zod v4 校验输入,业务逻辑放入 service 文件,相关处用 traceException 处理错误,在 tests/ 添加单元或集成测试,配置经 env.mjs 读取。
  2. 公开 API 端点:在 pages/api/public/ 创建路由,用 withMiddlewares 与 createAuthedProjectAPIRoute 包装,类型定义在 features/public-api/types/,使用 basic auth,用 Zod schema 校验 query、body 与响应,路径与 schema 含 API 版本,同步更新 Fern API 定义,在 tests/async/ 添加端到端测试。
  3. 队列处理器:在 worker/src/queues/ 创建处理器,队列类型定义在 packages/shared/src/server/queues,业务逻辑放在 features/ 或 worker/src/features/,区分失败任务与应成功但记录错误的任务,在 app.ts 的 WorkerManager 注册队列,添加 worker vitest 覆盖。

核心原则:路由、公开 API 与队列处理器将业务逻辑委托给服务;配置经 env.mjs,不在 env 设置外直接读 process.env;所有外部输入用 Zod v4 校验;简单 CRUD 直接用 Prisma,复杂查询用 repository;用 OpenTelemetry 与 DataDog 做可观测性;项目范围查询始终按 projectId 过滤;保持 Fern API 定义与公开 TypeScript 契约同步;后端测试独立且可并行。

命名:tRPC 路由用 camelCaseRouter.ts,服务用 service.ts,队列处理器用 camelCaseQueue.ts,公开 API 路由用 kebab-case 文件名。

应避免:路由或 procedure 中写业务逻辑、直接使用 process.env、缺少错误处理、缺少输入校验、租户查询缺少 projectId 过滤、用 console.log 代替 logger/traceException。

参考文件按主题划分:架构与包边界、路由与控制器、中间件与认证、服务与仓库、数据库访问、配置、测试。

限制:资料未提供安装命令、收费、价格、平台或效果信息。