← 返回笔记列表
·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

  1. 连接 GitHub 仓库
  2. 配置环境变量
  3. 设置构建命令:npm run build
  4. 设置启动命令: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