快速配置记录 NestJS 项目的初始化、依赖注入、控制器、DTO、数据校验与 API 文档配置。初始化项目nest new first-app-g-s生成项目架构图使用madge分析模块依赖并生成架构图。安装npminstall-gmadge生成图片madge--imagegraph.svg ./src/main.ts依赖注入依赖关系在未使用依赖注入时UserController会自行创建UserService实例classUserService{findUser(){return查询用户;}}classUserController{privateuserService:UserService;constructor(){this.userServicenewUserService();}getUser(){returnthis.userService.findUser();}}UserController │ │ 依赖 ▼ UserService控制反转IoC传统方式由Controller主动创建ServiceController │ │ 创建 ▼ Service使用 IoC 后由容器负责管理和提供依赖IoC 容器 │ │ 注入 ▼ Controller ◀── ServiceNestJS 中的依赖注入提示依赖注入的核心是IoC 容器。它负责管理类的生命周期和依赖关系。Serviceimport{Injectable}fromnestjs/common;Injectable()// 表示该类可以由 IoC 容器管理exportclassUserService{findUser(){return用户数据;}}Controllerimport{Controller,Get}fromnestjs/common;import{UserService}from./user.service;Controller(users)exportclassUserController{constructor(privatereadonlyuserService:UserService){}Get()getUser(){returnthis.userService.findUser();}}提示可在dist目录查看编译后的 JavaScript 文件了解依赖注入的实现方式。Controller生成 Controllernest g controller todo --no-specCRUD 示例Controller(todo)exportclassTodoController{constructor(privatereadonlytodoService:TodoService){}Get()findAll(){returnthis.todoService.findAllTodos();}Get(:id)findOne(Param(id)id:string){returnthis.todoService.findOneTodo(Number(id));}Post()create(Body()newTodo:any){returnthis.todoService.createTodo(newTodo);}Patch(:id)update(Param(id)id:string,Body()updateTodoBody:any){returnthis.todoService.updateTodo(Number(id),updateTodoBody);}Delete(:id)deleteTodo(Param(id)id:string,Res({passthrough:true})res:Response,){constresultthis.todoService.deleteTodo(Number(id));if(result){return{message:Todo deleted successfully,};}returnres.status(HttpStatus.BAD_REQUEST).json({message:bad request,});}}提示Res({ passthrough: true })表示 NestJS 仍会自动将返回值转换为 JSON因此不需要手动调用res.json()。DTO 与 Entity推荐使用class定义 DTOexportclassCreateTodoDto{title:string;content:string;isCompleted:boolean;}PartialType可基于已有类型创建新类型并将原类型的所有属性改为可选import{PartialType}fromnestjs/mapped-types;exportclassUpdateTodoDtoextendsPartialType(CreateTodoDto){}Pipe参数校验与转换安装依赖pnpmaddclass-validator class-transformer配置全局验证管道在main.ts中添加import{ValidationPipe}fromnestjs/common;import{NestFactory}fromnestjs/core;import{AppModule}from./app.module;asyncfunctionbootstrap(){constappawaitNestFactory.create(AppModule);app.useGlobalPipes(newValidationPipe({transform:true,// 自动转换类型例如将 params 中的 string ID 转为 numberwhitelist:true,// 自动移除 DTO 未声明的属性forbidNonWhitelisted:true,// 请求体含有未声明属性时抛出异常}),);awaitapp.listen(3000);}bootstrap();为 DTO 添加验证装饰器// 这里只列出部分常用校验器import{IsBoolean,IsNotEmpty,IsString}fromclass-validator;exportclassCreateTodoDto{IsNotEmpty()IsString()title!:string;IsNotEmpty()IsString()content!:string;IsNotEmpty()IsBoolean()isCompleted!:boolean;}提示NestJS CLI 可使用以下命令生成 CRUD 资源模板nest g resourceAPI 文档Swagger安装依赖pnpmaddnestjs/swagger配置 Swagger在main.ts中添加 Swagger 配置import{DocumentBuilder,SwaggerModule}fromnestjs/swagger;constconfignewDocumentBuilder().setTitle(Todos example).setDescription(The todo API description).setVersion(1.0).addServer(http://localhost:3000,localhost).addTag(todos).build();constdocumentFactory()SwaggerModule.createDocument(app,config);SwaggerModule.setup(api,app,documentFactory,{jsonDocumentUrl:swagger/json,});配置 Swagger CLI 插件在nest-cli.json中添加{$schema:https://json.schemastore.org/nest-cli,collection:nestjs/schematics,sourceRoot:src,compilerOptions:{deleteOutDir:true,plugins:[nestjs/swagger]}}提示访问http://localhost:3000/api查看 Swagger 文档。访问http://localhost:3000/swagger/json查看 Swagger 的 JSON 文档。使用PartialType时应从nestjs/swagger导入。提高编译速度SWC安装依赖pnpmaddswc/cli swc/core-D配置 SWC在nest-cli.json中添加{compilerOptions:{builder:swc,typeCheck:true}}兼容 Swagger在main.ts中导入新增的元数据文件importmetadatafrom./metadata;awaitSwaggerModule.loadPluginMetadata(metadata);注意不推荐同时使用 SWC 构建器与 Swagger CLI 插件。
快速配置记录 NestJS 项目的初始化、依赖注入、控制器、DTO、数据校验与 API 文档配置。初始化项目nest new first-app-g-s生成项目架构图使用madge分析模块依赖并生成架构图。安装npminstall-gmadge生成图片madge--imagegraph.svg ./src/main.ts依赖注入依赖关系在未使用依赖注入时UserController会自行创建UserService实例classUserService{findUser(){return查询用户;}}classUserController{privateuserService:UserService;constructor(){this.userServicenewUserService();}getUser(){returnthis.userService.findUser();}}UserController │ │ 依赖 ▼ UserService控制反转IoC传统方式由Controller主动创建ServiceController │ │ 创建 ▼ Service使用 IoC 后由容器负责管理和提供依赖IoC 容器 │ │ 注入 ▼ Controller ◀── ServiceNestJS 中的依赖注入提示依赖注入的核心是IoC 容器。它负责管理类的生命周期和依赖关系。Serviceimport{Injectable}fromnestjs/common;Injectable()// 表示该类可以由 IoC 容器管理exportclassUserService{findUser(){return用户数据;}}Controllerimport{Controller,Get}fromnestjs/common;import{UserService}from./user.service;Controller(users)exportclassUserController{constructor(privatereadonlyuserService:UserService){}Get()getUser(){returnthis.userService.findUser();}}提示可在dist目录查看编译后的 JavaScript 文件了解依赖注入的实现方式。Controller生成 Controllernest g controller todo --no-specCRUD 示例Controller(todo)exportclassTodoController{constructor(privatereadonlytodoService:TodoService){}Get()findAll(){returnthis.todoService.findAllTodos();}Get(:id)findOne(Param(id)id:string){returnthis.todoService.findOneTodo(Number(id));}Post()create(Body()newTodo:any){returnthis.todoService.createTodo(newTodo);}Patch(:id)update(Param(id)id:string,Body()updateTodoBody:any){returnthis.todoService.updateTodo(Number(id),updateTodoBody);}Delete(:id)deleteTodo(Param(id)id:string,Res({passthrough:true})res:Response,){constresultthis.todoService.deleteTodo(Number(id));if(result){return{message:Todo deleted successfully,};}returnres.status(HttpStatus.BAD_REQUEST).json({message:bad request,});}}提示Res({ passthrough: true })表示 NestJS 仍会自动将返回值转换为 JSON因此不需要手动调用res.json()。DTO 与 Entity推荐使用class定义 DTOexportclassCreateTodoDto{title:string;content:string;isCompleted:boolean;}PartialType可基于已有类型创建新类型并将原类型的所有属性改为可选import{PartialType}fromnestjs/mapped-types;exportclassUpdateTodoDtoextendsPartialType(CreateTodoDto){}Pipe参数校验与转换安装依赖pnpmaddclass-validator class-transformer配置全局验证管道在main.ts中添加import{ValidationPipe}fromnestjs/common;import{NestFactory}fromnestjs/core;import{AppModule}from./app.module;asyncfunctionbootstrap(){constappawaitNestFactory.create(AppModule);app.useGlobalPipes(newValidationPipe({transform:true,// 自动转换类型例如将 params 中的 string ID 转为 numberwhitelist:true,// 自动移除 DTO 未声明的属性forbidNonWhitelisted:true,// 请求体含有未声明属性时抛出异常}),);awaitapp.listen(3000);}bootstrap();为 DTO 添加验证装饰器// 这里只列出部分常用校验器import{IsBoolean,IsNotEmpty,IsString}fromclass-validator;exportclassCreateTodoDto{IsNotEmpty()IsString()title!:string;IsNotEmpty()IsString()content!:string;IsNotEmpty()IsBoolean()isCompleted!:boolean;}提示NestJS CLI 可使用以下命令生成 CRUD 资源模板nest g resourceAPI 文档Swagger安装依赖pnpmaddnestjs/swagger配置 Swagger在main.ts中添加 Swagger 配置import{DocumentBuilder,SwaggerModule}fromnestjs/swagger;constconfignewDocumentBuilder().setTitle(Todos example).setDescription(The todo API description).setVersion(1.0).addServer(http://localhost:3000,localhost).addTag(todos).build();constdocumentFactory()SwaggerModule.createDocument(app,config);SwaggerModule.setup(api,app,documentFactory,{jsonDocumentUrl:swagger/json,});配置 Swagger CLI 插件在nest-cli.json中添加{$schema:https://json.schemastore.org/nest-cli,collection:nestjs/schematics,sourceRoot:src,compilerOptions:{deleteOutDir:true,plugins:[nestjs/swagger]}}提示访问http://localhost:3000/api查看 Swagger 文档。访问http://localhost:3000/swagger/json查看 Swagger 的 JSON 文档。使用PartialType时应从nestjs/swagger导入。提高编译速度SWC安装依赖pnpmaddswc/cli swc/core-D配置 SWC在nest-cli.json中添加{compilerOptions:{builder:swc,typeCheck:true}}兼容 Swagger在main.ts中导入新增的元数据文件importmetadatafrom./metadata;awaitSwaggerModule.loadPluginMetadata(metadata);注意不推荐同时使用 SWC 构建器与 Swagger CLI 插件。
