自定义路由装饰器 Custom route decorators

Nest 是围绕一种名为**装饰器**的语言功能构建的。装饰器是许多常用编程语言中众所周知的概念，但在 JavaScript 世界中，它们仍然相对较新。为了更好地理解装饰器的工作原理，这里有一个简单的定义：

我们建议阅读这篇文章。

ES2016 装饰器是一个返回函数的表达式，可以接受目标、名称和属性描述符作为参数。通过在装饰器前加上 @ 字符并将其放在要装饰的内容的最顶部来应用它。可以为类、方法或属性定义装饰器。

参数装饰器

Nest 提供了一组有用的参数装饰器，您可以将其与 HTTP 路由处理程序一起使用。下面是提供的装饰器和它们所代表的普通 Express（或 Fastify）对象的列表


`@Request(), @Req()`	`req`
`@Response(), @Res()`	`res`
`@Next()`	`next`
`@Session()`	`req.session`
`@Param(param?: string)`	`req.params` / `req.params[param]`
`@Body(param?: string)`	`req.body` / `req.body[param]`
`@Query(param?: string)`	`req.query` / `req.query[param]`
`@Headers(param?: string)`	`req.headers` / `req.headers[param]`
`@Ip()`	`req.ip`
`@HostParam()`	`req.hosts`

此外，您还可以创建自己的自定义装饰器。这有什么用呢？

在 node.js 世界中，将属性附加到request对象是一种常见的做法。然后，您可以在每个路由处理程序中手动提取它们，使用如下代码：

const user = req.user

为了使您的代码更具可读性和透明度，您可以创建一个 @User() 装饰器并在所有控制器中重复使用它。

user.decorator

import { ExecutionContext, createParamDecorator } from '@nestjs/common'

export const User = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest()
    return request.user
  },
)

然后，您只需在符合您要求的地方使用它即可。

@Get()
async findOne(@User() user: UserEntity) {
  console.log(user);
}

传递数据

当装饰器的行为取决于某些条件时，您可以使用 data 参数将参数传递给装饰器的工厂函数。一个用例是自定义装饰器，它按键从请求对象中提取属性。例如，假设我们的身份验证层验证请求并将用户实体附加到请求对象。经过身份验证的请求的用户实体可能如下所示：

json

{
  "id": 101,
  "firstName": "Alan",
  "lastName": "Turing",
  "email": "alan@email.com",
  "roles": ["admin"]
}

让我们定义一个装饰器，以属性名称作为键，如果存在则返回关联值（如果不存在则返回未定义，或者如果尚未创建用户对象）。

user.decorator

import { ExecutionContext, createParamDecorator } from '@nestjs/common'

export const User = createParamDecorator(
  (data: string, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest()
    const user = request.user

    return data ? user?.[data] : user
  },
)

import { createParamDecorator } from '@nestjs/common'

export const User = createParamDecorator((data, ctx) => {
  const request = ctx.switchToHttp().getRequest()
  const user = request.user

  return data ? user && user[data] : user
})

下面展示了如何通过控制器中的 @User() 装饰器访问特定属性：

@Get()
async findOne(@User('firstName') firstName: string) {
  console.log(`Hello ${firstName}`);
}

您可以使用同一个装饰器和不同的键来访问不同的属性。如果 user 对象很深或很复杂，这可以使请求处理程序实现更容易、更易读。

提示

对于 TypeScript 用户，请注意 createParamDecorator<T>() 是泛型。这意味着您可以明确强制执行类型安全，例如 createParamDecorator<string>((data, ctx) => ...)。或者，在工厂函数中指定参数类型，例如 createParamDecorator((data: string, ctx) => ...)。如果省略两者，则 data 的类型将为 any。

使用管道

Nest 以与内置装饰器相同的方式处理自定义参数装饰器（@Body()、@Param() 和 @Query()）。这意味着管道也会针对自定义注释参数执行（在我们的示例中为user参数）。此外，您可以将管道直接应用于自定义装饰器：

@Get()
async findOne(
  @User(new ValidationPipe({ validateCustomDecorators: true }))
  user: UserEntity,
) {
  console.log(user);
}

提示

请注意，validateCustomDecorators 选项必须设置为 true。默认情况下，ValidationPipe 不会验证使用自定义装饰器注释的参数。

装饰器组合

Nest 提供了一种辅助方法来组合多个装饰器。例如，假设您想将所有与身份验证相关的装饰器组合成一个装饰器。这可以通过以下构造来完成：

// auth.decorator
import { applyDecorators } from '@nestjs/common'

export function Auth(...roles: Role[]) {
  return applyDecorators(
    SetMetadata('roles', roles),
    UseGuards(AuthGuard, RolesGuard),
    ApiBearerAuth(),
    ApiUnauthorizedResponse({ description: 'Unauthorized' }),
  )
}

然后，您可以按如下方式使用此自定义 @Auth() 装饰器：

@Get('users')
@Auth('admin')
findAllUsers() {}

这具有通过单个声明应用所有四个装饰器的效果。

Warning

@nestjs/swagger 包中的 @ApiHideProperty() 装饰器不可组合，无法与 applyDecorators 函数正常工作。