Кастомные декораторы для NestJS: от простого к сложному
Введение
NestJS — стремительно набирающий популярность фрeймворк, построенный на идеях IoC/DI, модульного дизайна и декораторов. Благодаря последним, Nest имеет лаконичный и выразительный синтаксис, что повышает удобство разработки.
Декораторы или аннотации — наследники аспектов, которые позволяют декларативно описывать логику, модифицировать поведение классов, их свойств, аргументов и методов.
Технически декораторы — это просто функции, но их вызовом полностью управляет компилятор.
Важная особенность заключается в том, что в зависимости от контекста, сигнатуры аргументов будут различаться. Материалов на эту тему существует довольно много, однако мы сосредоточимся на специфике, связанной непосредственно с Nest.
Базовые декораторы
Возьмем простейший http-контроллер. Допустим, нам требуется, чтобы только определенные пользователи могли воспользоваться его методами. Для этого кейса в Nest есть встроенная функциональность гардов.
Guard — это комбинация класса, реализующего интерфейс CanActivate и декоратора @UseGuard.
@Injectable()
export class RoleGuard implements CanActivate {
canActivate(
context: ExecutionContext,
): boolean | Promise | Observable {
const request = context.switchToHttp().getRequest();
return getRole(request) === 'superuser'
}
}
@Controller()
export class MyController {
@Post('secure-path')
@UseGuards(RoleGuard)
async method() {
return
}
} Захардкоженный superuser — не самое лучшее решение, куда чаще нужны более универсальные декораторы.
Nest в этом случае предлагает использовать декоратор @SetMetadata. Как понятно из названия, он позволяет ассоциировать метаданные с декорируемыми объектами — классами или методами.
Для доступа к этим данным используется экземпляр класса Reflector, но можно и напрямую через reflect-metadata.
@Injectable()
export class RoleGuard implements CanActivate {
constructor(private reflector: Reflector) {}
canActivate(
context: ExecutionContext,
): boolean | Promise | Observable {
const role = this.reflector.get('role', context.getHandler());
const request = context.switchToHttp().getRequest();
return getRole(request) === role
}
}
@Controller()
export class MyController {
@Post('secure-path')
@SetMetadata('role', 'superuser')
@UseGuards(RoleGuard)
async test() {
return
}
} Композитные декораторы
Декораторы зачастую применяются в связках.
Обычно это обусловлено тесной связностью эффектов в каком-то бизнес-сценарии. В этом случае имеет смысл объединить несколько декораторов в один.
Для композиции можно воспользоваться утилитной функцией applyDecorators.
const Role = (role) => applyDecorators(UseGuards(RoleGuard), SetMetadata('role', role))или написать агрегатор самим:
const Role = role => (proto, propName, descriptor) => {
UseGuards(RoleGuard)(proto, propName, descriptor)
SetMetadata('role', role)(proto, propName, descriptor)
}
@Controller()
export class MyController {
@Post('secure-path')
@Role('superuser')
async test() {
return
}
}Полиморфные декораторы
Легко столкнуться с ситуацией, когда оказывается нужным задекорировать все методы класса.
@Controller()
@UseGuards(RoleGuard)
export class MyController {
@Post('secure-path')
@Role('superuser')
async test1() {
return
}
@Post('almost-securest-path')
@Role('superuser')
async test2() {
return
}
@Post('securest-path')
@Role('superuser')
async test3() {
return
}
}Такой код можно сделать чище, если повесить декоратор на сам класс. И уже внутри декоратора класса обойти прототип, применяя эффекты на все методы, как если бы декораторы были повешены на каждый метод по-отдельности.
Однако для этого обработчику необходимо различать типы объектов применения — класс и метод — и в зависимости от этого выбирать поведение.
Реализация декораторов в typescript не содержит этот признак в явном виде, поэтому его приходится выводить из сигнатуры вызова.
type ClassDecorator = (target: TFunction) => TFunction | void;
type MethodDecorator = (target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor) => TypedPropertyDescriptor | void;
type ParameterDecorator = (target: Object, propertyKey: string | symbol, parameterIndex: number) => void;
const Role = (role: string): MethodDecorator | ClassDecorator => (...args) => {
if (typeof args[0] === 'function') {
// Получение конструктора
const ctor = args[0]
// Получение прототипа
const proto = ctor.prototype
// Получение методов
const methods = Object
.getOwnPropertyNames(proto)
.filter(prop => prop !== 'constructor')
// Обход и декорирование методов
methods.forEach((propName) => {
RoleMethodDecorator(
proto,
propName,
Object.getOwnPropertyDescriptor(proto, propName),
role,
)
})
} else {
const [proto, propName, descriptor] = args
RoleMethodDecorator(proto, propName, descriptor, role)
}
} Есть вспомогательные библиотеки, которые берут на себя часть этой рутины: lukehorvat/decorator-utils, qiwi/decorator-utils.
Это несколько улучшает читаемость.
import { constructDecorator, CLASS, METHOD } from '@qiwi/decorator-utils'
const Role = constructDecorator(
({ targetType, descriptor, proto, propName, args: [role] }) => {
if (targetType === METHOD) {
RoleMethodDecorator(proto, propName, descriptor, role)
}
if (targetType === CLASS) {
const methods = Object.getOwnPropertyNames(proto)
methods.forEach((propName) => {
RoleMethodDecorator(
proto,
propName,
Object.getOwnPropertyDescriptor(proto, propName),
role,
)
})
}
},
)Совмещение в одном декораторе логики для разных сценариев дает очень весомый плюс для разработки:
вместо @DecForClass, @DecForMethood, @DecForParam получается всего один многофункциональный @Dec.
Так, например, если роль пользователя вдруг потребуется в бизнес-слое контроллера, можно просто расширить логику @Role.
Добавляем в ранее написанную функцию обработку сигнатуры декоратора параметра.
Так как подменить значение параметров вызова напрямую нельзя, createParamDecorator делегирует это вышестоящему декоратору посредством метаданных.
И далее именно декоратор метода / класса будет резолвить аргументы вызова (через очень длинную цепочку от ParamsTokenFactory до RouterExecutionContext).
// Сигнатура параметра
if (typeof args[2] === 'number') {
const [proto, propName, paramIndex] = args
createParamDecorator((_data: unknown, ctx: ExecutionContext) => {
return getRole(ctx.switchToHttp().getRequest())
})()(proto, propName, paramIndex)
}Также стоит отметить, что при помощи метадаты можно решать разные интересные кейсы, например, вводить ограничения для повторяемости или сочетаемости аннотаций.
Предположим, нам потребовалось ограничение размера запроса, и соответствующий декоратор повесили дважды. Какому значению доверять?
Без знания логики компилятора возникает неопределенность. Правильнее, наверное, было бы бросить ошибку.
class SomeController {
@RequestSize(1000)
@RequestSize(5000)
@Post('foo')
method(@Body() body) {
}
}Вот другой пример: необходимо ограничить работу методов контроллера отдельными портами. Здесь, скорее, требуется не затирать предыдущие значения, а добавлять новые к имеющимся.
class SomeController {
@Port(9092)
@Port(8080)
@Post('foo')
method(@Body() body) {
}
}Схожая ситуация возникает с ролевой моделью.
class SomeController {
@Post('securest-path')
@Role('superuser')
@Role('usert')
@Role('otheruser')
method(@Role() role) {
}
}Обобщая рассуждения, реализация декоратора для последнего примера с использованием reflect-metadata и полиморфного контракта может иметь вид:
import { ExecutionContext, createParamDecorator } from '@nestjs/common'
import { constructDecorator, METHOD, PARAM } from '@qiwi/decorator-utils'
@Injectable()
export class RoleGuard implements CanActivate {
canActivate(context: ExecutionContext): boolean | Promise {
const roleMetadata = Reflect.getMetadata(
'roleMetadata',
context.getClass().prototype,
)
const request = context.switchToHttp().getRequest()
const role = getRole(request)
return roleMetadata.find(({ value }) => value === role)
}
}
const RoleMethodDecorator = (proto, propName, decsriptor, role) => {
UseGuards(RoleGuard)(proto, propName, decsriptor)
const meta = Reflect.getMetadata('roleMetadata', proto) || []
Reflect.defineMetadata(
'roleMetadata',
[
...meta, {
repeatable: true,
value: role,
},
],
proto,
)
}
export const Role = constructDecorator(
({ targetType, descriptor, proto, propName, paramIndex, args: [role] }) => {
if (targetType === METHOD) {
RoleMethodDecorator(proto, propName, descriptor, role)
}
if (targetType === PARAM) {
createParamDecorator((_data: unknown, ctx: ExecutionContext) =>
getRole(ctx.switchToHttp().getRequest()),
)()(proto, propName, paramIndex)
}
},
) Макродекораторы
Nest спроектирован таким образом, что его собственные декораторы удобно расширять и переиспользовать. На первый взгляд довольно сложные кейсы, к примеру, связанные с добавлением поддержки новых протоколов, реализуются парой десятков строк обвязочного кода. Так, стандартный @Controller можно «обсахарить»
для работы с JSON-RPC.
Не будем останавливаться на этом подробно, это слишком бы далеко вышло за формат этой статьи, но покажу основную идею: на что способны декораторы, в сочетании с Nest.
import {
ControllerOptions,
Controller,
Post,
Req,
Res,
HttpCode,
HttpStatus,
} from '@nestjs/common'
import { Request, Response } from 'express'
import { Extender } from '@qiwi/json-rpc-common'
import { JsonRpcMiddleware } from 'expressjs-json-rpc'
export const JsonRpcController = (
prefixOrOptions?: string | ControllerOptions,
): ClassDecorator => {
return (target: TFunction) => {
const extend: Extender = (base) => {
@Controller(prefixOrOptions as any)
@JsonRpcMiddleware()
class Extended extends base {
@Post('/')
@HttpCode(HttpStatus.OK)
rpc(@Req() req: Request, @Res() res: Response): any {
return this.middleware(req, res)
}
}
return Extended
}
return extend(target as any)
}
}
Далее необходимо извлечь @Req() из rpc-method в мидлваре, найти совпадение с метой, которую добавил декоратор @JsonRpcMethod.
Готово, можно использовать:
import {
JsonRpcController,
JsonRpcMethod,
IJsonRpcId,
IJsonRpcParams,
} from 'nestjs-json-rpc'
@JsonRpcController('/jsonrpc/endpoint')
export class SomeJsonRpcController {
@JsonRpcMethod('some-method')
doSomething(
@JsonRpcId() id: IJsonRpcId,
@JsonRpcParams() params: IJsonRpcParams,
) {
const { foo } = params
if (foo === 'bar') {
return new JsonRpcError(-100, '"foo" param should not be equal "bar"')
}
return 'ok'
}
@JsonRpcMethod('other-method')
doElse(@JsonRpcId() id: IJsonRpcId) {
return 'ok'
}
}
Вывод
Декораторы Nest адаптируются к широкому спектру прикладных задач. В них легко переносится утилитная и бизнесовая логика. Их несложно расширять, композировать, совмещая несколько сценариев. И в этом, без сомнения, одна из сильных сторон фреймворка.
Однако важно помнить, что синтаксис декораторов сегодня все еще является экспериментальным, а их чрезмерное использование может дать обратный эффект, и сделать ваш код более запутанным.
