Разработка веб приложений. #3 - Backend, Nest.

Первая статья — здесь.
Вторая статья — здесь.

:(
1. Надеюсь у всех все хорошо, насколько это возможно.
2. По самым разным причинам, я эту статью писал месяцев 7… Ну как писал… Часть написал еще в феврале и оставил статью пылиться. Я решил закончить давно начатое, надеюсь статья придется вам по вкусу и вы узнаете для себя хоть что-то новое. Погнали.

TypeScript
Конечно увидев Nest, у меня (наверное не только у меня) появились сомненения, ведь TS это как бы JS, но масштаб погружения все таки намного глубже, требуются совсем другого уровня знания. Так думал я перед тем как начать изучать Nest. Я даже вспомнил, что уже давно купил себе этот курс, но так и не начал его изучать (все таки на момент написания статьи, уже начал).

На самом деле, не особо и нужны все эти курсы, их можно покупать максимум для того, чтобы смотреть как кино. Но очень важно их смотреть, если вы выучили хотя бы базу. Это поможет вам критически оценивать то, что говорит в курсе автор. На примере курса по Express я могу сказать, что очень часто автор дает крайне сомнительную информацию, которая иногда может сильно навредить, заложив фундаментельно неправильные знания в голову падавана.

Так как же я изучаю TS? Да просто начинаю что-то делать! TS прекрасно подходит для написания библиотечек на Node. Например сейчас я разрабатываю компоненты на Node, Vue 3, Vite и TS. Это самый современный и крутой подход на сегодняшний день для написания библиотек на Vue. Если вдруг у коммьюнити будет интерес, соберем энную сумму донатов и я напишу подробную статейку по этой теме, выложу исходники бойлерплейта и покажу схему сборки библиотеки от начала, до продакшена на какой-нибудь NPM.

TypeScript типизация
Конечно первое что слышат люди при изучении TS — это то, что он решает ошибки типов данных, которым так страдает, в нашем случае JS. Да, это действительно так. Сейчас на основной работе мы работаем на Vue 2 без TS, так вот там частенько проблемы с типами встречаются. Деклоративность в коде это неплохо, а иногда даже хорошо. Мы говорим коду, что именно должна вернуть функция и код такой — окей не вопрос, но если ты падла такая попробуешь вернуть что-то другое, пойдешь нахер.

Это не так явно бросается в глаза, когда вы просто указываете тип переменных. Ага — это у нас строка, это массив, это объект и т.д… Конечно это помогает, но куда больший профит от типизации появляется в несколько более сложных примерах типизации. В примере ниже, я создал конфигурационную функцию для одной опенсурс библиотеки и указал что функция возвращает промис с типом MailerOptions, однако пытаюсь вернуть строку и TS мне выдает ошибку.



Конечно я могу не указывать тип возвращаемых данных, но зачем тогда использовать TS? Да и почему не привыкать к типизации? Ведь всегда можно открыть дтску и посмотреть какие данные мы должны вернуть в функции… В моем случае, функция должна вернуть эти данные.



Все предельно очевидно, видно что обязательно, а что нет. Виден и тип данных. Но даже если вы ошибетесь, TS вам об этом расскажет. Более того, я использую phpStorm и эта IDE просто не даст мне вернуть что-то, что не описано в интерфейсе библиотеки. Автокомплит с типизацией это очень мощная штука.

TypeScript панацея?
Не думаю что я могу делать какие-то глобальные выводы, ввиду моей пока что еще не очень большой работы на TS, но я считаю, если вы пишите на ноде, то TS сегодня очень и очень мастхев. Backend, библиотеки или SPA на условном Vue — я всегда буду выбирать TS вместо нативного JS.

Nest.js
Ну вот и дошли до Nest… Короче Nest под капотом использует Express… :) Конечно может использовать и Fastify, но блин… Я ушел с Express на Nest, а Nest использует Express. Но не спешите с выводами. Express он использует да, но при этом решает множество проблем, с которыми вы рано или поздно столкнетесь при масштабировании вашего приложения, если бы вы работали на Express.

При этом, Nest не является оберткой или микрофреймворком, это самый настоящий фреймворк. Если кратко, то Nest собрал в себе почти все лучшие практики по организации лучшего на данный момент бекенда на ноде. Nest использует TS (хотя может работать в режиме чистого JS, но смысла в этом нет), почти вся его концепция завязана на DI и декораторах.

Nest.js — Dependency Injection
Это не очень простая техника, в которой один объект или класс, получает другой объект или класс как зависимость и уже не может работать без него. Иными словами, функционал класса теперь требует эту зависимость. Это довольно часто вызывает проблему циклических зависимостей, когда классу пользователей нужен класс заказов, а классу заказов нужен класс пользователей. Вы можете получить в терминале ошибки, на этот случай у Nest из коробки идет решение. На этой технике строится весь backend, вы будете писать модули и внутри этих модулей делать DI, а так же вы почти наверняка будете делать DI модуля, внутрь другого модуля и т.д.

Nest.js — Декораторы
Это такая штука, с помощью которой вы можете добавить классу некий функционал. В Nest зачастую требуется писать свои декораторы. Конечно все зависит от задачи, но написание декораторов не является большой проблемой. Есть документация и гугл, со временем появляется все больше статей где показывают как работают декораторы внутри Nest.

Например в моем приложении я использую декораторы для проверок ролей и пермишенов пользователей.

Nest.js — саммари
Вообще у Nest из коробки идет все что нужно для организации бека. Интерцепторы для обработки разного типа ошибок, пайпы для трансформации и валидации данных, гарды для защиты роутов и т.д. Документация исключительно дружелюбна, а там где ее не хватает, есть гугл. Так же Nest постепенно обживается экосистемой различных модулей. Так например есть свой модуль для работы с почтой, есть модуль для локализации построенный на i18n и т.д. Я эти модули уже применил на своих проектах и подключение их в проект не намного тяжелее установки дополнений из модстора… :) Шутка, но если погрузиться в контекст работы Nest, то не такая уж и шутка. Если бы вы работали на Express, все вышеописанное и многое другое, вам пришлось бы писать самому.

Nest.js — миграция
Хорош поносословить, начну показывать во что в итоге превратился мой модуль для сотрудников. На данный момент он состоит из 8-ми частей — например модуль сотрудников, модуль авторизации, модули ролей и прав сотрудников и т.д… Я покажу лишь кусочек модуля авторизации:

ДИСКЛЕЙМЕР: Часть кода из примеров ниже я либо упростил, либо вырезал для примера.

Для начала главный файл модуля, куда я импортирую коллекции Mongo, а так же другие модули, которые я так или иначе применяю в модуле авторизации. А значит в силу вступает DI. Так же я регистрирую провайдеры, в которых будет описана бизнес логика

@Module({
  imports: [
    MongooseModule.forFeature([
      {
        name: Staff.name,
        schema: StaffSchema,
        collection: 'staffs',
      },
      {
        name: StaffToken.name,
        schema: StaffTokenSchema,
        collection: 'staffsTokens',
      },
      {
        name: StaffRoles.name,
        schema: StaffRolesSchema,
        collection: 'staffsRoles',
      },
    ]),
    JwtModule.registerAsync({
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: getJWTConfig,
    }),
    StaffModule,
    StaffRolesModule,
    StaffPermissionsModule,
    StaffLogsModule,
    ConfigModule,
    MailModule,
    PassportModule,
  ],
  providers: [
    StaffAuthValidateService,
    StaffAuthPasswordService,
    StaffAuthTokenService,
    StaffAuthSignUpService,
    StaffAuthSignInService,
    StaffAuthSignOutService,
    StaffAuthEmailService,
    StaffJwtStrategy,
  ],
  controllers: [
    StaffAuthCommonController,
    StaffAuthSelfPasswordController,
    StaffAuthSelfEmailController,
    StaffAuthOneEmailController,
  ],
})
export class StaffAuthModule {}

Как видите, провайдеров и контроллеров набралось прилично. Дело в том, что я пишу довольно обширную систему аутентификации и авторизации пользователей в свою систему управления сайтом. О ней можно написать отдельную статью, возможно, когда-нибудь это и случится.

Так вот, по поводу большого кол-ва провайдеров и контроллеров — я предпочитаю отделять мух. Писать довольно большую бизнес-логику в одном service-файле, приведет к лапшекоду, в моем случае каждый сервис отвечает за отведенную ему часть бизнес-логики по работе с аутентификацией и авторизацией сотрудников.

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

В прошлой статье я выложил код своего модуля авторизации на Express.js. Там в самом начале я писал валидацию. Nest.js предоставляет возможность вынести валидацию в DTO классы. Вот пример моей валидации для аутентификации сотрудника:

export class StaffAuthSignInDto {
  @ApiProperty({
    example: 'example@example.com',
    description: 'Email сотрудника',
  })
  @IsNotEmpty({ message: 'staff.ERR_EMAIL_IS_EMPTY' })
  @IsEmail({}, { message: 'staff.ERR_EMAIL_INVALID' })
  email: string;

  @ApiProperty({
    example: '12346789',
    description: 'Пароль сотрудника',
    minimum: 8,
  })
  @IsNotEmpty({ message: 'staff.ERR_PASSWORD_IS_EMPTY' })
  @IsString({ message: 'staff.ERR_PASSWORD_IS_STRING' })
  @MinLength(8, { message: 'staff.ERR_PASSWORD_MIN_LENGTH' })
  password: string;
}

@IsNotEmpty — это те самые декораторы, о которых я уже писал ранее. Только это не самописные декораторы, а коробочные из библиотеки class-validator. В объекте message вы видите локали (что-то вроде лексиконов в MODx). В моем бекенде есть мультиязычность, за это отвечает модуль nestjs-i18n.

Опять же, смотрим на код из прошлой статьи, ту часть где я пытаюсь аутентифицировать сотрудника:

// Trying to login
const staff = await Staff.findOne({ email: normalizedEmail });

...и там дальше идут провеки, работа с JWT и т.д.

Аутентификация и авторизация теперь разбита на две части. Сначала покажу авторизацию.

@Injectable()
export class StaffAuthSignInService {
  constructor(
    private readonly staffAuthValidateService: StaffAuthValidateService,
    private readonly staffAuthTokenService: StaffAuthTokenService,
  ) {}

  /**
   * @description Sign in staff and register JWT token with payloads
   * @param staffAuthSignInDto {StaffAuthSignInDto}
   */
  async signIn(staffAuthSignInDto: StaffAuthSignInDto): Promise<object> {
    const staff = await this.staffAuthValidateService.validateStaff(
      staffAuthSignInDto.email,
      staffAuthSignInDto.password,
    );

    const { id, email, username, avatar, role } = staff;
    const payload = { id, email, username, avatar, role };

    const accessToken = await this.staffAuthTokenService.generateAccessToken(payload);
    const refreshToken = await this.staffAuthTokenService.generateRefreshToken(payload);
    const foundToken = await this.staffAuthTokenService.findStaffTokenById(payload.id);

    if (foundToken) {
      await this.staffAuthTokenService.updateRefreshToken(foundToken.id, refreshToken);
      return {
        accessToken,
        refreshToken,
        payload,
        staff,
      };
    }

    await this.staffAuthTokenService.createRefreshToken(refreshToken, payload.id);
    return {
      accessToken,
      refreshToken,
      payload,
      staff,
    };
  }
}

Сам метод аутентификации теперь находится в сервисе по валидации сотрудника. Все как завещали отцы, описывающие разницу авторизации и аутентификации:

@Injectable()
export class StaffAuthValidateService {
  constructor(
    private readonly staffService: StaffService,
    @InjectModel(Staff.name) private readonly staffModel: Model<Staff>,

    @Inject(forwardRef(() => StaffAuthPasswordService))
    private staffAuthPasswordService: StaffAuthPasswordService,
  ) {}

  /**
   * @description Validate staff candidate to sign in
   * @param email {string}
   * @param password {string}
   */
  async validateStaff(email: string, password: string): Promise<Staff> {
    const staff = await this.staffService.getOneByEmail(email, 'password');

    if (
      !staff ||
      staff.deleted ||
      !(await this.staffAuthPasswordService.comparePasswords(password, staff.password))
    ) {
      throw new HttpException(
        { key: 'auth.ERR_INCORRECT_EMAIL_OR_PASSWORD' },
        HttpStatus.UNAUTHORIZED,
      );
    }

    if (!staff.active) {
      throw new HttpException({ key: 'staff.ERR_NOT_ACTIVATED' }, HttpStatus.UNAUTHORIZED);
    }

    if (staff.blocked) {
      throw new HttpException({ key: 'staff.ERR_IS_BLOCKED' }, HttpStatus.UNAUTHORIZED);
    }

    return staff;
  }
}

Обратите внимание, я вызываю методы одного сервиса аутентификационного модуля, в другом. Но в последнем коде, вызывается сервис сотрудников — staffService. Это и есть DI. Я покажу кусочек кода этого сервиса:

async getOneByEmail(email: string, select?: string): Promise<Staff> {
  const staff = await this.staffModel
    .findOne({ email: email })
    .select(`+${select}`)
    .populate({ path: 'role', select: '', model: this.staffRoleModel })
    .exec();

  if (!staff) {
    throw new HttpException(
      { key: 'auth.ERR_INCORRECT_EMAIL_OR_PASSWORD' },
      HttpStatus.UNAUTHORIZED,
    );
  }

  return staff;
}

Вызов этой цепочки методов различных сервисов, избавит нас от необходимости постоянно писать какие-либо проверки. Так что, если возникнут проблемы с аутентификацией сотрудника, это решит либо метод getOneByEmail, либо validateStaff, последний уж точно не пропустит пользователя, если первый не справился с проверкой. Но будьте осторожней с асинхронщиной. К слову, в методе getOneByEmail вызывается модель модуля ролей пользователя. Это тоже DI.

Ну и кусочек контроллера, который создает endpoint для аутентификации:

@StaffAuthDecorator(
  {
    apiOperation: {
      summary: 'Аутентификация сотрудника.',
      description: 'Endpoint для аутентификация сотрудника.',
    },
    apiResponse: {
      status: HttpStatus.OK,
    },
  },
  { statusCode: HttpStatus.OK },
)
@Post('signIn')
async signIn(@Body() staffAuthSignInDto: StaffAuthSignInDto): Promise<object> {
  return this.staffAuthSignInService.signIn(staffAuthSignInDto);
}

Для начала — в Nest.js есть swagger. Автодокументация для REST API, в уже в самописном декораторе StaffAuthDecorator я описываю эту документацию для текущего ендпоинта. Затем через декоратор указываю метод, путь ендпоинта и сам метод, в теле которого передается та же DTO и вызывается сервис с бизнес-логикой.

Вот здесь я бы хотел тормознуть. По неведомым мне причинам, почти во всех видеоуроках на ютубе, бизнес-логику пишут в контроллере. Я до сих пор не понял зачем авторы курсов так делают. Может кто-то в комментах мне объяснит?

Ну собственно все. Конечно надо было бы показать как подключается база данных (mongo или postgres), как подключается модуль для работы с JWT или про unit-тесты рассказать… Но это уже такие нишевые темы, что включать их в эту статью, будет не очень правильно.

Стало ли у меня больше кода в сравнении с тем что было в прошлой статье? Да, мой модуль сотрудников сайта вырос значительно. Буквально вот на днях я дописал модуль логов (примерно как в MODx журнал событий). Выведу его в админку, протестирую и сделаю деплой.

Если честно, в холодный пот бросает, когда пытаюсь себе представить как бы выглядел набор модулей для работы с сотрудника на Express.js…

P.S.
Сборки моих проектов работают через микросервисы- бекенд, админка и фронт разделены и лежат в своих репозиториях (сабмодулях), есть отдельный репозиторий с настройками докера. Именно он разруливает через nginx маршрутиризацию. Деплой происходит через релиз новой версии проекта в Github, через Actions — полностью автоматизировано практически все.

В планах разработать большой модуль для работы с контентом сайта (статьи, товары и т.д.) благо есть хороший референс.

Будет ли следующая статья — не знаю. Но цикл статей я могу продолжать еще прилично долго, темы и материал есть. Могу погрузится в Nest.js или написать статью про Vue. Там же будет затронута тема с TS повторно, на реальном примере.

Спасибо что читаете мои статейки. Засим откланиваюсь.