【NestJS】12 守卫（Guard）：认证与权限控制实战

这一片我们将学习 守卫（Guard），这是 NestJS 中用于权限控制的核心机制。

守卫决定一个请求是否应该被路由处理函数处理。它通常用于认证（Authentication）和授权（Authorization）。认证是验证”你是谁”，授权是验证”你能做什么”。这两个概念是构建安全应用的基石 🔐

一、什么是守卫？#

守卫的定义 🎯#

守卫（Guard） 是决定一个请求是否应该被路由处理函数处理的类。它实现了 CanActivate 接口，返回布尔值来决定请求的命运。

守卫的核心逻辑：

返回 true：请求继续处理，进入后续流程
返回 false：请求被拒绝，通常返回 403 Forbidden 错误

📚 参考资源：

NestJS Guards 官方文档 - 官方完整指南

JWT 官方网站 - JSON Web Token 标准

守卫的执行时机 📍#

在 NestJS 的请求处理流程中，守卫处于关键位置：

1
请求 → 中间件 → 守卫 → 拦截器（前） → 管道 → 控制器

守卫在中间件之后、拦截器之前执行，确保只有通过验证的请求才能进入后续流程。

守卫的核心用途#

守卫在实际应用中主要用于三大场景：

认证（Authentication）：验证用户是否已登录，确认用户身份
授权（Authorization）：验证用户是否有权限访问特定资源
角色控制（Role-Based Access Control）：根据用户角色决定是否允许访问

二、创建第一个守卫#

使用 CLI 生成守卫#

NestJS CLI 提供了快速生成守卫的命令：

1
nest generate guard auth

或者使用简写：

1
nest g guard auth

这会创建 src/auth/auth.guard.ts 文件。

基本守卫实现#

让我们看看生成的文件结构：

1
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
2

3
@Injectable()
4
export class AuthGuard implements CanActivate {
5
  canActivate(context: ExecutionContext): boolean {
6
    // 守卫逻辑
7
    return true;
8
  }
9
}

ExecutionContext 详解#

ExecutionContext 提供了当前执行上下文的丰富信息：

1
canActivate(context: ExecutionContext): boolean {
2
  // 获取 HTTP 上下文
3
  const request = context.switchToHttp().getRequest();
4
  const response = context.switchToHttp().getResponse();
5

6
  // 可以访问请求的所有信息
7
  return true;
8
}

📚 参考资源：

ExecutionContext API 文档 - 执行上下文详解

基本示例：Token 验证守卫#

创建一个简单的认证守卫，验证请求头中的 Token：

1
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
2

3
@Injectable()
4
export class AuthGuard implements CanActivate {
5
  canActivate(context: ExecutionContext): boolean {
6
    const request = context.switchToHttp().getRequest();
7
    const token = request.headers.authorization;
8

9
    if (!token) {
10
      return false; // 未提供 token，拒绝请求
11
    }
12

13
    // 验证 token（简化示例）
14
    return this.validateToken(token);
15
  }
16

17
  private validateToken(token: string): boolean {
18
    // 实际项目中应该验证 JWT
19
    return token.startsWith('Bearer ');
20
  }
21
}

三、使用守卫#

控制器级别守卫#

使用 @UseGuards() 装饰器应用到整个控制器：

1
@Controller('user')
2
@UseGuards(AuthGuard)  // 所有路由都需要认证
3
export class UserController {
4
  @Get()
5
  findAll() {
6
    return '所有用户';
7
  }
8
}

方法级别守卫#

也可以只应用到特定方法：

1
@Controller('user')
2
export class UserController {
3
  @Get()
4
  @UseGuards(AuthGuard)  // 只有这个方法需要认证
5
  findAll() {
6
    return '所有用户';
7
  }
8

9
  @Get('public')
10
  getPublic() {
11
    return '公开信息';  // 不需要认证
12
  }
13
}

全局守卫#

在 app.module.ts 中注册全局守卫，对所有路由生效：

1
import { APP_GUARD } from '@nestjs/core';
2
import { AuthGuard } from './auth/auth.guard';
3

4
@Module({
5
  providers: [
6
    {
7
      provide: APP_GUARD,
8
      useClass: AuthGuard,
9
    },
10
  ],
11
})
12
export class AppModule {}

多个守卫组合#

可以同时应用多个守卫，它们会按顺序执行：

1
@UseGuards(AuthGuard, RolesGuard)  // 先认证，再验证角色
2
export class UserController {
3
  // 所有守卫都返回 true 时，请求才会继续
4
}

四、认证守卫实现#

什么是认证？#

认证（Authentication） 是验证用户身份的过程，确认”你是谁”。常见的认证方式包括：

用户名密码登录
Token 认证（如 JWT）
OAuth 第三方登录
生物识别认证

📚 参考资源：

OAuth 2.0 官方文档 - OAuth 认证标准

MDN - HTTP 认证 - HTTP 认证机制

完整的认证守卫实现#

创建一个功能完善的认证守卫：

1
import {
2
  CanActivate,
3
  ExecutionContext,
4
  Injectable,
5
  UnauthorizedException,
6
} from '@nestjs/common';
7
import { Request } from 'express';
8

9
@Injectable()
10
export class AuthGuard implements CanActivate {
11
  canActivate(context: ExecutionContext): boolean {
12
    const request = context.switchToHttp().getRequest<Request>();
13
    const token = this.extractTokenFromHeader(request);
14

15
    if (!token) {
16
      throw new UnauthorizedException('未提供认证令牌');
17
    }
18

19
    // 验证 token（实际项目中应该验证 JWT）
20
    if (!this.validateToken(token)) {
21
      throw new UnauthorizedException('认证令牌无效');
22
    }
23

24
    // 将用户信息附加到请求对象，供后续使用
25
    request.user = this.getUserFromToken(token);
26

27
    return true;
28
  }
29

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

35
  private validateToken(token: string): boolean {
36
    // 实际的 token 验证逻辑
37
    // 这里简化处理
38
    return token.length > 10;
39
  }
40

41
  private getUserFromToken(token: string): any {
42
    // 从 token 中提取用户信息
43
    // 实际项目中应该解析 JWT
44
    return { id: 1, name: '测试用户', roles: ['user'] };
45
  }
46
}

在控制器中使用#

1
@Controller('user')
2
@UseGuards(AuthGuard)
3
export class UserController {
4
  @Get('info')
5
  getInfo(@Request() req: any) {
6
    // req.user 包含从守卫中注入的用户信息
7
    return req.user;
8
  }
9
}

五、授权守卫实现#

什么是授权？#

授权（Authorization） 是验证用户是否有权限访问资源的过程，确认”你能做什么”。授权发生在认证之后。

常见的授权模型：

RBAC（Role-Based Access Control）：基于角色的访问控制
ABAC（Attribute-Based Access Control）：基于属性的访问控制
ACL（Access Control List）：访问控制列表

实现角色守卫#

创建一个基于角色的授权守卫：

1
import {
2
  CanActivate,
3
  ExecutionContext,
4
  Injectable,
5
  SetMetadata,
6
} from '@nestjs/common';
7
import { Reflector } from '@nestjs/core';
8

9
// 定义角色装饰器
10
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
11

12
@Injectable()
13
export class RolesGuard implements CanActivate {
14
  constructor(private reflector: Reflector) {}
15

16
  canActivate(context: ExecutionContext): boolean {
17
    // 获取路由处理器上的角色元数据
18
    const requiredRoles = this.reflector.get<string[]>(
19
      'roles',
20
      context.getHandler(),
21
    );
22

23
    if (!requiredRoles) {
24
      return true; // 没有角色要求，允许访问
25
    }
26

27
    const request = context.switchToHttp().getRequest();
28
    const user = request.user;
29

30
    if (!user) {
31
      return false; // 用户未认证
32
    }
33

34
    // 检查用户是否拥有所需角色
35
    return requiredRoles.some((role) => user.roles?.includes(role));
36
  }
37
}

📚 参考资源：

Reflector API 文档 - 元数据反射

使用角色守卫#

1
@Controller('admin')
2
@UseGuards(AuthGuard, RolesGuard)  // 先认证，再验证角色
3
export class AdminController {
4
  @Get('users')
5
  @Roles('admin')  // 只有 admin 角色可以访问
6
  getUsers() {
7
    return '所有用户列表';
8
  }
9

10
  @Get('stats')
11
  @Roles('admin', 'moderator')  // admin 或 moderator 角色可以访问
12
  getStats() {
13
    return '统计数据';
14
  }
15
}

六、JWT 认证守卫实现#

什么是 JWT？#

JWT（JSON Web Token） 是一种开放标准（RFC 7519），用于在各方之间安全地传输信息。JWT 由三部分组成：

Header（头部）：包含令牌类型和加密算法
Payload（负载）：包含用户信息和其他数据
Signature（签名）：用于验证令牌的完整性

📚 参考资源：

JWT.io - JWT 在线调试工具

RFC 7519 - JWT 官方标准

安装依赖#

首先，安装必要的依赖包：

1
pnpm add @nestjs/jwt@11.0.0 @nestjs/passport@11.0.5 passport@0.7.0 passport-jwt@4.0.1
2
pnpm add -D @types/passport-jwt@4.0.1

配置 JWT 模块#

在 app.module.ts 中配置 JWT 模块：

1
import { JwtModule } from '@nestjs/jwt';
2
import { JwtStrategy } from './auth/jwt.strategy';
3

4
@Module({
5
  imports: [
6
    JwtModule.register({
7
      secret: 'sunday-secret-key', // 应该从环境变量读取
8
      signOptions: { expiresIn: '24h' },
9
    }),
10
  ],
11
  providers: [JwtStrategy],
12
})
13
export class AppModule {}

推荐使用异步配置，从环境变量读取密钥：

1
JwtModule.registerAsync({
2
  imports: [ConfigModule],
3
  useFactory: async (configService: ConfigService) => ({
4
    secret: configService.get<string>('JWT_SECRET'),
5
    signOptions: { expiresIn: '24h' },
6
  }),
7
  inject: [ConfigService],
8
}),

创建 JWT Strategy#

创建 src/auth/jwt.strategy.ts 文件：

1
import { Injectable, UnauthorizedException } from '@nestjs/common';
2
import { PassportStrategy } from '@nestjs/passport';
3
import { ExtractJwt, Strategy } from 'passport-jwt';
4
import { ConfigService } from '@nestjs/config';
5

6
@Injectable()
7
export class JwtStrategy extends PassportStrategy(Strategy) {
8
  constructor(private configService: ConfigService) {
9
    super({
10
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(), // 从 Bearer Token 中提取
11
      ignoreExpiration: false, // 不忽略过期时间
12
      secretOrKey: configService.get<string>('JWT_SECRET') || 'sunday-secret-key',
13
    });
14
  }
15

16
  async validate(payload: any) {
17
    if (!payload.userId) {
18
      throw new UnauthorizedException('Token 无效');
19
    }
20

21
    // 返回的对象会被附加到 request.user
22
    return {
23
      userId: payload.userId,
24
      username: payload.username,
25
      roles: payload.roles || ['user'],
26
    };
27
  }
28
}

创建 JWT 认证守卫#

创建 src/auth/jwt-auth.guard.ts 文件：

1
import { Injectable } from '@nestjs/common';
2
import { AuthGuard } from '@nestjs/passport';
3

4
@Injectable()
5
export class JwtAuthGuard extends AuthGuard('jwt') {}

使用 JWT 认证守卫#

1
@Controller('user')
2
@UseGuards(JwtAuthGuard)  // 使用 JWT 认证
3
export class UserController {
4
  @Get('info')
5
  getInfo(@Request() req: any) {
6
    // req.user 包含从 JWT 中解析的用户信息
7
    return req.user;
8
  }
9
}

七、执行上下文（ExecutionContext）#

ExecutionContext 详解#

ExecutionContext 是守卫中最重要的参数，提供了当前执行上下文的完整信息。

获取请求和响应对象#

1
canActivate(context: ExecutionContext): boolean {
2
  const ctx = context.switchToHttp();
3
  const request = ctx.getRequest();    // 获取请求对象
4
  const response = ctx.getResponse();  // 获取响应对象
5

6
  // 访问请求信息
7
  console.log(request.method);  // GET, POST, etc.
8
  console.log(request.url);     // /user/info
9
  console.log(request.headers); // 请求头
10

11
  return true;
12
}

获取路由信息#

1
canActivate(context: ExecutionContext): boolean {
2
  const handler = context.getHandler();  // 获取处理方法
3
  const controller = context.getClass(); // 获取控制器类
4

5
  console.log(handler.name);    // 方法名
6
  console.log(controller.name); // 控制器名
7

8
  return true;
9
}

获取元数据#

使用 Reflector 获取通过装饰器设置的元数据：

1
import { Reflector } from '@nestjs/core';
2

3
constructor(private reflector: Reflector) {}
4

5
canActivate(context: ExecutionContext): boolean {
6
  // 获取方法上的角色元数据
7
  const roles = this.reflector.get<string[]>('roles', context.getHandler());
8

9
  // 获取控制器上的元数据
10
  const isPublic = this.reflector.get<boolean>('isPublic', context.getClass());
11

12
  return true;
13
}

八、实战：完整的权限验证系统#

需求分析 📋#

创建一个完整的权限验证系统，包含以下功能：

JWT 认证守卫：验证用户身份
角色守卫：验证用户权限
在控制器中组合使用

完整实现#

第一步：配置 JWT 模块

在 app.module.ts 中配置（参考前面的代码）。

第二步：创建 JWT Strategy

创建 src/auth/jwt.strategy.ts（参考前面的代码）。

第三步：创建 JWT 认证守卫

创建 src/auth/jwt-auth.guard.ts（参考前面的代码）。

第四步：创建角色守卫

1
import {
2
  CanActivate,
3
  ExecutionContext,
4
  Injectable,
5
  SetMetadata,
6
} from '@nestjs/common';
7
import { Reflector } from '@nestjs/core';
8

9
export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
10

11
@Injectable()
12
export class RolesGuard implements CanActivate {
13
  constructor(private reflector: Reflector) {}
14

15
  canActivate(context: ExecutionContext): boolean {
16
    const requiredRoles = this.reflector.get<string[]>(
17
      'roles',
18
      context.getHandler(),
19
    );
20

21
    if (!requiredRoles) {
22
      return true;
23
    }
24

25
    const request = context.switchToHttp().getRequest();
26
    const user = request.user;
27

28
    if (!user) {
29
      return false;
30
    }
31

32
    return requiredRoles.some((role) => user.roles?.includes(role));
33
  }
34
}

第五步：在控制器中使用

1
import { Controller, Get, UseGuards, Request } from '@nestjs/common';
2
import { JwtAuthGuard } from '../auth/jwt-auth.guard';
3
import { RolesGuard, Roles } from '../auth/roles.guard';
4

5
@Controller('user')
6
@UseGuards(JwtAuthGuard) // 所有路由都需要认证
7
export class UserController {
8
  @Get('info')
9
  getInfo(@Request() req: any) {
10
    return req.user;
11
  }
12

13
  @Get('admin')
14
  @UseGuards(RolesGuard)
15
  @Roles('admin')
16
  getAdminInfo(@Request() req: any) {
17
    // 只有 admin 角色可以访问
18
    return { message: '管理员信息', user: req.user };
19
  }
20
}

测试验证 ✅#

1. 使用 Token 访问接口

1
curl http://localhost:3000/user/info \
2
  -H "Authorization: Bearer <your-token>"

2. 测试未认证的请求

1
curl http://localhost:3000/user/info

应该返回 401 Unauthorized 错误。

九、守卫的最佳实践#

1. 分离认证和授权 🔐#

1
// ✅ 推荐：分离关注点
2
@UseGuards(JwtAuthGuard, RolesGuard)
3
export class AdminController {}

2. 使用装饰器提高可读性 📝#

1
// ✅ 推荐：清晰明了
2
@Roles('admin')
3
@Get('admin')
4
getAdmin() {
5
  return '管理员信息';
6
}

3. 提供友好的错误信息 💬#

1
// ✅ 推荐：友好的错误信息
2
if (!user) {
3
  throw new UnauthorizedException('请先登录后再访问');
4
}
5

6
if (!hasPermission) {
7
  throw new ForbiddenException('您没有权限访问此资源');
8
}

4. 使用全局守卫 🌐#

1
// ✅ 推荐：全局认证
2
@Module({
3
  providers: [
4
    {
5
      provide: APP_GUARD,
6
      useClass: JwtAuthGuard,
7
    },
8
  ],
9
})
10
export class AppModule {}

十、常见问题排查#

问题 1：守卫未执行#

可能原因：守卫未注册或未使用 @UseGuards() 装饰器

解决方案：

1
// ✅ 确保守卫已注册
2
@Module({
3
  providers: [AuthGuard],
4
})

问题 2：Token 验证失败#

可能原因：Token 格式不正确或 Secret 不匹配

解决方案：检查 Token 格式和 Secret 配置

问题 3：用户信息未注入#

可能原因：守卫的 validate 方法未返回用户信息

解决方案：确保返回用户信息对象

总结 🎯#

这节课我们系统学习了 NestJS 守卫的核心概念和实战应用。

核心知识点 ✅#

✅ 理解了守卫的定义：决定请求是否应该被处理的类
✅ 掌握了守卫的执行时机：在中间件之后、拦截器之前
✅ 学习了如何创建守卫：实现 CanActivate 接口
✅ 实现了认证守卫：验证用户身份
✅ 实现了授权守卫：验证用户权限
✅ 学习了 JWT 认证：使用 Passport 和 JWT
✅ 了解了 ExecutionContext：获取执行上下文信息

认证 vs 授权对比 📊#

概念	英文	作用	示例
认证	Authentication	验证”你是谁”	用户登录、Token 验证
授权	Authorization	验证”你能做什么”	角色权限、资源访问控制

音乐

音乐

【NestJS】12 守卫（Guard）：认证与权限控制实战

一、什么是守卫？#

守卫的定义 🎯#

守卫的执行时机 📍#

守卫的核心用途#

二、创建第一个守卫#

使用 CLI 生成守卫#

基本守卫实现#

ExecutionContext 详解#

基本示例：Token 验证守卫#

三、使用守卫#

控制器级别守卫#

方法级别守卫#

全局守卫#

多个守卫组合#

四、认证守卫实现#

什么是认证？#

完整的认证守卫实现#

在控制器中使用#

五、授权守卫实现#

什么是授权？#

实现角色守卫#

使用角色守卫#

六、JWT 认证守卫实现#

什么是 JWT？#

安装依赖#

配置 JWT 模块#

创建 JWT Strategy#

创建 JWT 认证守卫#

使用 JWT 认证守卫#

七、执行上下文（ExecutionContext）#

ExecutionContext 详解#

获取请求和响应对象#

获取路由信息#

获取元数据#

八、实战：完整的权限验证系统#

需求分析 📋#

完整实现#

测试验证 ✅#

九、守卫的最佳实践#

1. 分离认证和授权 🔐#

2. 使用装饰器提高可读性 📝#

3. 提供友好的错误信息 💬#

4. 使用全局守卫 🌐#

十、常见问题排查#

问题 1：守卫未执行#

问题 2：Token 验证失败#

问题 3：用户信息未注入#

总结 🎯#

核心知识点 ✅#

认证 vs 授权对比 📊#

延伸学习资源 📚#

支持与分享

评论区

文章目录