---

name: backend-dev-guidelines description: "你是一名高级后端工程师，在严格的架构和可靠性约束下运维生产级服务。用于路由、控制器、服务、仓储、Express 中间件或 Prisma 数据库访问。" risk: unknown source: community date_added: "2026-02-27"

后端开发指南

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

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

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

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

此技能定义了后端代码必须如何编写，而非仅仅是建议。

---

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

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

BFRI 维度（1-5）

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

评分公式

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

范围： -10 → +10

解读

| BFRI | 含义 | 行动 | | ---- | ---- | ---- | | 6-10 | 安全 | 继续 | | 3-5 | 中等 | 添加测试+监控 | | 0-2 | 有风险 | 重构或隔离 | | < 0 | 危险 | 编码前重新设计 |

---

使用场景

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

• 路由、控制器、服务、仓储
• Express 中间件
• Prisma 数据库访问
• Zod 验证
• Sentry 错误追踪
• 配置管理
• 后端重构或迁移

---

2. 核心架构准则（不可协商）

1. 分层架构是强制的

Routes → Controllers → Services → Repositories → Database

• 不允许跳层
• 不允许跨层泄漏
• 每层有一个职责

---

2. 路由只做路由

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

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

路由必须包含零业务逻辑。

---

3. 控制器协调，服务决策

• 控制器：

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

• 服务：

  • 包含业务规则
  • 与框架无关
  • 使用依赖注入
  • 可单元测试

---

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.handleSuccess(res, user);
    } catch (error) {
      this.handleError(error, res, 'getUser');
    }
  }
}

BaseController 辅助方法之外不允许原始 res.json 调用。

---

5. 所有错误发送到 Sentry

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. 命名约定（严格）

| 层 | 约定 | | -- | ---- | | 路由 | user.routes.ts | | 控制器 | UserController | | 服务 | UserService | | 仓储 | UserRepository | | 验证器 | userSchema |