Часто задаваемые вопросы (FAQ)

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

1. Начало работы

В: Что такое проект express-cargo?

О: Это промежуточное ПО (middleware), разработанное для автоматизации повторяющейся и утомительной обработки данных запроса (req.body, req.query и т.д.) в Express.js с использованием подхода на основе классов. Используя декораторы TypeScript, вы можете обрабатывать привязку данных и валидацию декларативно в одном месте.

В: Есть ли какие-либо меры предосторожности при установке?

О: Рекомендуется Node.js версии 20 или выше. Библиотека разработана для гибкой интеграции в существующие проекты Express в качестве стандартного промежуточного ПО.

В: Обязательна ли конфигурация TypeScript?

О: Да. Поскольку используются декораторы, следующие две опции должны быть установлены в true в вашем tsconfig.json:

• experimentalDecorators: true
• emitDecoratorMetadata: true

Кроме того, должен быть установлен пакет reflect-metadata для чтения информации о типах во время выполнения.

2. Привязка данных и декораторы

В: В чем разница между @Body и @Query?

О: Разница заключается в источнике извлечения данных:

• @Body: Извлекает данные из тела HTTP-запроса. В основном используется для запросов POST и PUT.
• @Query: Извлекает параметры из строки запроса URL (например, ?id=1&name=test). В основном используется для фильтрации или сортировки в запросах GET.
• Вы также можете привязывать различные другие данные запроса, используя @Params() (или @Uri()), @Header() и @Session().

В: Что такое @Uri()? Отличается ли он от @Params()?

О: @Uri() — это псевдоним для @Params(). Вы можете выбирать между ними в зависимости от ваших предпочтений в читаемости при привязке параметров пути URL (например, /:id).

В: Как получить привязанные данные?

О: После передачи промежуточного ПО bindingCargo(ClassName) в вашем маршрутизаторе, вы можете получить экземпляр внутри обработчика, вызвав функцию getCargo<ClassName>(req).

3. Валидация и преобразование

В: Как обрабатываются ошибки валидации?

О: Валидация выполняется внутри с использованием декораторов, таких как @Min, @Max и @Length. Если обнаружены неверные данные, промежуточное ПО автоматически возвращает ответ об ошибке или выбрасывает исключение.

В: Как я могу обработать или преобразовать значения полей?

О: Используйте декоратор @Transform(). Например, написав @Transform(v => v.trim()), вы можете преобразовать входные данные в желаемый формат перед привязкой.

В: Как избежать ошибок, если определенное поле отсутствует?

О: Используйте декоратор @Optional(). Поле будет успешно привязано, даже если значение равно null или undefined, пропуская валидацию для этого поля.

4. Совместимость фреймворков

В: Могу ли я использовать это с Fastify или NestJS?

О: Эта библиотека специально разработана как эксклюзивное промежуточное ПО для Express.js.

• NestJS: У NestJS есть свой собственный ValidationPipe и декораторы, которые могут перекрываться по функциональности. Хотя технически это возможно при использовании адаптера Express, основная цель этой библиотеки — улучшить DX в чистых средах Express.
• Fastify: В настоящее время официально не поддерживается.

5. Устранение неполадок

В: Почему данные экземпляра моего класса возвращают undefined?

О: Пожалуйста, проверьте следующие два пункта:

• Объявлено ли промежуточное ПО для парсинга тела, такое как express.json(), перед bindingCargo?
• Импортируется ли reflect-metadata в самом верху точки входа вашего приложения?

В: Происходит ли автоматическое преобразование типов?

О: Да. Предпринимается попытка автоматически преобразовать значения на основе типов, определенных в полях класса (string, number, boolean и т.д.). Например, строка "123", приходящая из @Query(), будет автоматически преобразована в число, если тип поля определен как number.

6. Разное

В: Могу ли я использовать это бесплатно в коммерческих проектах?

О: Эта библиотека лицензирована под лицензией MIT. Вы можете свободно использовать, изменять и распространять ее даже в коммерческих целях без ограничений.