Custom route decorators

Nest được xây dựng xoay quanh một tính năng ngôn ngữ gọi là decorator. Decorator là một khái niệm quen thuộc trong nhiều ngôn ngữ lập trình phổ biến, nhưng trong thế giới JavaScript, chúng vẫn còn khá mới. Để hiểu rõ hơn cách decorator hoạt động, chúng tôi khuyến khích đọc bài viết này. Sau đây là một định nghĩa đơn giản:

An ES2016 decorator is an expression which returns a function and can take a target, name and property descriptor as arguments. You apply it by prefixing the decorator with an @ character and placing this at the very top of what you are trying to decorate. Decorators can be defined for either a class, a method or a property.

Param decorators

Nest cung cấp một tập hợp các param decorator hữu ích mà bạn có thể dùng cùng với HTTP route handler. Dưới đây là danh sách các decorator được cung cấp và object Express (hoặc Fastify) thuần mà chúng đại diện

Ngoài ra, bạn còn có thể tạo custom decorator của riêng mình. Tại sao điều này hữu ích?

Trong thế giới node.js, việc gắn property vào object request là chuyện phổ biến. Sau đó bạn tự tay trích xuất chúng trong mỗi route handler, dùng code như sau:

const user = req.user;

Để làm code của bạn dễ đọc và rõ ràng hơn, bạn có thể tạo một decorator @User() và tái sử dụng nó trong tất cả controller của mình.

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

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

Sau đó, bạn có thể đơn giản dùng nó ở bất cứ đâu phù hợp với nhu cầu của mình.

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

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

Truyền dữ liệu (Passing data)

Khi hành vi của decorator phụ thuộc vào một số điều kiện, bạn có thể dùng tham số data để truyền một argument vào factory function của decorator. Một use case cho việc này là một custom decorator trích xuất property từ object request theo key. Giả sử, ví dụ, tầng xác thực của chúng ta validate các request và gắn một user entity vào object request. User entity cho một request đã xác thực có thể trông như sau:

{
  "id": 101,
  "firstName": "Alan",
  "lastName": "Turing",
  "email": "[email protected]",
  "roles": ["admin"]
}

Hãy định nghĩa một decorator nhận vào tên của một property làm key, và trả về giá trị tương ứng nếu nó tồn tại (hoặc undefined nếu không tồn tại, hoặc nếu object user chưa được tạo).

import { createParamDecorator, ExecutionContext } 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;
});

Đây là cách bạn có thể truy cập một property cụ thể thông qua decorator @User() trong controller:

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

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

Bạn có thể dùng cùng một decorator này với các key khác nhau để truy cập các property khác nhau. Nếu object user sâu hoặc phức tạp, điều này giúp việc triển khai request handler dễ đọc và dễ dàng hơn.

Làm việc với pipe (Working with pipes)

Nest xử lý custom param decorator theo cùng cách với các decorator có sẵn (@Body(), @Param() và @Query()). Điều này có nghĩa là pipe cũng được thực thi cho các tham số được đánh dấu tùy chỉnh (trong ví dụ của chúng ta, là tham số user). Hơn nữa, bạn có thể áp dụng pipe trực tiếp cho custom decorator:

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

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

Quy tắc tương tự cũng áp dụng cho StandardSchemaValidationPipe. Nếu custom decorator của bạn gắn dữ liệu cần được validate thông qua một schema tương thích Standard Schema, hãy bật validateCustomDecorators khi cấu hình pipe.

Kết hợp decorator (Decorator composition)

Nest cung cấp một helper method để kết hợp nhiều decorator lại với nhau. Ví dụ, giả sử bạn muốn gộp tất cả decorator liên quan đến xác thực thành một decorator duy nhất. Điều này có thể thực hiện với cấu trúc sau:

import { applyDecorators } from '@nestjs/common';

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

import { applyDecorators } from '@nestjs/common';

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

Sau đó bạn có thể dùng custom decorator @Auth() này như sau:

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

Điều này có tác dụng áp dụng cả bốn decorator chỉ với một khai báo duy nhất.