【NestJS】15 最佳实践与学习总结

1
// ✅ 推荐：Service 封装业务逻辑
2
@Injectable()
3
export class UserService {
4
  constructor(
5
    @InjectModel(User.name) private userModel: Model<User>,
6
    private readonly emailService: EmailService,
7
    private readonly cacheService: CacheService,
8
  ) {}
9

10
  async create(dto: CreateUserDto): Promise<User> {
11
    // 业务逻辑：检查用户是否存在
12
    const existing = await this.userModel.findOne({ email: dto.email });
13
    if (existing) {
14
      throw new ConflictException('邮箱已被使用');
15
    }
16

17
    // 业务逻辑：创建用户
18
    const user = await this.userModel.create(dto);
19

20
    // 业务逻辑：发送欢迎邮件（异步，不阻塞）
21
    this.emailService.sendWelcome(user.email).catch(console.error);
22

23
    // 业务逻辑：清除缓存
24
    await this.cacheService.invalidate('users');
25

26
    return user;
27
  }
28

29
  async findOne(id: number): Promise<User> {
30
    // 业务逻辑：先查缓存
31
    const cached = await this.cacheService.get(`user:${id}`);
32
    if (cached) return cached;
33

34
    // 业务逻辑：查数据库
35
    const user = await this.userModel.findById(id);
36

37
    if (!user) {
38
      throw new NotFoundException(`用户 ${id} 不存在`);
39
    }
40

41
    // 业务逻辑：写入缓存
42
    await this.cacheService.set(`user:${id}`, user, 3600);
43

44
    return user;
45
  }
46

47
  async update(id: number, dto: UpdateUserDto): Promise<User> {
48
    const user = await this.findOne(id); // 复用查询逻辑
49

50
    Object.assign(user, dto);
51
    await user.save();
52

53
    // 清除缓存
54
    await this.cacheService.invalidate(`user:${id}`);
55

56
    return user;
57
  }
58
}

1
// ✅ 推荐：JWT 认证守卫
2
@Injectable()
3
export class JwtAuthGuard implements CanActivate {
4
  constructor(
5
    private jwtService: JwtService,
6
    private reflector: Reflector,
7
  ) {}
8

9
  canActivate(context: ExecutionContext): boolean {
10
    // 检查是否标记为公开路由
11
    const isPublic = this.reflector.get<boolean>(
12
      'isPublic',
13
      context.getHandler(),
14
    );
15
    if (isPublic) return true;
16

17
    const request = context.switchToHttp().getRequest();
18
    const token = this.extractTokenFromHeader(request);
19

20
    if (!token) {
21
      throw new UnauthorizedException('未提供认证令牌');
22
    }
23

24
    try {
25
      const payload = this.jwtService.verify(token);
26
      request.user = payload;  // 将用户信息附加到请求
27
      return true;
28
    } catch {
29
      throw new UnauthorizedException('认证令牌无效');
30
    }
31
  }
32

33
  private extractTokenFromHeader(request: Request): string | undefined {
34
    const [type, token] = request.headers.authorization?.split(' ') ?? [];
35
    return type === 'Bearer' ? token : undefined;
36
  }
37
}
38

39
// ✅ 推荐：角色守卫
40
@Injectable()
41
export class RolesGuard implements CanActivate {
42
  constructor(private reflector: Reflector) {}
43

44
  canActivate(context: ExecutionContext): boolean {
45
    const requiredRoles = this.reflector.get<string[]>(
46
      'roles',
47
      context.getHandler(),
48
    );
49

50
    if (!requiredRoles) {
51
      return true;  // 没有角色要求，允许访问
52
    }
53

54
    const request = context.switchToHttp().getRequest();
55
    const user = request.user;
56

57
    if (!user) {
58
      throw new UnauthorizedException('未认证');
59
    }
60

61
    const hasRole = requiredRoles.some(role => user.roles?.includes(role));
62

63
    if (!hasRole) {
64
      throw new ForbiddenException('权限不足');
65
    }
66

67
    return true;
68
  }
69
}
70

71
// 使用守卫
72
@Controller('user')
73
@UseGuards(JwtAuthGuard, RolesGuard)  // 可以组合多个守卫
74
export class UserController {
75
  @Get('profile')
76
  getProfile(@Request() req) {
77
    return req.user;  // 访问守卫注入的用户信息
78
  }
79

80
  @Post('admin')
81
  @Roles('admin')  // 需要 admin 角色
82
  adminAction() {
83
    return 'Admin action';
84
  }
85

86
  @Get('public')
87
  @Public()  // 公开路由，不需要认证
88
  publicRoute() {
89
    return 'Public data';
90
  }
91
}
92

93
// 自定义装饰器
94
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
95
export const Public = () => SetMetadata('isPublic', true);

1
// ✅ 推荐：统一响应格式拦截器
2
@Injectable()
3
export class ResponseInterceptor implements NestInterceptor {
4
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
5
    return next.handle().pipe(
6
      map(data => ({
7
        code: 200,
8
        message: 'Success',
9
        data: data,
10
        timestamp: new Date().toISOString(),
11
      })),
12
    );
13
  }
14
}
15

16
// ✅ 推荐：性能监控拦截器
17
@Injectable()
18
export class PerformanceInterceptor implements NestInterceptor {
19
  private readonly logger = new Logger('Performance');
20

21
  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
22
    const request = context.switchToHttp().getRequest();
23
    const { method, url } = request;
24
    const startTime = Date.now();
25

26
    return next.handle().pipe(
27
      tap(() => {
28
        const duration = Date.now() - startTime;
29

30
        if (duration > 1000) {
31
          this.logger.warn(`慢请求: ${method} ${url} - ${duration}ms`);
32
        } else {
33
          this.logger.log(`${method} ${url} - ${duration}ms`);
34
        }
35
      }),
36
    );
37
  }
38
}
39

40
// ✅ 推荐：缓存拦截器
41
@Injectable()
42
export class CacheInterceptor implements NestInterceptor {
43
  constructor(private cacheService: CacheService) {}
44

45
  async intercept(
46
    context: ExecutionContext,
47
    next: CallHandler,
48
  ): Promise<Observable<any>> {
49
    const request = context.switchToHttp().getRequest();
50
    const cacheKey = `cache:${request.url}`;
51

52
    // 尝试从缓存获取
53
    const cached = await this.cacheService.get(cacheKey);
54
    if (cached) {
55
      return of(cached);  // 直接返回缓存
56
    }
57

58
    // 执行请求并缓存结果
59
    return next.handle().pipe(
60
      tap(async (data) => {
61
        await this.cacheService.set(cacheKey, data, 300);  // 缓存 5 分钟
62
      }),
63
    );
64
  }
65
}
66

67
// 全局注册拦截器
68
async function bootstrap() {
69
  const app = await NestFactory.create(AppModule);
70

71
  app.useGlobalInterceptors(
72
    new ResponseInterceptor(),
73
    new PerformanceInterceptor(),
74
  );
75

76
  await app.listen(3000);
77
}

1
// ✅ 推荐：使用 class-validator 进行验证
2
import { IsEmail, IsString, MinLength, MaxLength, IsOptional } from 'class-validator';
3

4
export class CreateUserDto {
5
  @IsString({ message: '用户名必须是字符串' })
6
  @MinLength(3, { message: '用户名至少 3 个字符' })
7
  @MaxLength(20, { message: '用户名最多 20 个字符' })
8
  username: string;
9

10
  @IsEmail({}, { message: '邮箱格式不正确' })
11
  email: string;
12

13
  @IsString()
14
  @MinLength(6, { message: '密码至少 6 个字符' })
15
  password: string;
16

17
  @IsOptional()
18
  @IsString()
19
  bio?: string;
20
}
21

22
// 在控制器中使用
23
@Post()
24
async create(@Body() dto: CreateUserDto) {
25
  // ValidationPipe 会自动验证 DTO
26
  return this.userService.create(dto);
27
}
28

29
// ✅ 推荐：自定义管道进行类型转换
30
@Injectable()
31
export class ParseIntPipe implements PipeTransform<string, number> {
32
  transform(value: string, metadata: ArgumentMetadata): number {
33
    const val = parseInt(value, 10);
34

35
    if (isNaN(val)) {
36
      throw new BadRequestException(
37
        `${metadata.data} 参数必须是数字，收到的是: ${value}`
38
      );
39
    }
40

41
    return val;
42
  }
43
}
44

45
// ✅ 推荐：自定义验证管道
46
@Injectable()
47
export class FileValidationPipe implements PipeTransform {
48
  constructor(private readonly maxSize: number) {}
49

50
  transform(value: any) {
51
    if (!value) {
52
      throw new BadRequestException('文件不能为空');
53
    }
54

55
    if (value.size > this.maxSize) {
56
      throw new BadRequestException(
57
        `文件大小不能超过 ${this.maxSize / 1024 / 1024}MB`
58
      );
59
    }
60

61
    const allowedTypes = ['image/jpeg', 'image/png', 'image/gif'];
62
    if (!allowedTypes.includes(value.mimetype)) {
63
      throw new BadRequestException('只支持 JPG、PNG、GIF 格式');
64
    }
65

66
    return value;
67
  }
68
}
69

70
// 使用自定义管道
71
@Post('upload')
72
@UseInterceptors(FileInterceptor('file'))
73
uploadFile(
74
  @UploadedFile(new FileValidationPipe(5 * 1024 * 1024)) file: Express.Multer.File
75
) {
76
  return { filename: file.filename };
77
}

1
// ✅ 推荐：全局异常过滤器
2
@Catch()
3
export class AllExceptionsFilter implements ExceptionFilter {
4
  private readonly logger = new Logger(AllExceptionsFilter.name);
5

6
  catch(exception: unknown, host: ArgumentsHost) {
7
    const ctx = host.switchToHttp();
8
    const response = ctx.getResponse<Response>();
9
    const request = ctx.getRequest<Request>();
10

11
    let status = HttpStatus.INTERNAL_SERVER_ERROR;
12
    let message = '服务器内部错误';
13
    let errors: any = null;
14

15
    // 处理 HTTP 异常
16
    if (exception instanceof HttpException) {
17
      status = exception.getStatus();
18
      const exceptionResponse = exception.getResponse();
19

20
      if (typeof exceptionResponse === 'string') {
21
        message = exceptionResponse;
22
      } else if (typeof exceptionResponse === 'object') {
23
        const responseObj = exceptionResponse as any;
24
        message = responseObj.message || '请求失败';
25
        errors = responseObj.errors || null;
26
      }
27
    }
28
    // 处理 Mongoose 错误
29
    else if (exception instanceof Error && exception.name === 'MongoError') {
30
      status = HttpStatus.BAD_REQUEST;
31
      message = '数据库操作失败';
32

33
      // 处理唯一索引冲突
34
      if ((exception as any).code === 11000) {
35
        message = '数据已存在';
36
      }
37
    }
38
    // 处理其他异常
39
    else if (exception instanceof Error) {
40
      message = exception.message || '服务器内部错误';
41
      this.logger.error(
42
        `未处理的异常: ${exception.message}`,
43
        exception.stack,
44
      );
45
    }
46

47
    // 记录错误日志
48
    this.logger.error(
49
      `${request.method} ${request.url} - ${status} - ${message}`,
50
      exception instanceof Error ? exception.stack : undefined,
51
    );
52

53
    // 返回统一格式的错误响应
54
    response.status(status).json({
55
      code: status,
56
      message: Array.isArray(message) ? message[0] : message,
57
      data: null,
58
      timestamp: new Date().toISOString(),
59
      path: request.url,
60
      ...(errors && { errors }),
61
    });
62
  }
63
}
64

65
// 全局注册
66
async function bootstrap() {
67
  const app = await NestFactory.create(AppModule);
68
  app.useGlobalFilters(new AllExceptionsFilter());
69
  await app.listen(3000);
70
}