3. NestJS CLI 初始化：项目创建与核心文件职责

在 API Design 驱动的事务边界治理体系中，项目初始化是奠定架构规范的第一步。使用 @nestjs/cli 创建的项目骨架，天然提供了模块化、依赖注入和装饰器支持，这些特性正是后续实现声明式事务边界的基础设施。本节将带你完成 CLI 初始化、解析目录结构，并深入理解 main.ts 与 app.module 的核心职责。

3.1 使用 @nestjs/cli 创建项目

确保已全局安装 NestJS CLI：

npm install -g @nestjs/cli

创建新项目：

nest new transaction-boundary-api

CLI 会提示选择包管理器（npm / yarn / pnpm），建议选择 npm 以保持与后续课程示例一致。创建完成后，进入项目目录：

cd transaction-boundary-api

启动开发服务器验证安装：

npm run start:dev

访问 http://localhost:3000，应看到 Hello World! 响应。

3.2 项目目录结构解析

初始化后的项目目录结构如下，每一层都有明确的架构职责：

transaction-boundary-api/
├── src/                          # 应用源代码
│   ├── app.controller.spec.ts    # 控制器单元测试
│   ├── app.controller.ts         # 根控制器
│   ├── app.module.ts             # 根模块（核心配置入口）
│   ├── app.service.ts            # 根服务
│   └── main.ts                   # 应用入口（启动引导）
├── test/                         # e2e 测试
│   ├── app.e2e-spec.ts
│   └── jest-e2e.json
├── node_modules/                 # 依赖包
├── .eslintrc.js                  # ESLint 配置
├── .prettierrc                   # Prettier 配置
├── nest-cli.json                 # NestJS CLI 构建配置
├── package.json                  # 项目元数据与脚本
├── tsconfig.build.json           # 构建用 TypeScript 配置
├── tsconfig.json                 # 开发用 TypeScript 配置
└── README.md

下表总结了关键目录与文件的职责：

路径	职责	与事务边界治理的关系
src/	应用源代码根目录	所有业务模块、过滤器、拦截器均在此组织
src/main.ts	应用启动入口，创建 Nest 应用实例	在此注册全局管道、过滤器、拦截器，是事务边界治理的第一道防线
src/app.module	根模块，声明全局依赖与模块导入	在此导入数据库模块、全局中间件，定义事务作用域
src/app.controller	根路由控制器	演示用，后续会被业务控制器替代
src/app.service	根业务逻辑服务	演示用，后续会被业务服务替代
test/	端到端测试	用于验证事务回滚与提交的集成测试
nest-cli.json	CLI 构建与编译配置	可配置 entryFile、watchAssets 等

3.3 核心文件职责：main.ts

main.ts 是 NestJS 应用的启动引导文件，其核心职责包括：

• 创建 Nest 应用实例：使用 NestFactory.create() 启动应用。
• 注册全局基础设施：如全局验证管道（ValidationPipe）、全局异常过滤器、全局拦截器。
• 配置监听端口与 CORS：设置服务端口、跨域策略。
• 启用 Swagger / 其他插件：为 API 文档做准备。

默认生成的 main.ts：

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

在事务边界治理场景中，我们将在 main.ts 中注册全局的 事务拦截器 和 异常过滤器，确保所有请求进入统一的数据库会话管理流程。

3.4 核心文件职责：app.module

app.module 是根模块，使用 @Module() 装饰器声明应用的全局依赖关系。其核心职责包括：

• 导入功能模块：如数据库模块（TypeORM / Prisma）、配置模块（ConfigModule）。
• 注册全局控制器与服务：根控制器与根服务。
• 声明全局提供者：如全局守卫、全局拦截器（若不在 main.ts 注册）。
• 导出共享模块：使其他模块可以复用数据库连接等。

默认生成的 app.module.ts：

import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

在后续课程中，我们将在 imports 中添加 TypeOrmModule.forRoot() 或 PrismaModule，并在 providers 中注册全局事务拦截器，从而将事务边界治理能力注入整个应用。

3.5 核心文件协作关系

下图展示了 main.ts、app.module 与业务模块之间的启动与依赖关系：

3.6 初始化后的验证清单

完成 CLI 初始化后，建议执行以下验证步骤，确保环境就绪：

步骤	命令 / 操作	预期结果
1. 启动开发服务器	npm run start:dev	控制台输出 Nest application successfully started
2. 测试根路由	curl http://localhost:3000	返回 Hello World!
3. 运行单元测试	npm run test	所有测试通过
4. 检查 TypeScript 编译	npm run build	生成 dist/ 目录，无编译错误

3.7 本章小结