NestJS Starter 项目结构完全解析：6大模块的REST API单体架构设计一图看懂

NestJS Starter 项目结构完全解析：6大模块的REST API单体架构设计一图看懂

【免费下载链接】nestjs-starter-rest-apiNestJS Starter Kit. Monolithic Backend. REST API.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-api

本文带你快速搞懂 nestjs-starter-rest-api——一个基于 NestJS 11 的轻量级单体后端 REST API 启动套件。它开箱即用地内置了 JWT 认证、RBAC 权限、TypeORM 数据库、Docker 部署等能力，是新手搭建企业级 Node.js 后端的理想起点。

为什么值得用这个 NestJS 启动套件

相比从零搭建，这个 starter kit 把后端开发中最耗时的"基础设施"都做好了：

此外还附带 Prettier 格式化、Husky 提交钩子、Commitlint 规范、SonarCloud 代码质量检查等"隐性福利"。

全景图：6大模块一图看懂

整个src/采用 NestJS 的模块化单体架构，所有业务模块在 app.module.ts 中统一装配：

src/ ├── main.ts # 应用入口：端口、前缀、Swagger ├── app.module.ts # 根模块，装配所有业务模块 ├── cli.ts # 命令行入口 │ ├── ① 应用入口区（src/ 根文件） ├── ② user/ 用户模块（账户管理） ├── ③ auth/ 认证授权模块（JWT + RBAC） ├── ④ article/ 文章模块（业务 CRUD 示例） ├── ⑤ shared/ 共享模块（配置、日志、过滤器、中间件） │ migrations/ # ⑥ 数据库迁移文件 test/ # ⑥ E2E 端到端测试 scripts/ # ⑥ 辅助脚本（npm 代理、JWT 密钥生成） docs/ # ⑥ 架构与 API 文档

一句话理解：业务模块各管一个领域，共享模块提供公共地基，外围区域负责数据演进和质量保障。官方结构说明见 project-structure.md。

① 应用入口区：main.ts 如何拉起整个应用

main.ts 是全局装配点，做了四件关键事：

1. 全局路由前缀：所有接口统一挂在/api/v1下，天然支持未来版本升级
2. 全局校验管道：ValidationPipe配合 class-validator 自动拦截非法参数
3. 请求追踪：RequestIdMiddleware为每个请求打上唯一 ID，方便日志排查
4. Swagger 文档：启动后访问/swagger即可看到全部接口文档

根模块 app.module.ts 仅做一件事——导入四大模块：SharedModule、UserModule、AuthModule、ArticleModule。结构极简，一眼看清依赖全貌。

② auth 模块：JWT 认证与 RBAC 权限核心

auth 模块是整个安全体系的"心脏"，内部按职责拆成六个目录：

auth/ ├── constants/ # 角色常量、策略常量 ├── controllers/ # 登录、注册、刷新 Token 接口 ├── decorators/ # @Roles 角色装饰器 ├── dtos/ # 登录/注册输入输出 DTO ├── guards/ # 4 道守卫：本地认证、JWT、刷新Token、角色校验 └── strategies/ # 3 种 Passport 策略：local、jwt-auth、jwt-refresh

亮点设计：

• RS256 非对称签名：JWT 使用公钥/私钥对（auth.module.ts），私钥仅用于签发，公钥用于校验，安全性高于常见的 HS256
• 双 Token 机制：短期 access token + 长期 refresh token，jwt-refresh.guard.ts专门负责无感刷新
• 声明式鉴权：控制器方法上标注角色装饰器，配合roles.guard.ts自动拦截越权请求

③ user 模块：标准业务模块的分层样板

user 模块是最值得"抄作业"的标准分层结构，每个目录都有明确分工：

注意其中的user-acl.service.ts：它继承共享模块的BaseAclService，声明"谁能对 User 资源做什么操作"。这套 ACL 机制的完整用法可参考 acl.md，比如可以写出自定义规则——"只有文章作者本人能修改自己的文章"。

④ article 模块：可复用的 CRUD 业务模板

article 模块与 user 模块结构完全同构（controller → service → repository → entity），是标准的"增删改查"业务模板。

当你要新增一个业务域（比如订单、商品），只需照此结构复制一份，再在 app.module.ts 中导入即可——这就是模块化单体架构最爽的地方：每个领域自成一包，内部高内聚，之间低耦合。

⑤ shared 模块：所有模块共享的地基

shared.module.ts 是全应用的基础设施层，其他模块都依赖它：

• 配置中心：ConfigModule统一管理.env环境变量（数据库、JWT 密钥、端口）
• 数据库连接：TypeOrmModule全局注册 Postgres 连接，实体按约定路径自动扫描
• winston 日志：AppLoggerModule提供结构化日志能力
• 全局异常过滤器：AllExceptionsFilter兜底捕获所有未处理异常，统一返回错误格式
• 日志拦截器：LoggingInterceptor记录每个请求的处理耗时
• 中间件：request-id.middleware.ts注入请求追踪 ID

简单说：业务模块负责"做什么"，shared 模块负责"怎么跑"。

⑥ 外围基建区：数据演进与质量保障

根目录下还有四个"非 src"区域，构成项目的工程化保障：

• migrations/：TypeORM 迁移文件（CreateUsers.ts），数据库结构随代码版本可追溯地演进
• test/：E2E 端到端测试，覆盖 app、auth、user、article 四大场景
• scripts/：generate-jwt-keys 一键生成 JWT 密钥对；npm脚本让 Docker 内外命令行为一致
• docs/：架构文档与 middleware.md 等专项说明

请求生命周期：6大模块如何协同工作

以一个"用户登录"请求为例，完整走一遍架构：

1. 请求进入 →RequestIdMiddleware打上追踪 ID
2. 经过ValidationPipe校验参数合法性
3. 路由到 auth.controller.ts
4. local.strategy.ts验证用户名密码，AuthService调用 UserModule 查询用户
5. 签发 JWT，返回 access + refresh token
6. LoggingInterceptor记录耗时；若中途抛错，AllExceptionsFilter统一格式化返回

一条请求横向穿越 shared、auth、user 三个模块——模块间协作清晰，但各自职责独立，这正是单体架构"好维护"的关键。

快速上手：3步本地启动指南

想亲手体验这套架构？三步即可跑起来：

git clone https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-api cd nestjs-starter-rest-api && npm install cp .env.template .env && ./scripts/generate-jwt-keys

然后把生成的 JWT 公钥/私钥 base64 值填入.env，执行npm run start即可。访问http://localhost:3000/swagger，你将看到一个文档齐全的 REST API——这就是这套 starter kit 的交付水准。

小结：这套架构给新手的3个启示

1. 单体不等于混乱：按领域划分模块（user / auth / article），每个模块内部严格分层，未来需要拆分微服务时成本极低
2. 安全体系一次到位：JWT 双 Token + RBAC + ACL 三层防护，避免了"先上线后补安全"的常见陷阱
3. 基建与业务分离：shared 模块承载配置、日志、异常处理等横切关注点，业务模块保持纯粹

对于想快速交付企业级 Node.js 后端的新手而言，读懂这 6 大模块的设计逻辑，你就掌握了 NestJS 单体架构的核心骨架。

【免费下载链接】nestjs-starter-rest-apiNestJS Starter Kit. Monolithic Backend. REST API.项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-starter-rest-api