backend-dev-guidelines

Backend Development Guidelines - Node.js 后端开发规范

技能概述

为 Node.js + Express + TypeScript 微服务提供企业级后端开发规范，包含分层架构设计、BaseController 模式、依赖注入、Prisma 仓储、Zod 验证、Sentry 错误追踪等生产级最佳实践。

适用场景

1. 生产级 Node.js 微服务开发

当你需要构建承受真实流量的生产环境后端服务时，这套规范确保代码的可预测性、可观测性和可维护性。通过强制分层架构和严格的错误处理，避免常见的架构债务和维护陷阱。

2. 团队后端开发标准统一

适用于多人协作的后端团队，通过统一的目录结构、命名规范和开发模式，降低代码审查成本，新成员快速上手，确保所有服务遵循相同的质量标准。

3. TypeScript + Express 技术栈项目

专为使用 TypeScript 和 Express 框架的项目设计，充分利用强类型检查和面向对象特性，结合 Prisma ORM、Zod 验证等生态工具，构建类型安全的后端系统。

核心功能

1. 分层架构强制执行

严格定义 Routes → Controllers → Services → Repositories → Database 的数据流向，禁止跨层调用和层间泄露。路由层只做路由分发，控制器层负责协调，服务层处理业务逻辑，仓储层封装数据访问。通过架构约束确保代码职责单一、易于测试和维护。

2. Backend Feasibility & Risk Index（BFRI）评估体系

在实现任何后端功能前，通过五个维度（架构适配度、业务复杂度、数据风险、操作风险、可测试性）评估可行性，计算风险指数并指导决策。BFRI ≥ 6 可直接实施，3-5 需要补充测试和监控，低于 0 必须重新设计。

3. 生产级可观测性与错误处理

强制要求所有错误通过 Sentry 追踪，禁止使用 console.log 或静默失败。通过 BaseController 统一错误处理和响应格式，结合 unifiedConfig 集中配置管理，确保生产环境的所有关键路径可观测、可监控。

常见问题

什么是 BFRI？如何使用后端可行性风险指数？

BFRI（Backend Feasibility & Risk Index）是一套量化评估后端功能实施风险的框架。从架构适配、业务复杂度、数据风险、操作风险、可测试性五个维度各打 1-5 分，通过公式 (架构适配 + 可测试性) − (复杂度 + 数据风险 + 操作风险) 计算得分。得分 6-10 分可直接实施，3-5 分需补充测试和监控，0-2 分需要重构或隔离，低于 0 则必须重新设计。

为什么路由层不能包含业务逻辑？

路由层的唯一职责是将 HTTP 请求分发到对应的控制器，任何业务逻辑都应该在服务层实现。这样设计的好处包括：便于单元测试（控制器和服务可独立测试）、避免代码重复、支持多协议复用（同一服务可被 HTTP 和 WebSocket 调用）、降低维护成本。路由中包含业务逻辑是本规范明确禁止的反模式。

统一配置管理 unifiedConfig 相比直接使用 process.env 有什么优势？

unifiedConfig 是项目中唯一的配置来源，相比直接使用 process.env 有以下优势：类型安全（TypeScript 类型定义）、集中管理（所有配置在一处维护）、环境隔离（开发/测试/生产环境配置分离）、默认值处理、配置验证。直接使用 process.env 容易出现拼写错误、类型不一致、配置散落各处等问题，是本规范明确禁止的反模式。