backend-dev-guidelines

# 后端开发指南 ## 目标 在使用现代 Node.js/Express/TypeScript 模式的后端微服务（如 blog-api, auth-service, notifications-service）中建立一致性和最佳实践。 ## 何时使用此技能 在进行以下工作时自动激活： - 创建或修改路由、端点、API - 构建控制器、服务、存储库 - 实现中间件（认证、验证、错误处理） - 使用 Prisma 进行数据库操作 - 使用 Sentry 进行错误追踪 - 使用 Zod 进行输入验证 - 配置管理 - 后端测试和重构 --- ## 快速开始 ### 新后端功能检查清单 - [ ] **路由**: 清晰定义，委托给控制器 - [ ] **控制器**: 继承 BaseController - [ ] **服务**: 包含依赖注入的业务逻辑 - [ ] **存储库**: 数据库访问（如果逻辑复杂） - [ ] **验证**: Zod 模式 - [ ] **Sentry**: 错误追踪 - [ ] **测试**: 单元测试 + 集成测试 - [ ] **配置**: 使用 unifiedConfig ### 新微服务检查清单 - [ ] 目录结构 (参考 [architecture-overview.md](architecture-overview.md)) - [ ] 用于 Sentry 的 instrument.ts - [ ] unifiedConfig 设置 - [ ] BaseController 类 - [ ] 中间件栈 - [ ] 错误边界 - [ ] 测试框架 --- ## 架构概览 ### 分层架构 HTTP 请求 ↓ 路由 (仅负责路由) ↓ 控制器 (请求处理) ↓ 服务 (业务逻辑) ↓ 存储库 (数据访问) ↓ 数据库 (Prisma) **核心原则:** 每一层只承担一个职责。 详见 [architecture-overview.md](architecture-overview.md)。 --- ## 目录结构 service/src/ ├── config/ # UnifiedConfig ├── controllers/ # 请求处理器 ├── services/ # 业务逻辑 ├── repositories/ # 数据访问 ├── routes/ # 路由定义 ├── middleware/ # Express 中间件 ├── types/ # TypeScript 类型 ├── validators/ # Zod 模式 ├── utils/ # 工具类 ├── tests/ # 测试 ├── instrument.ts # Sentry (优先导入) ├── app.ts # Express 设置 └── server.ts # HTTP 服务器 **命名规范:** - 控制器: `PascalCase` - `UserController.ts` - 服务: `camelCase` - `userService.ts` - 路由: `camelCase + Routes` - `userRoutes.ts` - 存储库: `PascalCase + Repository` - `UserRepository.ts` --- ## 核心原则 (7 条关键规则) ### 1. 路由