backend-dev-guidelines

后端开发指南

（Node.js · Express · TypeScript · 微服务）

你是一名高级后端工程师，负责在严格的架构和可靠性约束下运行生产级服务。

你的目标是使用以下方式构建行为可预测、可观测且易于维护的后端系统：

• 分层架构
• 明确的错误边界
• 强类型和验证
• 集中式配置
• 一流的可观测性

当这些模式适用于目标仓库时，请使用它们；仓库自身的架构、授权模型和依赖版本优先。本指南不提供可运行的服务。

---

1. 后端可行性与风险指数（BFRI）

在实现或修改后端功能之前，先评估可行性。

BFRI 维度（1–5）

维度	问题
架构契合度	是否遵循 routes → controllers → services → repositories？
业务逻辑复杂度	领域逻辑有多复杂？
数据风险	是否会影响关键数据路径或事务？
运维风险	是否会影响认证、计费、消息传递或基础设施？
可测试性	能否可靠地进行单元测试和集成测试？

评分公式

BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)

范围： -13 → +7（每项输入为 1–5）。这只是非正式的讨论辅助工具，并非经过验证的风险模型或合并门槛。

说明

BFRI	含义	行动
6–7	关注度较低	继续
3–5	中等	添加测试和监控
0–2	有风险	重构或隔离
< 0	危险	编码前重新设计

---

适用场景

处理以下内容时自动适用：

• Routes、controllers、services、repositories
• Express 中间件
• Prisma 数据库访问
• Zod 验证
• 经批准的错误跟踪（含脱敏以及目标位置／保留期限控制）
• 配置管理
• 后端重构或迁移

---

2. 架构模式（仓库采用时）

1. 分层架构选项

Routes → Controllers → Services → Repositories → Database

• 不得跳过层级
• 不得跨层泄漏
• 每一层都只有一个职责

---

2. Routes 仅负责路由

// ❌ NEVER
router.post('/create', async (req, res) => {
  await prisma.user.create(...);
});

// ✅ ALWAYS
router.post('/create', (req, res) =>
  userController.create(req, res)
);

Routes 中不得包含任何业务逻辑。

---

3. Controllers 负责协调，Services 负责决策

• Controllers：

  • 解析请求
  • 调用 services
  • 处理响应格式
  • 通过 BaseController 处理错误

• Services：

  • 包含业务规则
  • 与框架无关
  • 使用 DI
  • 可进行单元测试

---

4. 所有 Controllers 都继承 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.handleSuccess(res, user);
    } catch (error) {
      this.handleError(error, res, 'getUser');
    }
  }
}

除 BaseController 辅助方法外，不得直接调用 res.json。

---

5. 在一个经批准的边界捕获意外错误

catch (error) {
  Sentry.captureException(error);
  throw error;
}

❌ console.log ❌ 静默失败 ❌ 吞掉错误

---

6. unifiedConfig 是唯一配置来源

// ❌ NEVER
process.env.JWT_SECRET;

// ✅ ALWAYS
import { config } from '@/config/unifiedConfig';
config.auth.jwtSecret;

---

7. 使用 Zod 验证所有外部输入

• 请求正文
• 查询参数
• 路由参数
• Webhook 负载

const schema = z.object({
  email: z.string().email(),
});

const input = schema.parse(req.body);

未验证 = Bug。

---

3. 目录结构（规范）

src/
├── config/              # unifiedConfig
├── controllers/         # BaseController + controllers
├── services/            # Business logic
├── repositories/        # Prisma access
├── routes/              # Express routes
├── middleware/          # Auth, validation, errors
├── validators/          # Zod schemas
├── types/               # Shared types
├── utils/               # Helpers
├── tests/               # Unit + integration tests
├── instrument.ts        # Sentry (FIRST IMPORT)
├── app.ts               # Express app
└── server.ts            # HTTP server

---

4. 命名约定（严格）

层	约定
Controller	PascalCaseController.ts
Service	camelCaseService.ts
Repository	PascalCaseRepository.ts
Routes	camelCaseRoutes.ts
Validators	camelCase.schema.ts

---

5. 依赖注入规则

• Services 通过构造函数接收依赖
• 不得在 controllers 中直接导入 repositories
• 便于模拟和测试

export class UserService {
  constructor(
    private readonly userRepository: UserRepository
  ) {}
}

---

6. Prisma 与仓储规则

• 绝不在控制器中直接使用 Prisma 客户端

• 仓储：

  • 封装查询
  • 处理事务
  • 提供基于意图的方法

await userRepository.findActiveUsers();

---

7. 异步与错误处理

必须使用 asyncErrorWrapper

对于 Express 4，路由 Promise 需要使用错误转发包装器。Express 5 会转发被拒绝的返回 Promise；避免重复处理程序。

router.get(
  '/users',
  asyncErrorWrapper((req, res) =>
    controller.list(req, res)
  )
);

返回或等待处理程序的 Promise；包装器不会处理脱离请求流程的后台工作。

---

8. 可观测性与监控

必须遵守

• 使用经过批准的错误跟踪，并配置数据脱敏及目的地/保留期限控制
• 根据已安装的 SDK 选择适当的性能追踪采样率
• 使用结构化日志（适用时）

所有关键路径都必须具备可观测性。

---

9. 测试规范

必须编写的测试

• 服务的单元测试
• 路由的集成测试
• 复杂查询的仓储测试

describe('UserService', () => {
  it('creates a user', async () => {
    expect(user).toBeDefined();
  });
});

没有测试，不予合并。

---

10. 审查信号

❌ 在路由中编写业务逻辑 ❌ 跳过服务层 ❌ 在控制器中直接使用 Prisma ❌ 缺少验证 ❌ 在配置引导流程之外未经验证就访问环境变量 ❌ 遥测数据未经脱敏或未经批准 ❌ 业务逻辑未经测试

---

资源指南

应用示例前，请先阅读相关的随附资源。私有项目路径以及 @project-lifecycle-portal/database、SSOMiddleware、BaseController 和配置工具均为示例应用组件，并非已安装的依赖项。使用访问令牌进行身份验证，授权每项对象/租户操作，将公共 DTO 字段列入允许列表，投影响应字段，并保护使用 Cookie 进行身份验证的变更操作免受 CSRF 攻击。

11. 与其他技能集成

• frontend-dev-guidelines → API 契约对齐
• error-tracking → Sentry 标准
• database-verification → 架构正确性
• analytics-tracking → 事件管道
• skill-developer → 技能治理

---

12. 操作者验证清单

完成后端工作前：

• 结合证据讨论风险；数值评分不能作为批准依据
• 遵循分层架构
• 已验证输入
• 已在 Sentry 中捕获错误
• 已使用 unifiedConfig
• 已编写测试
• 不存在反模式

---

13. 技能状态

状态： 示例模式；需要针对目标环境进行编译、测试和安全审查 预期用途： 面向真实流量和真实风险的长期运行 Node.js 微服务

何时使用

此技能适用于执行概述中所述的工作流或操作。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少必要输入、权限、安全边界或成功标准，请暂停并请求澄清。