守卫 Guards

Guard 具有单一职责。它们根据运行时存在的某些条件（如权限、角色、ACL 等）确定给定请求是否由路由处理程序处理。这通常称为授权。授权（及其通常与之协作的身份验证）通常由传统 Express 应用程序中的 中间件 处理。中间件是身份验证的不错选择，因为诸如令牌验证和将属性附加到 request 对象之类的事情与特定路由上下文（及其元数据）没有紧密联系。

但中间件本质上是愚蠢的。它不知道在调用 next() 函数后将执行哪个处理程序。另一方面，Guard 可以访问 ExecutionContext 实例，因此确切知道接下来要执行什么。它们的设计与异常过滤器、管道和拦截器非常相似，可让您在请求/响应周期的正确位置插入处理逻辑，并以声明方式进行。这有助于保持代码简洁和声明性。

授权守卫

如上所述，授权 是 Guard 的一个很好的用例，因为只有当调用者（通常是特定的经过身份验证的用户）具有足够的权限时，特定路由才可用。我们现在将构建的 AuthGuard 假设一个经过身份验证的用户（因此，令牌附加到请求标头）。它将提取并验证令牌，并使用提取的信息来确定请求是否可以继续。

// auth.guard
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common'
import { Observable } from 'rxjs'

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    const request = context.switchToHttp().getRequest()
    return validateRequest(request)
  }
}

validateRequest() 函数中的逻辑可以根据需要简单或复杂。此示例的主要目的是展示守卫如何融入请求/响应周期。

每个守卫都必须实现一个 canActivate() 函数。此函数应返回一个布尔值，指示当前请求是否被允许。它可以同步或异步返回响应（通过 Promise 或 Observable）。Nest 使用返回值来控制下一个操作：

• 如果返回 true，则将处理请求。
• 如果返回 false，Nest 将拒绝该请求。

执行上下文

canActivate() 函数接受一个参数，即 ExecutionContext 实例。ExecutionContext 继承自 ArgumentsHost。我们之前在异常过滤器章节中看到过 ArgumentsHost。在上面的示例中，我们只是使用之前在 ArgumentsHost 上定义的相同辅助方法来获取对 Request 对象的引用。您可以参考 异常过滤器 章节的 Arguments host 部分，了解有关此主题的更多信息。

通过扩展 ArgumentsHost，ExecutionContext 还添加了几个新的辅助方法，这些方法提供有关当前执行过程的更多详细信息。这些详细信息有助于构建更通用的保护程序，这些保护程序可以跨广泛的控制器、方法和执行上下文工作。在此处 了解有关 ExecutionContext 的更多信息。

基于角色的身份验证

让我们构建一个功能更强大的防护器，仅允许具有特定角色的用户访问。我们将从一个基本的防护器模板开始，并在接下来的部分中对其进行构建。目前，它允许所有请求继续进行：

// roles.guard
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common'
import { Observable } from 'rxjs'

@Injectable()
export class RolesGuard implements CanActivate {
  canActivate(
    context: ExecutionContext,
  ): boolean | Promise<boolean> | Observable<boolean> {
    return true
  }
}

绑定保护

与管道和异常过滤器一样，保护可以是控制器范围、方法范围或全局范围。下面，我们使用 @UseGuards() 装饰器设置控制器范围的保护。此装饰器可以采用单个参数或逗号分隔的参数列表。这样，您只需一个声明即可轻松应用适当的保护集。

@Controller('cats')
@UseGuards(RolesGuard)
export class CatsController {}

上面，我们传递了 RolesGuard 类（而不是实例），将实例化的责任留给框架并启用依赖注入。与管道和异常过滤器一样，我们也可以传递一个就地实例：

@Controller('cats')
@UseGuards(new RolesGuard())
export class CatsController {}

上面的构造将守卫附加到此控制器声明的每个处理程序。如果我们希望守卫仅应用于单个方法，我们将 @UseGuards() 装饰器应用于方法级别。

为了设置全局守卫，请使用 Nest 应用程序实例的 useGlobalGuards() 方法：

const app = await NestFactory.create(AppModule)
app.useGlobalGuards(new RolesGuard())

全局保护用于整个应用，适用于每个控制器和每个路由处理程序。就依赖注入而言，从任何模块外部注册的全局保护（使用上述示例中的 useGlobalGuards()）无法注入依赖项，因为这在任何模块的上下文之外完成。为了解决这个问题，您可以使用以下构造直接从任何模块设置保护：

import { Module } from '@nestjs/common'
import { APP_GUARD } from '@nestjs/core'

@Module({
  providers: [
    {
      provide: APP_GUARD,
      useClass: RolesGuard,
    },
  ],
})
export class AppModule {}

import { Reflector } from '@nestjs/core'

export const Roles = Reflector.createDecorator<string[]>()

// cats.controller
@Post()
@Roles(['admin'])
async create(@Body() createCatDto: CreateCatDto) {
  this.catsService.create(createCatDto);
}

// roles.guard
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common'
import { Reflector } from '@nestjs/core'
import { Roles } from './roles.decorator'

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

  canActivate(context: ExecutionContext): boolean {
    const roles = this.reflector.get(Roles, context.getHandler())
    if (!roles) {
      return true
    }
    const request = context.switchToHttp().getRequest()
    const user = request.user
    return matchRoles(roles, user.roles)
  }
}

{
  "statusCode": 403,
  "message": "Forbidden resource",
  "error": "Forbidden"
}

throw new UnauthorizedException()