后端系统架构

本文说明 art-design-pro-server 的后端架构。阅读本页后，你应该能理解 Nest 应用如何启动、全局基础设施如何装配，以及一个请求从进入服务到返回响应会经过哪些层。

架构分层

商业版后端可以按 5 层理解：

层级	主要目录	职责
启动层	src/main.ts	创建 Nest 应用，注册全局前缀、版本、CORS、Swagger、过滤器、拦截器、校验管道
装配层	src/app.module.ts	装配配置、限流、调度、Prisma、健康检查和业务模块
基础设施层	src/common、src/config、src/filters、src/guards、src/interceptors、src/prisma	通用 DTO、配置、异常处理、认证守卫、响应转换、数据库访问
业务模块层	src/modules	认证、用户、角色、菜单、文件、内容、工作流、商城、监控等业务能力
数据与脚本层	prisma、src/scripts	数据模型、迁移、默认数据、管理员、角色权限、定时任务初始化

启动流程

启动入口在 src/main.ts：

flowchart TD
  A["NestFactory.create(AppModule)"] --> B["useLogger(winston)"]
  B --> C["enableShutdownHooks()"]
  C --> D["helmet()"]
  D --> E["setGlobalPrefix + enableVersioning"]
  E --> F["trust proxy"]
  F --> G["AllExceptionFilter"]
  G --> H["TransformInterceptor"]
  H --> I["ValidationPipe"]
  I --> J["configureCors()"]
  J --> K["SwaggerModule.setup()"]
  K --> L["app.listen(port)"]

这说明全局异常、统一响应、DTO 校验、CORS 和 Swagger 都在应用启动阶段统一装配，而不是分散在单个模块中维护。

请求处理链路

一个常规 API 请求大致会经过：

flowchart TD
  A["HTTP Request"] --> B["RequestIdMiddleware"]
  B --> C["ApiSecurityMiddleware"]
  C --> D["ThrottlerGuard"]
  D --> E["JwtGuard / ApiPermission"]
  E --> F["Controller"]
  F --> G["DTO ValidationPipe"]
  G --> H["Service"]
  H --> I["PrismaService"]
  I --> J["TransformInterceptor"]
  J --> K["HTTP Response"]

如果过程中出现异常，会进入 AllExceptionFilter，并转换成统一结构。

根模块装配

AppModule 负责把全局能力和业务模块装配到一起：

• ConfigModule.forRoot()：加载 .env 并进行环境变量校验。
• ThrottlerModule.forRootAsync()：装配限流策略。
• ScheduleModule.forRoot()：启用定时任务能力。
• PrismaModule：提供数据库访问基础设施。
• HealthModule：提供健康检查能力。
• modules/*：装配各业务模块。
• RequestIdMiddleware、ApiSecurityMiddleware：挂载到所有路由。

统一响应与异常

成功响应由 TransformInterceptor 统一包装：

{
  code: 200,
  msg: '请求成功',
  data: {}
}

异常由 AllExceptionFilter 统一处理，主要职责包括：

• 映射 Nest HttpException。
• 映射 Prisma 常见错误。
• 映射 JWT 相关异常。
• 记录 requestId、路径、方法、查询参数和异常堆栈。
• 返回统一的 { code, msg, data } 响应结构。

模块组织方式

大多数业务模块遵循下面结构：

src/modules/<module>
├── <module>.module.ts
├── <module>.controller.ts
├── <module>.service.ts
└── dto/

复杂模块会继续拆分：

• repositories/
• services/
• interfaces/
• decorators/

新增模块时，建议沿用当前结构，避免在 main.ts、app.module.ts 或公共基础设施中混入业务细节。