# nest-enterprise **Repository Path**: wyuers/nest-enterprise ## Basic Information - **Project Name**: nest-enterprise - **Description**: npx create-nest-enterprise my-project 即可完成项目初始化。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-02 - **Last Updated**: 2026-06-03 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # create-nest-enterprise `create-nest-enterprise` 是一个专为企业级应用打造的、支持长期复用且兼容动态升级的 NestJS 旗舰脚手架。它彻底解耦了 CLI 工具与模板工程，能够在用户创建项目时自动向 NPM Registry 查询并渲染当前最新的 NestJS 11+ 生态与 Prisma 7+ 依赖版本，确保所生成的项目始终运行在最新、最稳定的技术生态之上。 本脚手架默认集成了高性能的 **Biome** 工具链、**nestjs-pino** 日志系统、**Prisma 7.x 数据库驱动适配器**、**BullMQ + Redis 8 异步日志队列**、**多策略文件存储 (策略模式)** 以及细粒度的 **RBAC 鉴权机制**。 --- ## 📂 项目结构设计 ### 1. 本脚手架开发目录 (解耦架构) ``` nest-enterprise/ ├── package.json # 根项目配置文件 (npm workspaces) ├── packages/ │ ├── cli/ # 脚手架 CLI 工具 (Commander + Inquirer) │ │ ├── src/ │ │ │ ├── index.ts # 命令行入口 (动态获取 NPM 版本、拉取模板、精准渲染) │ │ │ ├── questions.ts # 交互问题定义 (数据库、Redis、存储选型) │ │ │ └── utils.ts # 靶向渲染与 GitHub 下载引擎 │ │ └── package.json │ └── template/ # 旗舰 NestJS 项目模板 (独立工程) ``` ### 2. 生成后的 NestJS 企业项目目录 ``` my-project/ ├── prisma/ │ ├── schema.prisma # 核心数据模型 (User, Role, Menu, Dept, Dict, Log 等) │ └── seed.ts # 基础数据种子填充 (超级管理员、初始角色、核心菜单) ├── src/ │ ├── common/ # 系统公共核心模块 │ │ ├── decorators/ # 常用装饰器 (如 @Log, @RequiresPermissions, @CurrentUser) │ │ ├── dto/ # 统一分页 DTO 封装 (PageDto, PageOptionsDto) │ │ ├── exceptions/ # 统一业务异常类 (BusinessException) │ │ ├── filters/ # 全局异常过滤器 (AllExceptionsFilter) │ │ ├── guards/ # 鉴权守卫 (JwtAuthGuard, PermissionGuard) │ │ ├── interceptors/ # 全局拦截器 (TransformInterceptor, LogInterceptor) │ │ └── storage/ # 策略模式多云文件存储 (Minio, AliOSS, HWOBS) │ ├── modules/ # 核心业务模块 │ │ ├── auth/ # 认证中心 (JWT 登录与资料获取) │ │ ├── user/ # 用户管理 (分页查询与权限应用) │ │ ├── upload/ # 文件上传路由 │ │ └── log/ # 异步操作日志消费 (BullMQ) │ ├── app.module.ts # 全局依赖编排 (Pino, BullMQ 队列初始化) │ └── main.ts # 项目启动入口 (Pino 接管、Swagger 配置、管道挂载) ├── biome.json # Biome 审查与格式化配置文件 (代替 ESLint/Prettier) ├── Dockerfile # Node 24 LTS 多阶段构建 Dockerfile ├── docker-compose.yml # MySQL 8.4 LTS + Redis 8 + Minio 容器编排 ├── prisma.config.ts # Prisma 7.x 连接配置文件 └── package.json # 动态渲染后的项目依赖 ``` --- ## 🛠️ 项目使用步骤 以下为从零创建、运行直至调试一个全新 NestJS 企业项目的完整实操步骤。 ### 第一步：一键运行脚手架创建项目 在全球任意空目录下执行以下命令（脚手架在运行时会自动查询并抓取最新的 NestJS 与 Prisma 7.x 稳定版本注入项目）： ```bash npx create-nest-enterprise my-project ``` 启动后会进入交互问答，您可以直接使用回车确认默认参数，或输入您本地的 MySQL/Redis 凭证及默认存储选型（Minio/阿里云 OSS/华为云 OBS）。 > [!TIP] > **Minio 服务自动连接与建桶机制**： > - 如果您在存储选型中选择了 **Minio**，脚手架会进一步提示您输入 Minio API 端点（例如 `http://127.0.0.1:9000`）、Access Key、Secret Key 以及桶（Bucket）名称。 > - 输入后，脚手架将**自动尝试连接**该 Minio 服务。若连接成功，会直接在您的 Minio 实例中为您创建好指定的桶，实现开箱即用。 > - 若因服务未启动等原因导致连接失败，脚手架会进行优雅的容错处理，在项目创建完毕的最后给出显眼的警告和详细的排查提示，而**不会阻断**项目模板的生成，您可以选择后续在 Docker 环境启动后自行处理。 ### 第二步：拉起基础设施容器 (Docker) 进入新生成的项目目录，如果您本地安装了 Docker Desktop，可以直接一键拉起集成了 MySQL 8.4 LTS、Redis 8 与 Minio 的容器环境： ```bash cd my-project docker compose up -d ``` ### 第三步：数据库初始化与数据填充 项目启动前，我们需要完成物理数据表结构的创建与超级管理员等系统种子数据的填充： 1. **同步表结构**：Prisma 会自动读取根目录下的 `prisma.config.ts` 连接串并向 MySQL 创建全部系统表： ```bash npx prisma db push ``` 2. **导入种子基础数据**：向数据库填充默认的部门架构、初始菜单及默认超级管理员账号（用户名 `admin`，密码 `123456`）： ```bash npx prisma db seed ``` ### 第四步：启动 NestJS 应用程序 在项目根目录下，使用您的包管理器启动本地热更新开发服务器： ```bash npm run dev # 或者 pnpm dev # 或者 yarn dev ``` 启动成功后，控制台会输出 Pino 引擎接管的结构化启动日志，并在端口 `3000` 顺利跑通。 --- ## 📖 核心功能调试与使用文档 ### 1. Swagger 统一接口调试文档 我们已经在主入口中深度集成了 Swagger 文档并开启了 JWT 持久化授权支持： - **访问入口**：在浏览器中打开 [http://localhost:3000/api](http://localhost:3000/api)。 - **JWT 接口授权联调**： 1. 在 Swagger 页面中，找到 `系统认证管理 -> /auth/login` 端点，点击 **Try it out**。 2. 输入内置的 `admin` 及 `123456`，发送 POST 请求，获取响应体里的 `accessToken`。 3. 点击 Swagger 页面右上角的 **Authorize** 按钮，在输入框中填入 `Bearer <您的accessToken>`，点击 Authorize 确认。 4. 此时，所有被 `@ApiBearerAuth('JWT')` 装饰器限制的接口（如用户列表、文件上传等）均可正常通过网关校验。页面即使刷新也无需重复输入，极大地方便了前后端联调。 ### 2. Prisma Studio 可视化数据后台 我们配置了 Prisma 官方的可视化数据库管理工具： - **一键启动**：在项目根目录下执行 `npm run prisma:studio` (或 `pnpm prisma:studio`)。 - **管理数据**：在浏览器中访问 [http://localhost:5555](http://localhost:5555)，即可直接以图形化网格界面对用户表、角色表、字典及系统日志表进行直接的增删改查及数据过滤。 ### 3. Biome 一键格式化与静态检查 项目全面弃用了传统的 ESLint + Prettier 方案，采用集成了 Format、Lint、Import Sort 三合一的高性能 **Biome** 工具链： - **格式化代码**：执行 `npm run format` 自动格式化 `src` 下所有 TypeScript 文件。 - **语法检查**：执行 `npm run lint` 进行超高性能的语法审查。 - 此外，项目内置了 **Husky** Git 提交流水线，当执行 `git commit` 时会自动触发 Biome 对暂存区代码的安全扫视，保障团队代码规范的绝对统一。 --- ## 💡 内置高阶机制与架构原理解析 ### 1. Prisma 7.x 强制 Adapter (MariaDB/MySQL) 驱动池解耦 Prisma 7 彻底移除了 Rust 底层查询引擎，对于直连本地物理数据库强制要求采用适配器（Driver Adapter）模式。 为此，我们在 [prisma.service.ts](file:///Users/wuhao/Desktop/work/nest-enterprise/packages/template/src/modules/prisma/prisma.service.ts) 中进行了如下重构： - 使用 **`@prisma/adapter-mariadb`**（Prisma 7 对 MySQL/MariaDB 的官方通用驱动）作为底层连接媒介。 - 引入 `URL` 对象在 `PrismaService` 构造函数中动态解密并拆分 `DATABASE_URL`，自动组装连接参数实例化 `PrismaMariaDb` 适配器传给 `super({ adapter })`，这彻底消除了本地未配置数据库时编译崩溃的问题。 ### 2. 纯 JavaScript 原生加密 (bcryptjs) 项目淘汰了容易产生 C++ 原生 Native 模块编译崩溃的 `bcrypt`，改用 100% 纯 JavaScript 实现的 `bcryptjs`。这确保了生成的项目在 macOS、Windows、Linux、Alpine Docker 镜像等各个环境下均可一键通过安装，无需依赖本地 node-gyp 编译。 ### 3. BullMQ + Redis 8 的异步日志拦截设计 高并发接口如果直接阻塞写入数据库，会导致接口响应变慢并增加数据库 I/O 负担。我们采用 **BullMQ** 对日志进行异步落库： - 开发者只需在控制器方法上挂载自定义的 `@Log({ module: '用户管理', action: '查询列表' })` 装饰器。 - 全局的 [LogInterceptor](file:///Users/wuhao/Desktop/work/nest-enterprise/packages/template/src/common/interceptors/log.interceptor.ts) 会自动捕获用户的请求/响应数据及接口耗时，在不阻塞主线程接口响应的前提下，向 BullMQ 异步投递任务。 - 由独立的 [LogProcessor](file:///Users/wuhao/Desktop/work/nest-enterprise/packages/template/src/modules/log/log.processor.ts) 从 Redis 8 队列中取出任务，并在后台批量写入 MySQL 操作日志表。 ### 4. 细粒度 RBAC 权限鉴定设计 基于 `Prisma` 数据表关联实现： - 控制器或路由端点上，可以通过 `@RequiresPermissions('system:user:query')` 声明访问所需的权限字段。 - [PermissionGuard](file:///Users/wuhao/Desktop/work/nest-enterprise/packages/template/src/common/guards/permission.guard.ts) 守卫会利用 Reflector 反射获取元数据，比对当前从 JWT 解密解析出该用户所关联角色的全部菜单权限，实行细粒度的按钮级/接口级拦截。 - **超级管理员放行**：如果当前用户的角色 code 包含 `'admin'`，则自动绕过校验，免去重复配置的痛苦。 ### 5. 策略模式多云文件存储与 Minio 自动生命周期初始化 在 [src/common/storage/](file:///Users/wuhao/Desktop/work/nest-enterprise/packages/template/src/common/storage) 目录下设计了统一的存储策略： - 定义了统一的接口行为 `StorageStrategy`。 - 实现了 `MinioStorageStrategy`、`AliOssStorageStrategy` 和 `HwObsStorageStrategy` 三个具体云存储服务类. - [StorageFactory](file:///Users/wuhao/Desktop/work/nest-enterprise/packages/template/src/common/storage/storage.factory.ts) 动态工厂会在运行时读取 `.env` 中的 `STORAGE_TYPE`。切换存储只需更改配置文件中的存储类型及对应的 AK/SK 即可，业务层控制器完全不需要发生任何代码修改，极佳地践行了面向接口设计的开闭原则。 - **开箱即用建桶**：脚手架 CLI 支持在项目初始化期间与用户的 Minio 服务（不论是本地 Docker Compose 跑的还是已存在的外部 Minio 服务）直接连接测试，自动创建并配置对应的存储桶，彻底摆脱了手动登录 Web Console 的繁琐步骤。