Блог компании qiwi

Введение

NestJS стремительно набирающий популярность фрeймворк, построенный на идеях IoC/DI, модульного дизайна и декораторов. Благодаря последним, Nest имеет лаконичный и выразительный синтаксис, что повышает удобство разработки.

Декораторы или аннотации наследники аспектов, которые позволяют декларативно описывать логику, модифицировать поведение классов, их свойств, аргументов и методов.
Технически декораторы это просто функции, но их вызовом полностью управляет компилятор.
Важная особенность заключается в том, что в зависимости от контекста, сигнатуры аргументов будут различаться. Материалов на эту тему существует довольно много, однако мы сосредоточимся на специфике, связанной непосредственно с Nest.

Базовые декораторы

Возьмем простейший http-контроллер. Допустим, нам требуется, чтобы только определенные пользователи могли воспользоваться его методами. Для этого кейса в Nest есть встроенная функциональность гардов.
Guard это комбинация класса, реализующего интерфейс CanActivate и декоратора @UseGuard.

@Injectable()export class RoleGuard implements CanActivate {  canActivate(    context: ExecutionContext,  ): boolean | Promise<boolean> | Observable<boolean> {    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<boolean> | Observable<boolean> {    const role = this.reflector.get<string>('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 = <TFunction extends Function>(target: TFunction) => TFunction | void;type MethodDecorator = <T>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | 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<boolean> {    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 <TFunction extends Function>(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 адаптируются к широкому спектру прикладных задач. В них легко переносится утилитная и бизнесовая логика. Их несложно расширять, композировать, совмещая несколько сценариев. И в этом, без сомнения, одна из сильных сторон фреймворка.
Однако важно помнить, что синтаксис декораторов сегодня все еще является экспериментальным, а их чрезмерное использование может дать обратный эффект, и сделать ваш код более запутанным.

Проблемы, которые мы решали

Нет единых стандартов версионирования

В ходе отладки ушатываем тестовую базу

Методы DAO не покрываются тестами, не проверяются в CI

Неизоморфность сред

Тяжелый и ломучий процесс наката в продакшен

Как можно делать, чтобы было хорошо

Отладка на локальной БД в докер-контейнере

FROM postgres:12.3ADD init.sql /docker-entrypoint-initdb.d/

• Пользователя-владельца схемы и саму схему.
• Пользователя приложения с грантом на использование схемы.
• Требуемые EXTENSIONs

create role my_awesome_servicewith login password *** NOSUPERUSER inherit CREATEDB CREATEROLE NOREPLICATION;create tablespace my_awesome_service owner my_awesome_service location '/u01/postgres/my_awesome_service_data';create schema my_awesome_service authorization my_awesome_service;grant all on schema my_awesome_service to my_awesome_service;grant usage on schema my_awesome_service to my_awesome_service;alter role my_awesome_service set search_path to my_awesome_service,pg_catalog, public;create user my_awesome_service_app with LOGIN password *** NOSUPERUSER inherit NOREPLICATION;grant usage on schema my_awesome_service to my_awesome_service_app;create extension if not exists "uuid-ossp";

db:    docker container rm -f my_awesome_service_db || true    docker build -t my_awesome_service_db docker/db/.    docker run -d --name my_awesome_service_db -p 5433:5432 my_awesome_service_db

Версионирование changesetов с помощью чего-то стандартного для индустрии

• DDL-структуру объектов бд (create table).
• DML-содержимое таблиц-справочников (insert, update).
• DCL-гранты для УЗ Приложения (grant select, insert on ...).

create table my_awesome_service.ref_customer_type(    customer_type_code    varchar not null,    customer_type_description varchar not null,    constraint ref_customer_type_pk primary key (customer_type_code)); alter table my_awesome_service.ref_customer_type    add constraint customer_type_code_ck check ( (customer_type_code)::text = upper((customer_type_code)::text) );

grant select on all tables in schema my_awesome_service to ru_svc_qw_my_awesome_service_app;grant insert, update on my_awesome_service.some_entity to ru_svc_qw_my_awesome_service_app;

insert into my_awesome_service.ref_customer_type (customer_type_code, customer_type_description)values ('INDIVIDUAL', 'Физ. лицо');insert into my_awesome_service.ref_customer_type (customer_type_code, customer_type_description)values ('LEGAL_ENTITY', 'Юр. лицо');insert into my_awesome_service.ref_customer_type (customer_type_code, customer_type_description)values ('FOREIGN_AGENCY', 'Иностранное юр. лицо');

insert into my_awesome_service.some_entity_state (state_type_code, state_data, some_entity_id)values ('BINDING_IN_PROGRESS', '{}', 1);

drop table my_awesome_service.ref_customer_type;

databaseChangeLog: - changeSet:     id: 1     author: "mr.awesome"     changes:       - sqlFile:           path: db/changesets/001_init/0_ddl.sql       - sqlFile:           path: db/changesets/001_init/1_dcl.sql       - sqlFile:           path: db/changesets/001_init/2_dml_refs.sql     rollback:       sqlFile:         path: db/changesets/001_init/rollback.sql - changeSet:     id: 2     author: "mr.awesome"     context: dev     changes:       - sqlFile:           path: db/changesets/001_init/3_dml_dev.sql

Интеграция системы миграций БД в фазу запуска приложения

1. На тестовой БД патчсеты 001, 002, 003.
2. Погромист наразрабатывал патчсеты 004, 005 и не деплоил приложение в тест.
3. Деплоим в тест. Докатываются патчсеты 004, 005.

spring:  liquibase:    enabled: true    database-change-log-lock-table: "databasechangeloglock"    database-change-log-table: "databasechangelog"    user: ${secret.liquibase.user:}    password: ${secret.liquibase.password:}    url: "jdbc:postgresql://my.test.db:5432/my_awesome_service?currentSchema=my_awesome_service"

DAO тесты на CI-этапе verify

@Test@Transactional@Rollbackfun `create cheque positive flow`() {      jdbcTemplate.update(       "insert into my_awesome_service.some_entity(inn, registration_source_code)" +               "values (:inn, 'QIWICOM') returning some_entity_id",       MapSqlParameterSource().addValue("inn", "526317984689")   )   val insertedCheque = chequeDao.addCheque(cheque)   val resultCheque = jdbcTemplate.queryForObject(       "select cheque_id from my_awesome_service.cheque " +               "order by cheque_id desc limit 1", MapSqlParameterSource(), Long::class.java   )   Assert.assertTrue(insertedCheque.isRight())   Assert.assertEquals(insertedCheque, Right(resultCheque))}

1. На билдагенте может быть потенциально занят стандартный порт PostgreSQL 5432 или любой статичный. Мало ли, кто-то не потушил контейнер с базой после завершения тестов.
2. Из этого вторая задача: нужно тушить контейнер после завершения тестов.

@TestConfigurationpublic class DatabaseConfiguration {   @Bean   GenericContainer postgreSQLContainer() {       GenericContainer container = new GenericContainer("my_awesome_service_db")               .withExposedPorts(5432);       container.start();       return container;   }   @Bean   @Primary   public DataSource onlineDbPoolDataSource(GenericContainer postgreSQLContainer) {       return DataSourceBuilder.create()               .driverClassName("org.postgresql.Driver")               .url("jdbc:postgresql://localhost:"                       + postgreSQLContainer.getMappedPort(5432)                       + "/postgres")               .username("my_awesome_service_app")               .password("my_awesome_service_app_pwd")               .build();   }       @Bean   @LiquibaseDataSource   public DataSource liquibaseDataSource(GenericContainer postgreSQLContainer) {       return DataSourceBuilder.create()               .driverClassName("org.postgresql.Driver")               .url("jdbc:postgresql://localhost:"                       + postgreSQLContainer.getMappedPort(5432)                       + "/postgres")               .username("my_awesome_service")               .password("my_awesome_service_app_pwd")               .build();   }

Kubernetes это ответ! А какой был ваш вопрос?

• Билдагентов тимсити на всех не хватает.
• Лицензия стоит денег.
• Настройки виртуалок билдагентов делаются по старинке, через репозитории с конфигами и puppet.
• Доступы с билдагентов до целевых сетей пропиливать надо по старинке.
• Логины-пароли для наката изменений на базу тоже хранятся по старинке.

• Генерация проекта.
• Деплой.
• Доставку конфигов и секретов.
• Доступы.
• Логирование и доставка логов в ELK.

Теперь мы имеем:

• Версионирование ченджсетов.
• Проверяем их на выполнимость update rollback.
• Пишем тесты на DAO. Бывает даже следуем TDD: запускаем отладку DAO с помощью тестов. Тесты выполняются на свежеподнятой БД в TestContainers.
• Запускаем локально БД в докере на стандартном порту. Проводим отладку, смотрим, что осталось в БД. При необходимости можем управлять локальной БД вручную.
• Накатываем в тест и проводим авторелиз патчсетов стандартным пайплайном в teamcity, по аналогии с микросервисами. Пайплайн является дочерним для микросервиса, которому принадлежит БД.
• Не храним креды от БД в тимсити. И не заботимся о доступах с виртуалок-билдагентов.