nestjs
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseNestJS Framework Skill
NestJS框架技能
Master NestJS for building scalable, maintainable Node.js applications with TypeScript, dependency injection, and enterprise patterns.
掌握NestJS,使用TypeScript、依赖注入和企业级模式构建可扩展、可维护的Node.js应用。
Quick Start
快速开始
NestJS app in 4 steps:
- Create Project -
nest new project-name - Define Modules - Organize features
- Add Controllers - Handle requests
- Create Services - Business logic
4步搭建NestJS应用:
- 创建项目 -
nest new project-name - 定义模块 - 组织功能模块
- 添加控制器 - 处理请求
- 创建服务 - 实现业务逻辑
Core Concepts
核心概念
Module Structure
模块结构
typescript
// users/users.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './entities/user.entity';
@Module({
imports: [TypeOrmModule.forFeature([User])],
controllers: [UsersController],
providers: [UsersService],
exports: [UsersService] // Make available to other modules
})
export class UsersModule {}typescript
// users/users.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';
import { TypeOrmModule } from '@nestjs/typeorm';
import { User } from './entities/user.entity';
@Module({
imports: [TypeOrmModule.forFeature([User])],
controllers: [UsersController],
providers: [UsersService],
exports: [UsersService] // 提供给其他模块使用
})
export class UsersModule {}Controller
控制器
typescript
// users/users.controller.ts
import { Controller, Get, Post, Body, Param, Query, UseGuards } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';
import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
@ApiTags('users')
@Controller('users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Get()
@ApiOperation({ summary: 'Get all users' })
findAll(@Query('page') page = 1, @Query('limit') limit = 10) {
return this.usersService.findAll(page, limit);
}
@Get(':id')
findOne(@Param('id') id: string) {
return this.usersService.findOne(id);
}
@Post()
@UseGuards(JwtAuthGuard)
@ApiBearerAuth()
create(@Body() createUserDto: CreateUserDto) {
return this.usersService.create(createUserDto);
}
}typescript
// users/users.controller.ts
import { Controller, Get, Post, Body, Param, Query, UseGuards } from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';
import { JwtAuthGuard } from '../auth/guards/jwt-auth.guard';
import { ApiTags, ApiOperation, ApiBearerAuth } from '@nestjs/swagger';
@ApiTags('users')
@Controller('users')
export class UsersController {
constructor(private readonly usersService: UsersService) {}
@Get()
@ApiOperation({ summary: '获取所有用户' })
findAll(@Query('page') page = 1, @Query('limit') limit = 10) {
return this.usersService.findAll(page, limit);
}
@Get(':id')
findOne(@Param('id') id: string) {
return this.usersService.findOne(id);
}
@Post()
@UseGuards(JwtAuthGuard)
@ApiBearerAuth()
create(@Body() createUserDto: CreateUserDto) {
return this.usersService.create(createUserDto);
}
}Service with Dependency Injection
依赖注入服务
typescript
// users/users.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User } from './entities/user.entity';
@Injectable()
export class UsersService {
constructor(
@InjectRepository(User)
private usersRepository: Repository<User>
) {}
async findAll(page: number, limit: number) {
const [users, total] = await this.usersRepository.findAndCount({
skip: (page - 1) * limit,
take: limit
});
return { data: users, total, page, limit };
}
async findOne(id: string): Promise<User> {
const user = await this.usersRepository.findOne({ where: { id } });
if (!user) {
throw new NotFoundException(`User #${id} not found`);
}
return user;
}
async create(createUserDto: CreateUserDto): Promise<User> {
const user = this.usersRepository.create(createUserDto);
return this.usersRepository.save(user);
}
}typescript
// users/users.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { User } from './entities/user.entity';
@Injectable()
export class UsersService {
constructor(
@InjectRepository(User)
private usersRepository: Repository<User>
) {}
async findAll(page: number, limit: number) {
const [users, total] = await this.usersRepository.findAndCount({
skip: (page - 1) * limit,
take: limit
});
return { data: users, total, page, limit };
}
async findOne(id: string): Promise<User> {
const user = await this.usersRepository.findOne({ where: { id } });
if (!user) {
throw new NotFoundException(`用户 #${id} 不存在`);
}
return user;
}
async create(createUserDto: CreateUserDto): Promise<User> {
const user = this.usersRepository.create(createUserDto);
return this.usersRepository.save(user);
}
}Learning Path
学习路径
Beginner (2-3 weeks)
入门阶段(2-3周)
- ✅ NestJS CLI and project structure
- ✅ Modules, Controllers, Services
- ✅ Dependency injection basics
- ✅ Basic CRUD operations
- ✅ NestJS CLI与项目结构
- ✅ 模块、控制器、服务
- ✅ 依赖注入基础
- ✅ 基础CRUD操作
Intermediate (4-6 weeks)
进阶阶段(4-6周)
- ✅ Guards, Pipes, Interceptors
- ✅ TypeORM/Prisma integration
- ✅ JWT authentication
- ✅ Validation with class-validator
- ✅ 守卫、管道、拦截器
- ✅ TypeORM/Prisma集成
- ✅ JWT身份认证
- ✅ 使用class-validator进行验证
Advanced (8-12 weeks)
高级阶段(8-12周)
- ✅ Microservices with transports
- ✅ GraphQL with NestJS
- ✅ WebSockets (Gateways)
- ✅ Testing strategies
- ✅ 基于传输层的微服务
- ✅ NestJS集成GraphQL
- ✅ WebSockets(网关)
- ✅ 测试策略
Validation with DTOs
基于DTO的验证
typescript
// dto/create-user.dto.ts
import { IsEmail, IsString, MinLength, IsOptional } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';
export class CreateUserDto {
@ApiProperty({ example: 'john@example.com' })
@IsEmail()
email: string;
@ApiProperty({ example: 'John Doe' })
@IsString()
@MinLength(2)
name: string;
@ApiProperty({ example: 'password123' })
@IsString()
@MinLength(8)
password: string;
@ApiProperty({ required: false })
@IsOptional()
@IsString()
avatar?: string;
}typescript
// dto/create-user.dto.ts
import { IsEmail, IsString, MinLength, IsOptional } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';
export class CreateUserDto {
@ApiProperty({ example: 'john@example.com' })
@IsEmail()
email: string;
@ApiProperty({ example: 'John Doe' })
@IsString()
@MinLength(2)
name: string;
@ApiProperty({ example: 'password123' })
@IsString()
@MinLength(8)
password: string;
@ApiProperty({ required: false })
@IsOptional()
@IsString()
avatar?: string;
}Guards for Authentication
身份认证守卫
typescript
// auth/guards/jwt-auth.guard.ts
import { Injectable, ExecutionContext } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
canActivate(context: ExecutionContext) {
return super.canActivate(context);
}
}
// auth/guards/roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
const requiredRoles = this.reflector.get<string[]>('roles', context.getHandler());
if (!requiredRoles) return true;
const { user } = context.switchToHttp().getRequest();
return requiredRoles.some(role => user.roles?.includes(role));
}
}typescript
// auth/guards/jwt-auth.guard.ts
import { Injectable, ExecutionContext } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
@Injectable()
export class JwtAuthGuard extends AuthGuard('jwt') {
canActivate(context: ExecutionContext) {
return super.canActivate(context);
}
}
// auth/guards/roles.guard.ts
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
const requiredRoles = this.reflector.get<string[]>('roles', context.getHandler());
if (!requiredRoles) return true;
const { user } = context.switchToHttp().getRequest();
return requiredRoles.some(role => user.roles?.includes(role));
}
}Exception Filters
异常过滤器
typescript
// filters/http-exception.filter.ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { Response } from 'express';
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
catch(exception: HttpException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse<Response>();
const status = exception.getStatus();
response.status(status).json({
success: false,
statusCode: status,
message: exception.message,
timestamp: new Date().toISOString()
});
}
}typescript
// filters/http-exception.filter.ts
import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from '@nestjs/common';
import { Response } from 'express';
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
catch(exception: HttpException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse<Response>();
const status = exception.getStatus();
response.status(status).json({
success: false,
statusCode: status,
message: exception.message,
timestamp: new Date().toISOString()
});
}
}Microservices Transport
微服务传输层
typescript
// main.ts for microservice
import { NestFactory } from '@nestjs/core';
import { Transport, MicroserviceOptions } from '@nestjs/microservices';
const app = await NestFactory.createMicroservice<MicroserviceOptions>(
AppModule,
{
transport: Transport.RMQ,
options: {
urls: ['amqp://localhost:5672'],
queue: 'orders_queue',
queueOptions: { durable: true }
}
}
);
await app.listen();typescript
// 微服务版本main.ts
import { NestFactory } from '@nestjs/core';
import { Transport, MicroserviceOptions } from '@nestjs/microservices';
const app = await NestFactory.createMicroservice<MicroserviceOptions>(
AppModule,
{
transport: Transport.RMQ,
options: {
urls: ['amqp://localhost:5672'],
queue: 'orders_queue',
queueOptions: { durable: true }
}
}
);
await app.listen();Unit Test Template
单元测试模板
typescript
describe('UsersService', () => {
let service: UsersService;
let repository: Repository<User>;
beforeEach(async () => {
const module = await Test.createTestingModule({
providers: [
UsersService,
{
provide: getRepositoryToken(User),
useValue: {
findOne: jest.fn(),
create: jest.fn(),
save: jest.fn()
}
}
]
}).compile();
service = module.get<UsersService>(UsersService);
repository = module.get<Repository<User>>(getRepositoryToken(User));
});
it('should find user by id', async () => {
const user = { id: '1', name: 'John' };
jest.spyOn(repository, 'findOne').mockResolvedValue(user as User);
expect(await service.findOne('1')).toEqual(user);
});
});typescript
describe('UsersService', () => {
let service: UsersService;
let repository: Repository<User>;
beforeEach(async () => {
const module = await Test.createTestingModule({
providers: [
UsersService,
{
provide: getRepositoryToken(User),
useValue: {
findOne: jest.fn(),
create: jest.fn(),
save: jest.fn()
}
}
]
}).compile();
service = module.get<UsersService>(UsersService);
repository = module.get<Repository<User>>(getRepositoryToken(User));
});
it('should find user by id', async () => {
const user = { id: '1', name: 'John' };
jest.spyOn(repository, 'findOne').mockResolvedValue(user as User);
expect(await service.findOne('1')).toEqual(user);
});
});Troubleshooting
故障排查
| Problem | Cause | Solution |
|---|---|---|
| Circular dependency | Module imports | Use forwardRef() |
| Injection token not found | Missing provider | Add to module providers |
| Validation not working | Missing pipe | Add ValidationPipe globally |
| Guards not firing | Wrong order | Use @UseGuards correctly |
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 循环依赖 | 模块导入问题 | 使用forwardRef() |
| 注入令牌未找到 | 缺少提供者 | 添加到模块providers中 |
| 验证不生效 | 缺少管道 | 全局添加ValidationPipe |
| 守卫未触发 | 装饰器顺序错误 | 正确使用@UseGuards |
When to Use
适用场景
Use NestJS when:
- Building enterprise Node.js applications
- Need TypeScript with strong typing
- Want dependency injection
- Building microservices
- Need OpenAPI documentation
在以下场景使用NestJS:
- 构建企业级Node.js应用
- 需要强类型的TypeScript开发环境
- 希望使用依赖注入模式
- 构建微服务系统
- 需要生成OpenAPI文档
Related Skills
相关技能
- Express REST API (underlying framework)
- TypeScript (language)
- GraphQL (alternative to REST)
- Microservices (distributed systems)
- Express REST API(底层框架)
- TypeScript(开发语言)
- GraphQL(REST替代方案)
- 微服务(分布式系统)