Введение

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

Именно свобода и максимальная гибкость, которые данный язык предлагает разработчикам, больше всего влияет на качество проектов на нём. Язык позволяет решать задачи и строить приложения практически как угодно. И у большинства приложений бекэнда я замечаю одно и то же: спустя год, расширять и изменять их становится крайне неприятной задачей, за которую никто не захочет браться.

Да, я принимаю, что на других языках ситуации могут быть схожими, но я буду говорить только про "своё болото", и об его улучшении.

Туториал является сугубо субъективным, отталкиваясь от опыта увиденных приложений на NestJS, и решать, что со всем этим делать только вам.

О чем будем говорить

Сначала выведем несколько проблем и дополним каждую из них, а затем узнаем, какие решения предлагаются автором, а затем сделаем выводы.

Краткая справка и мысли про NestJS

Когда-то, во времена, когда люди передвигались на саблезубых тиграх, а концепции асинхронности не было, и программы еще не умели ничего обещать, разработчики писали серверные приложения на нативном модуле http, фреймворке koa, или же, скорее всего, на express - довольно удобном и прорывным на то время фреймворком.

Некоторые же последовали примеру представленных выше фреймворков и начали создавать свои, те самые, фреймворки - про мемичность этого явления знают все. Время шло, деревья росли, и в 2017 вышел, как на данный момент можно судить, прорывной фреймворк на Node.js, который был встречен очень неоднозначно, но продолжал уверенно развиваться и набирать популярность.

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

По собственному мнению и мнениям из круга товарищей-разработчиков, NestJS является очень удобным, понятным и простым в разработке фреймворком. Создание и интеграция модулей, использование декораторов, родная поддержка TypeScript, возможность выбора фреймворка под NestJS - всё это повлияло на мой выбор, и в основном я стал работать именно на нём, оставив express для простых приложений, где модули были бы лишним нагромождением.

В чём же проблема?

Разобрав немало коммерческих и внутренних проектов на NestJS, я могу выделить следующие проблемы, а затем мы перейдем к их решениям.

Проблема - Отсутствие абстрактного и(ли) графического (доменного) представления

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

Проблема - Игнорирование контрактов и высокая связность

Очень мало видел, чтобы хоть для модулей API создавались контракты (интерфейсы), а это очень важный пункт, но разберём важность этого пункта в решcениях.

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

Проблема - Создание функций, ответственных за 999 бизнес кейсов одной тематики

Нередки ситуации, когда разработчики обрабатывают очень много бизнес кейсов в одной функции, что в определенный момент сделает внесение изменений в логику без тотального рефакторинга невозможным или крайне трудозатратным (а еще разработчика будут вспоминать хорошими словами).

Проблема - Отсутствие комментариев

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

Обычно, без человека, который не сядет с новым разработчиком и расскажет про этот код, можно долго "засесть" на одном месте и, что хуже, самому начать создавать баги, неверно интерпретируя имеющийся код.

Проблема - Отказ и(ли) отсутствие выделения времени на создание и поддержку тестирований

Учитывая, что NestJS позволяет удобно и из коробки, вместе с Jest, создавать моки и тестирования, как юниты, так и сквозные с интеграционными, много где я этих самых заветных тестов не видел.

Возможно, на задачу не выделили времени с написанием/поддержкой тестирований, опираясь на какие-то другие приоритеты. Возможно, связано с же нежеланием разработчиков этим заниматься, но проблема серьезная, которая, скорее всего, повлечет гораздо больше проблем и трудозатрат, чем кажется.

Проблема - Чрезмерное использование ORM

ORM - довольно удобная и приятная вещь, которая сильно упрощает разработку, но повальное использование таких инструментов во всех случаях приложения, как правило, вызывает проблемы с работой логики частей приложения.

Проблема - Неправильное управление исключениями

Исключения в NestJS - очень гибкая и удобная вещь, которую, к тому же, можно улучшить фильтрами. Игнорирование или неправильное использование исключение может неплохо усложнить работу с кодом.

Решаем проблемы и рефлексируем

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

Решение - Отсутствие абстрактного и(ли) графического (доменного) представления

Для решения данной проблемы мы можем обратиться к абстрагированию от кода и к любимому многими DDD.

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

Но вернемся к графическому и абстрактному представлению приложения. Я советую всем рисовать и представлять приложение схематически, абстрагируясь от кода.

Для примера представим, что мы делаем бекэнд для университета, и как мы его можем представить, чтобы архитектура была понятной, и разработчики могли следовать ей?

Вот простая схема, рассчитанная на минимальное количество места для компактности, но вам советую не экономить холст и тогда будет красиво и понятно.

Про слои ответственности. Лучшим примером будет использование кода поиска не из репозитория. Рассматривать будем на крохотных примерах, на которых можно не увидеть очень больших проблем, но нужные ассоциации они у вас вызовут, уверен, ведь обычно логика использования репозитория бывает намного сложнее.

// Сервис + репозиторий
@Injectable()
export class UserService {
  constructor(
    @InjectRepository(User) private readonly userRepository: Repository<User>,
  ) {}

  async updateUserByIdAnd(userId: string, someUpdateObj: UpdateUserDTO): Promise<User> {
    const formatedObject = MyUtils.formatObject(someUpdateObj);
    /* 
     * Еще какая-то логика...   
     */
    return this.userRepository.update({where: {id: userId}}, someUpdateObj);
  }
}

К сожалению, мы намешали разные слои и зоны ответственностей: сервис пользователей и что-то считает-вычисляет, выполняя часть бизнес задачи, да еще и выполняет функции инфраструктуры, сразу же засорив код сервиса, который вообще не должен общаться с базой данных напрямую, кроме редких случаев.

Для исправления этого нам стоит вынести всю логику инфраструктуры в методы UserRepository, и уже вызывать их, полностью вынося из сервиса инфраструктурную логику.

// Репозиторий
@Injectable()
export class UserRepository {
  constructor(
    @InjectRepository(User) private readonly userRepository: Repository<User>,
  ) {}

  async partialUpdateUserById(userId: string, someUpdateObj: UpdateUserDTO): Promise<User> {
    //Можно использовать форматирование или выброс исключений, если мы определили репозиторий как умный (см. ниже)
      const formatedObject = MyUtils.formatObject(someUpdateObj);
      return this.userRepository.update({where: {id: userId}}, formatedObject);
  }
}
// Сервис
@Injectable()
export class UserService {
    constructor(
        private readonly userRepository: UserRepository,
    ) {}

    async updateUserByIdAnd(userId: string, someUpdateObj: UpdateUserDTO): Promise<User> {
        /* 
         * Какая-то логика...   
         */
        return this.userRepository.partialUpdateUserById(userId, someUpdateObj);
    }
}

На выбор предлагается два вида репозиториев:

• Умные (smart) репозитории полезны тогда, когда требуется выполнение операций типа форматирования и прочего, которые не могут быть выполнены просто с использованием CRUD операций.

• Глупые (dumb) репозитории подходят для простых частей системы, когда от него требуется просто выполнить операции CRUD.

Теперь мы разделили ответственности слоёв и упростили код и читаемости приложения.

Контекст же нужно намечать, чтобы разработчики понимали, что и где, возможно зачем, связанны модули приложения, что упростит понимание последнего.

Еще довольно полезным умением, которым стоит научиться - уметь думать доменно и посредством кода, например: Отчислить студента = Добавить в журнал отчислений запись о данном студенте в таблице журнала отчислений базы данных, удалить/изменить запись студента в таблице студентов базы данных.

Решение - Игнорирование контрактов и высокая связность

Для начала приведу абзац теории:

Связность (coupling) в программной инженерии относится к степени зависимости между различными модулями или компонентами системы. Высокая связность означает, что компоненты сильно зависят друг от друга, что усложняет их изменение, тестирование и повторное использование. Низкая связность, напротив, предполагает, что компоненты имеют минимальные зависимости друг от друга, что делает систему более гибкой и легкой для поддержки. Контракты - описание интерфейсов взаимодействия компонентов, то есть, интерфейсы или классы DTO в TypeScript.

Если же сделать выводы в контексте NestJS, то для низкой связности части приложения не должны быть привязанным к интерфейсам определенных классов, и классы не должны быть источниками контрактов, а должны их имплементировать.

Простой пример интерфейсов в NestJS:

// Интерфейс
export interface IUserService {
    findAll(): Promise<User[]>;
    findOne(id: string): Promise<User>;
    create(createUserDto: CreateUserDto): Promise<User>;
}
// Сервис, его имплементирущий
@Injectable()
export class UserService implements IUserService {
  async findAll(): Promise<User[]> {
    // Логика получения всех пользователей
  }
  async findOne(id: string): Promise<User> {
    // Логика получения пользователя по ID
  }
  async create(createUserDto: CreateUserDto): Promise<User> {
    // Логика создания нового пользователя
  }
}

То есть, у нас не интерфейс(описание функциональности) зависит от имеющейся функциональности, а имеющаяся функциональность зависит от требуемой функциональности.

А как же это связанно со связностью?

Низкая связность достигается тем, что КлассА не зависит от конкретной реализации КлассаБ, а использует контракт, описанный для КлассаБ, и ему не важно, как КлассБ выполняет логику функциональности.

Со временем я нашел самый полезный вариант снижения связности для NestJS, и я его вам покажу:

// Интерфейс сервиса
export interface IUserService {
    findAll(): Promise<User[]>;
    findOne(id: string): Promise<User>;
    create(createUserDto: CreateUserDto): Promise<User>;
}

// Интерфейс репозитория
export interface IUserRepository {
    findAll(): Promise<User[]>;
    findOne(id: string): Promise<User>;
    create(createUserDto: CreateUserDto): Promise<User>;
}

// Сервис
@Injectable()
export class UserService implements IUserService {
    constructor(
        @Inject('IUserRepository') private readonly userRepository: IUserRepository,
    ) {}
    async findAll(): Promise<User[]> {
        return this.userRepository.findAll();
    }
    async findOne(id: string): Promise<User> {
        return this.userRepository.findOne(id);
    }
    async create(createUserDto: CreateUserDto): Promise<User> {
        return this.userRepository.create(createUserDto);
    }
}

// Контроллер
@Controller('users')
export class UserController {
    constructor(@Inject('IUserService') private readonly userService: IUserService) {}
    @Get()
    async findAll() {
        return this.userService.findAll();
    }
    @Get(':id')
    async findOne(@Param('id') id: string) {
        return this.userService.findOne(id);
    }
    @Post()
    async create(@Body() createUserDto: CreateUserDto) {
        return this.userService.create(createUserDto);
    }
}

// Репозиторий
@Injectable()
export class UserRepository implements IUserRepository {
    constructor(
       @InjectRepository(User) private readonly userRepository: Repository<User>,
    ) {}
    async findAll(): Promise<User[]> {
        // Логика для получения всех пользователей
    }
    async findOne(id: string): Promise<User> {
        // Логика для получения пользователя по ID
    }
    async create(createUserDto: CreateUserDto): Promise<User> {
        // Логика для создания нового пользователя
    }
}

// Модуль
@Module({
    controllers: [UserController],
    providers: [
        {
            provide: 'IUserService',
            useClass: UserService,
        },
        {
            provide: 'IUserRepository',
            useClass: UserRepository,
        },
    ],
})
export class UserModule {
}

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

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

При возможном изменении сервисов и/ли реализаций их логики, остальные элементы будут не затронуты без изменения контракта. Также, упрощает создание моков при тестировании, так как мы чётко знаем, что кому нужно.

Можно обойтись и без инжектов через токены, но в больших приложениях данная опция будет цениться для удобства больше.

Проблема - Создание функций, ответственных за 999 бизнес кейсов одной тематики

Допустим, есть метод:

async fetchData(userId: string): Promise<{user: User, shops?: Shops, shopsMoney?: ShopsMoney, myMoney: UserMoney}> {
    const user = this.userRepository.fetchUser(userId);
    const result = {};
    if (user.role === UserRoles.ADMIN) {
        result.shops = this.shopsRepository.findAll();
        result.shopsMoney = await Promise.all(ashops.map(async (shop) => {
                const money = await this.moneyRepository.findByShopId(shop.id);
                return {shop, money};
            }));
        return result;
    } else {
        result.user = user;
        result.money = await this.moneyRepository.findByUserId(user.id);
        return result;
    }
    // ...
}

Вот такой код я видел не один раз, и это еще я указал мало ролей и параметров, иногда вообще дремучий лес возникает в коде.

Что делать?

1. Не допускать создания таких методов, разбивать их на единственные ответственности.

2. Не допускать создания методов, использующих таких методов, например, разбивать API на несколько роутов с обособленными методами.

Решение - Отсутствие комментариев

Здесь решение довольно простое - начать писать комментарии, и я вас научу даже как.Есть такая прекрасная вещь, как JSDoc, и вот как можно писать комментарии на нем к функциям, методам и т.д.:

/**
 * @description Функция, которая добававляет пользователя в базу данных и отсылает ему на почту сообщение с приветствием
 * @param email - имейл пользователя
 * @param phone - (опционально) - телефон пользователя
 * @param name - ФИО пользователя
 * @returns {string} UUID пользователя
 * @link https://mysuperwiki.com/registerUser
 */
function registerUser(email: string, name: string, phone?: number): Promise<string> { ... }

Следуя данному примеру, мы можем получить описание функций, ссылку на вики, что возвращает функция. Еще неплохая функция JSDoc с ESLint, проверка на существование параметров, если нет соответствия, то последний будет сыпать варнингами.

Еще рекомендую, но не настаиваю на описание шагов в важных и больших функциях, например:

function complicatedFunction(...) {
    // Шаг 1: Создаем x и вызываем функцию просчета траектории
    ...
    // Шаг 2: Передаем x в RMQ и ждем ответа
    ...
    // Шаг 3: Записываем результаты ответа от микросервиса просчета y
    ...
}

Поначалу, когда разработчик пишет еще горячий код, то потребность и желание в написании комментариев не так остра, а спустя некоторое время он смотрит на код со словами "Что же это такое?" - обыденная ситуация.

Решение - Отказ и(ли) отсутствие выделения времени на создание и поддержку тестирований

Наверное, самая важная и распространённая проблема, на самом деле. Про мотивы размышлять не будем, но тестирования, хотя бы юниты, обязаны быть. И лучше в юнитах добиваться хороших показателей покрытия, то есть, все возможные ветвления кода и т.д., но не усердствовать с неверным вводом, так как такие данные обсекутся пайпами и валидаторами.

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

Лучше всего сделать обязательные тестирования хотя бы перед merge-реквестом.Тестирования - важнейшая часть приложения, на которую стоит потратить время, чтобы потом быть намного увереннее, что проблем будет намного меньше. А если еще добавить интеграционные и сквозные (е2е), то будет еще лучше.

Решение - Неправильное управление исключениями

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

Исключения, особенно в NestJS, очень удобные, но позволяют уменьшить количество кода, например:

// Сервис 
@Injectable()
export class UserService {
    private users: User[] = [];
    findUserById(id: number): User | null {
        const user = this.users.find(user => user.id === id);
        return user || null;
    }
}
// Контроллер
@Controller('users')
export class UserController {
    constructor(private readonly userService: UserService) {}

    @Get(':id')
    findUserById(@Param('id') id: number) {
        const user = this.userService.findUserById(id);
        if (!user) {
            return { message: 'Пользователь не найден!' }; // Лишний здесь код, но ответить пользователю нужно
        }
        return user;
    }
}

Это самый простой пример, когда мы можем избавиться от части кода и убрать все негативные результаты при выполнении.

// Сервис 
@Injectable()
export class UserService {
    private users: User[] = [];
    findUserById(id: number): User | null {
        const user = this.users.find(user => user.id === id);
        if (!user) {
            throw new NotFountException({ message: 'Пользователь не найден!' });
        }
        return user;
    }
}
// Контроллер
@Controller('users')
export class UserController {
    constructor(private readonly userService: UserService) {}

    @Get(':id')
    findUserById(@Param('id') id: number) {
        return user = this.userService.findUserById(id);
    }
}

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

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

В таком случае у нас получаются либо только правильные ответы, либо ответы с ошибкой с кодом 4хх-5хх, что уменьшит количество ветвлений логики. Еще рекомендую добавить фильтры, которые добавляют дополнительную обработку исключений.

Какие выводы мы можем сделать

Вывод довольно прост - правильно выделять время на задачи, попросить ведущих разработчиков создать правила для написания кода, а что самое важное - внедрять людям культуру кода.

Культура кода важна для создания качественного, поддерживаемого и надежного программного обеспечения.

Она способствует улучшению взаимодействия с кодом внутри команды, повышает производительность разработчиков и обеспечивает хотя бы некоторые стандарты разработки.

Но тут, как и в стандартной культуре, нужно постепенно прививать и пропагандировать, что это нужно, и, главное, почему это важно и нужно.

На этом всё, спасибо за прочтение данной статьи, если есть вопросы или что-то другое, то обязательно пишите в комментариях. Всем успехов в ваших делах!