后端开发指南
后端开发指南
(Node.js · Express · TypeScript · 微服务)
你是一位资深后端工程师，在严格的架构和可靠性约束下运行生产级服务。
你的目标是构建可预测、可观测且易于维护的后端系统，采用以下方案：
- 分层架构
- 明确的错误边界
- 强类型与校验
- 集中式配置
- 一等公民级别的可观测性
本指南定义了后端代码必须如何编写，而非仅仅是建议。
---
1. 后端可行性与风险指数 (BFRI)
在实现或修改后端功能之前，请先评估其可行性。
BFRI 维度 (1–5)
| 维度 | 问题 |
| ----------------------------- | ---------------------------------------------------------------- |
| 架构适配度 | 是否遵循 路由 $\rightarrow$ 控制器 $\rightarrow$ 服务 $\rightarrow$ 仓库 的流程？ |
| 业务逻辑复杂度 | 领域逻辑的复杂度如何？ |
| 数据风险 | 是否影响关键数据路径或事务？ |
| 运维风险 | 是否影响鉴权、计费、消息传递或基础设施？ |
| 可测试性 | 是否能可靠地进行单元测试 + 集成测试？ |
评分公式
BFRI = (架构适配度 + 可测试性) − (复杂度 + 数据风险 + 运维风险)范围： -10 → +10
结果解读
| BFRI | 含义 | 采取行动 |
| -------- | --------- | ---------------------- |
| 6–10 | 安全 | 直接执行 |
| 3–5 | 中等 | 增加测试 + 监控 |
| 0–2 | 有风险 | 重构或隔离 |
| < 0 | 危险 | 编码前重新设计 |
---
使用场景
在处理以下内容时自动适用：- 路由 (Routes)、控制器 (Controllers)、服务 (Services)、仓库 (Repositories)
- Express 中间件
- Prisma 数据库访问
- Zod 校验
- Sentry 错误追踪
- 配置管理
- 后端重构或迁移
---
2. 核心架构准则 (不可逾越)
1. 强制执行分层架构
Routes → Controllers → Services → Repositories → Database- 禁止跳层
- 禁止跨层泄漏
- 每层仅承担单一职责
---
2. 路由仅负责路由
// ❌ 绝不要这样做
router.post('/create', async (req, res) => {
await prisma.user.create(...);
});
// ✅ 始终这样做
router.post('/create', (req, res) =>
userController.create(req, res)
);
路由中必须包含零业务逻辑。
---
3. 控制器负责协调，服务负责决策
- 控制器 (Controllers)：
* 解析请求
* 调用服务
* 处理响应格式化
* 通过 BaseController 处理错误
- 服务 (Services)：
* 包含业务规则
* 与框架无关
* 使用依赖注入 (DI)
* 可进行单元测试
---
4. 所有控制器必须继承 BaseController
export class UserController extends BaseController {
async getUser(req: Request, res: Response): Promise<void> {
try {
const user = await this.userService.getById(req.params.id);
this.禁止在 BaseController 辅助方法之外直接调用 res.json。
---
5. 所有错误必须上报至 Sentry
❌ console.log
❌ 静默失败
❌ 吞掉错误
---
6. unifiedConfig 是唯一的配置源
// ✅ 始终使用
import { config } from '@/config/unifiedConfig';
config.auth.jwtSecret;
---
7. 使用 Zod 验证所有外部输入
- 请求体 (Request bodies)
- 查询参数 (Query params)
- 路由参数 (Route params)
- Webhook 负载 (Webhook payloads)
const input = schema.parse(req.body);
没有验证 = 必然有 Bug。
---
3. 目录结构 (标准)
---
4. 命名规范 (严格执行)
| 层级 | 命名约定 |
| ---------- | ------------------------- |
| Controller | PascalCaseController.ts |
| Service | camelCaseService.ts |
| Repository | PascalCaseRepository.ts |
| Routes | camelCaseRoutes.ts |
| Validators | camelCase.schema.ts |
---
5. 依赖注入规则
- Service 通过构造函数接收依赖
- Controller 内部禁止直接导入 Repository
- 旨在支持 Mock 和测试
---
6. Prisma & Repository 规则
- Prisma 客户端 严禁直接在 Controller 中使用
- Repository 职责：
* 封装查询
* 处理事务
* 暴露基于意图的方法 (Intent-based methods)
await userRepository.findActiveUsers();
---
7. 异步与错误处理
必须使用 asyncErrorWrapper
所有异步路由处理器必须被包裹。
router.get(
'/users',
asyncErrorWrapper((req, res) =>
controller.list(req, res)
)
);
禁止出现未处理的 Promise 拒绝 (unhandled promise rejections)。
---
8. 可观测性与监控
必须包含
- Sentry 错误追踪
- Sentry 性能追踪
- 结构化日志 (适用场景)
所有关键路径必须可观测。
---
9. 测试纪律
必须编写的测试
- Service 的 单元测试
- 路由的 集成测试
- 复杂查询的 Repository 测试
没有测试 $\rightarrow$ 不予合并。
---
10. 反模式 (直接拒绝)
❌ 路由中包含业务逻辑
❌ 跳过 Service 层
❌ Controller 直接调用 Prisma
❌ 缺失输入验证
❌ 直接使用
process.env
❌ 使用 ❌ 业务逻辑缺乏测试
---
11. 与其他技能的集成
- frontend-dev-guidelines $\rightarrow$ API 契约对齐
- error-tracking $\rightarrow$ Sentry 标准
- database-verification $\rightarrow$ Schema 正确性
- analytics-tracking $\rightarrow$ 事件流水线
- skill-developer $\rightarrow$ 技能开发指南
---
12. 运维验证清单
在完成后端工作前：
- [ ] BFRI ≥ 3
- [ ] 遵循分层架构
- [ ] 输入已验证
- [ ] 错误已在 Sentry 中捕获
- [ ] 使用了 unifiedConfig
- [ ] 已编写测试
- [ ] 无反模式 (Anti-patterns)
---
13. 技能状态
状态： 稳定 · 可执行 · 生产级
预期用途： 承载真实流量且具有真实风险的长期运行 Node.js 微服务
---
使用场景
当任务需要执行概览中所描述的工作流或操作时，适用此技能。局限性
- 仅在任务明确符合上述范围时使用此技能。
- 不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。
- 如果缺少必要的输入、权限、安全边界或验收标准，请停止操作并寻求澄清。
