NestJS守卫如何实现权限控制？

Question

在使用NestJS进行权限控制时，常通过守卫（Guard）实现角色或权限校验。一个典型问题是：**如何基于用户角色动态控制路由访问权限？** 例如，管理员可访问所有接口，普通用户仅能查看部分数据。虽然NestJS提供了`CanActivate`接口和装饰器结合的机制，但在实际应用中，开发者常面临如何将用户角色信息注入请求上下文、如何在守卫中获取当前路由所需权限、以及如何实现细粒度权限判断等挑战。此外，与JWT策略协同时，守卫如何确保认证完成后再执行权限校验也易出错。这些问题若处理不当，会导致权限绕过或拦截失效，影响系统安全性。

Answer 1

基于NestJS的动态路由权限控制：从基础到高阶实践

1. 权限控制的基本模型与NestJS守卫机制

NestJS通过CanActivate接口提供了强大的守卫（Guard）机制，允许开发者在请求进入控制器前进行逻辑拦截。最常见的使用场景是角色基础的访问控制（RBAC），即根据用户角色决定是否放行请求。

守卫的核心在于实现canActivate方法，该方法返回布尔值或Promise/Observable，用于异步判断：

@Injectable()
export class RolesGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    return validateUserRoles(request.user, requiredRoles);
  }
}

2. 用户角色信息的上下文注入流程

要实现权限校验，首先需确保用户身份及角色信息已正确注入到请求对象中。通常这一过程发生在JWT认证策略中。

以下是JWT策略中将用户信息附加到请求的典型实现：

async validate(payload: any) {
  const user = await this.usersService.findById(payload.sub);
  return { userId: user.id, roles: user.roles };
}

在AuthGuard执行后，用户信息会自动挂载至req.user，为后续守卫提供数据支持。

3. 自定义装饰器与元数据结合实现权限声明

为了灵活指定每个路由所需的权限，可使用自定义装饰器绑定角色元数据：

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

然后在控制器中使用：

@Get('admin')
@Roles('admin')
@UseGuards(RolesGuard)
findAll() {
  return this.service.findAll();
}

守卫可通过Reflector获取当前路由所需角色：

const requiredRoles = this.reflector.getAllAndOverride<string[]>('roles', [
  context.getHandler(),
  context.getClass(),
]);

4. 守卫执行顺序与认证-授权协同问题

一个常见错误是未正确协调JwtAuthGuard与RolesGuard的执行顺序，导致req.user为空。

解决方案是确保先执行认证守卫，再执行权限守卫：

@UseGuards(JwtAuthGuard, RolesGuard)

NestJS按数组顺序依次执行守卫，因此顺序至关重要。

5. 细粒度权限控制的设计模式

除角色外，还可引入权限码（Permission Code）实现更细粒度控制，如“user:read”、“order:write”。

用户角色	可访问接口	对应权限码
admin	/users, /orders, /settings	*
user	/profile, /orders (read-only)	user:read, order:read
support	/tickets, /users (limited)	ticket:manage, user:view

6. 基于资源的权限校验（ABAC雏形）

对于更复杂的场景，如“用户只能编辑自己的文章”，需结合请求参数进行动态判断：

const userId = request.user.userId;
const resourceId = request.params.id;
return resource.ownerId === userId;

此类逻辑可封装为独立的守卫或策略服务，提升复用性。

7. 守卫的可扩展架构设计

为避免守卫膨胀，建议采用策略模式分离不同权限类型：

• RoleBasedGuard：处理角色校验
• PermissionGuard：处理权限码校验
• OwnershipGuard：处理资源归属校验

并通过组合方式在路由上应用：

@UseGuards(JwtAuthGuard, PermissionGuard)
@Permissions('user:delete')

8. 错误处理与安全审计

权限拒绝应统一抛出ForbiddenException，并记录日志用于安全审计：

if (!hasPermission) {
  this.logger.warn(`Access denied for user ${user.id} on route ${request.url}`);
  throw new ForbiddenException('Insufficient permissions');
}

9. 流程图：权限校验完整执行链

graph TD
    A[HTTP Request] --> B{JwtAuthGuard}
    B -- Authenticated --> C{RolesGuard/PermissionGuard}
    B -- Failed --> D[401 Unauthorized]
    C -- Authorized --> E[Controller Handler]
    C -- Forbidden --> F[403 Forbidden]
    E --> G[Response]
    

10. 生产环境最佳实践建议

1. 始终确保JwtAuthGuard在权限守卫之前执行
2. 使用Reflector提取元数据时注意继承与覆盖逻辑
3. 对敏感操作实施双重校验（前端+后端）
4. 避免在守卫中执行重型数据库查询，考虑缓存权限映射
5. 为不同环境配置不同的权限策略调试模式
6. 定期审查权限分配，防止权限蔓延（Privilege Creep）
7. 结合OpenAPI文档生成工具，自动标注接口所需权限
8. 实现可插拔的权限引擎，便于未来迁移到Casbin等框架
9. 对守卫进行单元测试，覆盖多角色、边界条件
10. 在CI/CD中加入权限配置扫描，防止误配