← 返回笔记列表
·11 分钟阅读
NestJS 学习笔记
NestJS 核心概念、模块结构与常用开发模式的个人学习记录。
- NestJS
- Node.js
- 后端
NestJS 学习笔记
概述
NestJS 是基于 Node.js 的企业级后端框架,采用 TypeScript,架构风格接近 Angular。最近用它写了几个项目,感觉代码组织非常清晰,尤其是依赖注入和模块化的设计,让大型项目的维护变得轻松很多。
为什么选择 NestJS
- 模块化架构:按功能拆分 Module,结构清晰,便于维护
- 依赖注入(DI):便于测试与解耦,代码更易复用
- 装饰器驱动:路由、守卫、拦截器写法统一,开发体验好
- 生态完善:支持 TypeORM、Prisma、Swagger、JWT 等主流库
- TypeScript:类型安全,开发时就能发现很多问题
- CLI 工具:快速生成代码骨架,提高开发效率
核心概念
Module
应用的基本组织单元,一个功能通常对应一个 Module。
import { Module } from '@nestjs/common';
import { CatsController } from './cats.controller';
import { CatsService } from './cats.service';
import { DatabaseModule } from '../database/database.module';
@Module({
imports: [DatabaseModule],
controllers: [CatsController],
providers: [CatsService],
exports: [CatsService],
})
export class CatsModule {}
模块组成:
imports:导入其他模块controllers:定义控制器providers:定义服务(可注入的依赖)exports:导出服务供其他模块使用
Controller
负责处理 HTTP 请求,定义路由。
import { Controller, Get, Post, Body, Param, Patch, Delete, Query } from '@nestjs/common';
@Controller('cats')
export class CatsController {
constructor(private readonly catsService: CatsService) {}
@Get()
findAll(@Query('page') page: number = 1, @Query('limit') limit: number = 10) {
return this.catsService.findAll(page, limit);
}
@Get(':id')
findOne(@Param('id') id: string) {
return this.catsService.findOne(id);
}
@Post()
create(@Body() createCatDto: CreateCatDto) {
return this.catsService.create(createCatDto);
}
@Patch(':id')
update(@Param('id') id: string, @Body() updateCatDto: UpdateCatDto) {
return this.catsService.update(id, updateCatDto);
}
@Delete(':id')
remove(@Param('id') id: string) {
return this.catsService.remove(id);
}
}
常用装饰器:
@Get()、@Post()、@Put()、@Patch()、@Delete():HTTP 方法@Param():路径参数@Query():查询参数@Body():请求体@Headers():请求头@Session():会话对象
Provider / Service
承载业务逻辑,通过构造函数注入到 Controller。
import { Injectable } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
import { CreateCatDto, UpdateCatDto } from './dto';
@Injectable()
export class CatsService {
constructor(private readonly prisma: PrismaService) {}
async findAll(page: number, limit: number) {
const skip = (page - 1) * limit;
const [data, total] = await Promise.all([
this.prisma.cat.findMany({ skip, take: limit }),
this.prisma.cat.count(),
]);
return { data, total, page, limit };
}
async findOne(id: string) {
const cat = await this.prisma.cat.findUnique({ where: { id } });
if (!cat) {
throw new NotFoundException(`Cat with id ${id} not found`);
}
return cat;
}
async create(dto: CreateCatDto) {
return this.prisma.cat.create({ data: dto });
}
async update(id: string, dto: UpdateCatDto) {
await this.findOne(id);
return this.prisma.cat.update({ where: { id }, data: dto });
}
async remove(id: string) {
await this.findOne(id);
return this.prisma.cat.delete({ where: { id } });
}
}
技巧:Service 中不要直接处理 HTTP 层的逻辑(如状态码、响应格式),这些应该交给 Filter 或 Interceptor。
常用功能
DTO 与校验
配合 class-validator 和 ValidationPipe 做请求体验证。
import { IsString, IsInt, Min, Max, IsOptional } from 'class-validator';
import { Type } from 'class-transformer';
export class CreateCatDto {
@IsString()
name: string;
@IsInt()
@Min(0)
@Max(30)
@Type(() => Number)
age: number;
@IsOptional()
@IsString()
breed?: string;
}
export class UpdateCatDto {
@IsOptional()
@IsString()
name?: string;
@IsOptional()
@IsInt()
@Min(0)
@Max(30)
@Type(() => Number)
age?: number;
@IsOptional()
@IsString()
breed?: string;
}
在 main.ts 中启用全局校验:
import { ValidationPipe } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
app.useGlobalPipes(
new ValidationPipe({
whitelist: true, // 自动去除未定义的属性
transform: true, // 自动转换类型
forbidNonWhitelisted: true, // 禁止传递未定义的属性
}),
);
await app.listen(3000);
}
bootstrap();
Guard(守卫)
用于鉴权,例如 JWT 登录校验。
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { Request } from 'express';
@Injectable()
export class JwtAuthGuard implements CanActivate {
constructor(private jwtService: JwtService) {}
async canActivate(context: ExecutionContext): Promise<boolean> {
const request = context.switchToHttp().getRequest();
const token = this.extractTokenFromHeader(request);
if (!token) {
throw new UnauthorizedException();
}
try {
const payload = await this.jwtService.verifyAsync(token);
request.user = payload;
} catch {
throw new UnauthorizedException();
}
return true;
}
private extractTokenFromHeader(request: Request): string | undefined {
const [type, token] = request.headers.authorization?.split(' ') ?? [];
return type === 'Bearer' ? token : undefined;
}
}
使用方式:
@UseGuards(JwtAuthGuard)
@Get('profile')
getProfile(@Request() req) {
return req.user;
}
Interceptor(拦截器)
可在请求前后做日志、响应转换、缓存等处理。
import { Injectable, NestInterceptor, ExecutionContext, CallHandler } from '@nestjs/common';
import { Observable } from 'rxjs';
import { map } from 'rxjs/operators';
@Injectable()
export class TransformInterceptor<T> implements NestInterceptor<T, { data: T }> {
intercept(context: ExecutionContext, next: CallHandler): Observable<{ data: T }> {
return next.handle().pipe(map((data) => ({ data })));
}
}
全局注册:
app.useGlobalInterceptors(new TransformInterceptor());
Exception Filter(异常过滤器)
统一处理错误响应格式。
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();
const message = exception.getResponse();
response.status(status).json({
statusCode: status,
message: typeof message === 'string' ? message : (message as any).message,
timestamp: new Date().toISOString(),
path: ctx.getRequest<Request>().url,
});
}
}
全局注册:
app.useGlobalFilters(new HttpExceptionFilter());
项目结构建议
src/
modules/
users/
users.module.ts
users.controller.ts
users.service.ts
dto/
create-user.dto.ts
update-user.dto.ts
entities/
user.entity.ts
guards/
admin.guard.ts
posts/
posts.module.ts
posts.controller.ts
posts.service.ts
common/
guards/
jwt-auth.guard.ts
filters/
http-exception.filter.ts
interceptors/
transform.interceptor.ts
logging.interceptor.ts
decorators/
public.decorator.ts
prisma/
prisma.module.ts
prisma.service.ts
app.module.ts
main.ts
组织原则:
- 按功能模块划分(users、posts 等)
- 通用功能放在 common 目录
- 数据库相关放在 prisma 或 database 目录
与 Prisma 集成
import { Injectable, OnModuleInit } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';
@Injectable()
export class PrismaService extends PrismaClient implements OnModuleInit {
async onModuleInit() {
await this.$connect();
}
}
在 Module 中注册:
import { Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';
@Module({
providers: [PrismaService],
exports: [PrismaService],
})
export class PrismaModule {}
然后在 Service 中注入使用:
@Injectable()
export class UsersService {
constructor(private readonly prisma: PrismaService) {}
async findOne(email: string) {
return this.prisma.user.findUnique({ where: { email } });
}
}
认证与授权
JWT 认证
import { Module } from '@nestjs/common';
import { JwtModule } from '@nestjs/jwt';
import { AuthService } from './auth.service';
import { AuthController } from './auth.controller';
@Module({
imports: [
JwtModule.register({
global: true,
secret: process.env.JWT_SECRET,
signOptions: { expiresIn: '1h' },
}),
],
controllers: [AuthController],
providers: [AuthService],
})
export class AuthModule {}
认证服务:
import { Injectable, UnauthorizedException } from '@nestjs/common';
import { JwtService } from '@nestjs/jwt';
import { UsersService } from '../users/users.service';
import { LoginDto } from './dto/login.dto';
@Injectable()
export class AuthService {
constructor(
private usersService: UsersService,
private jwtService: JwtService,
) {}
async login(dto: LoginDto) {
const user = await this.usersService.findOne(dto.email);
if (!user || user.password !== dto.password) {
throw new UnauthorizedException('Invalid credentials');
}
const payload = { sub: user.id, email: user.email, role: user.role };
return {
access_token: await this.jwtService.signAsync(payload),
};
}
}
角色授权
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { ROLES_KEY } from '../decorators/roles.decorator';
@Injectable()
export class RolesGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(context: ExecutionContext): boolean {
const requiredRoles = this.reflector.getAllAndOverride<string[]>(ROLES_KEY, [
context.getHandler(),
context.getClass(),
]);
if (!requiredRoles) {
return true;
}
const { user } = context.switchToHttp().getRequest();
return requiredRoles.includes(user.role);
}
}
自定义装饰器:
import { SetMetadata } from '@nestjs/common';
export const ROLES_KEY = 'roles';
export const Roles = (...roles: string[]) => SetMetadata(ROLES_KEY, roles);
使用:
@Roles('admin')
@UseGuards(JwtAuthGuard, RolesGuard)
@Delete(':id')
remove(@Param('id') id: string) {
return this.usersService.remove(id);
}
Swagger 文档
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
const config = new DocumentBuilder()
.setTitle('API Documentation')
.setDescription('The API description')
.setVersion('1.0')
.addBearerAuth()
.build();
const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup('api', app, document);
await app.listen(3000);
}
bootstrap();
在 Controller 和 DTO 中添加装饰器:
@ApiTags('cats')
@Controller('cats')
export class CatsController {}
@ApiProperty()
@IsString()
name: string;
中间件
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
@Injectable()
export class LoggerMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
next();
}
}
在 Module 中注册:
export class AppModule implements NestModule {
configure(consumer: MiddlewareConsumer) {
consumer.apply(LoggerMiddleware).forRoutes('*');
}
}
测试
单元测试
import { Test, TestingModule } from '@nestjs/testing';
import { CatsService } from './cats.service';
import { PrismaService } from '../prisma/prisma.service';
describe('CatsService', () => {
let service: CatsService;
let prisma: PrismaService;
beforeEach(async () => {
const module: TestingModule = await Test.createTestingModule({
providers: [
CatsService,
{
provide: PrismaService,
useValue: {
cat: {
findMany: jest.fn(),
findUnique: jest.fn(),
create: jest.fn(),
update: jest.fn(),
delete: jest.fn(),
},
},
},
],
}).compile();
service = module.get<CatsService>(CatsService);
prisma = module.get<PrismaService>(PrismaService);
});
it('should be defined', () => {
expect(service).toBeDefined();
});
it('should find all cats', async () => {
const mockCats = [{ id: '1', name: 'Whiskers', age: 2 }];
jest.spyOn(prisma.cat, 'findMany').mockResolvedValue(mockCats);
jest.spyOn(prisma.cat, 'count').mockResolvedValue(1);
const result = await service.findAll(1, 10);
expect(result.data).toEqual(mockCats);
expect(prisma.cat.findMany).toHaveBeenCalled();
});
});
端到端测试
import { Test, TestingModule } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import * as request from 'supertest';
import { AppModule } from './../src/app.module';
describe('Cats (e2e)', () => {
let app: INestApplication;
beforeEach(async () => {
const moduleFixture: TestingModule = await Test.createTestingModule({
imports: [AppModule],
}).compile();
app = moduleFixture.createNestApplication();
await app.init();
});
it('/cats (POST)', () => {
return request(app.getHttpServer())
.post('/cats')
.send({ name: 'Whiskers', age: 2 })
.expect(201);
});
afterAll(async () => {
await app.close();
});
});
部署
Docker
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/main.js"]
Railway / Render
- 连接 GitHub 仓库
- 配置环境变量
- 设置构建命令:
npm run build - 设置启动命令:
npm run start:prod
学习要点总结
| 概念 | 作用 |
|---|---|
| Module | 组织代码,管理依赖 |
| Controller | 处理路由和 HTTP 请求 |
| Provider | 业务逻辑,可注入的依赖 |
| DTO | 数据结构定义和校验 |
| Guard | 权限控制和认证 |
| Interceptor | 请求/响应增强 |
| Exception Filter | 统一错误处理 |
| Middleware | 中间件处理 |
实践中的坑
- 循环依赖:模块之间不要互相导入,会导致循环依赖错误
- DI 注入顺序:确保依赖的服务已经注册
- TypeScript 类型问题:DTO 中的数字类型需要使用
@Type(() => Number)转换 - 全局管道/过滤器/拦截器:需要在
main.ts中注册,不能在模块中注册 - Prisma 热重载:开发时需要手动重启服务,或者使用
nest start --watch