Обзор декораторов

Что такое декораторы?

Декораторы в express-cargo аннотируют поля класса, чтобы сообщить промежуточному ПО:

• Откуда извлекать данные (например, body, query)
• Как их валидировать
• Как их преобразовывать

Когда вы передаёте класс в bindingCargo, промежуточное ПО читает эти декораторы, чтобы построить, проверить и преобразовать типобезопасный объект, который вы получаете через getCargo.

Категории декораторов

Декораторы сгруппированы по роли, которую они играют в конвейере привязки.

Категория	Назначение	Примеры	Ссылка
Source	Выбирает, откуда берётся значение поля	@Body, @Query, @Header, @Uri / @Params, @Session, @UploadedFile, @UploadedFiles	Декораторы источника, Декораторы загрузки файлов
Request	Читает значение напрямую из Request Express	@Request	Декораторы виртуальных полей
Virtual	Вычисляет поле из остальных полей объекта	@Virtual	Декораторы виртуальных полей
Transform	Изменяет значение одного поля перед привязкой	@Transform	Декоратор преобразования
Type helper	Определяет, как исходное значение интерпретируется и приводится	@Type, @List, @Enum	Декораторы типов-помощников
Validation	Применяет правила к значению поля	@Min, @Max, @Email, @OneOf, …	Декораторы валидации
Missing-value	Решает, что происходит, когда поле отсутствует	@Default, @Optional	Обработка отсутствующих полей

Source, Request и Virtual отвечают на один и тот же вопрос — откуда берётся значение поля, — поэтому каждое поле должно нести ровно один из них, и совмещать их нельзя. @UploadedFile и @UploadedFiles — это декораторы источника, читающие вывод multipart-парсера, поэтому @UploadedFile и @Body на одном поле отклоняются так же, как @Body и @Query.

Более сложные сценарии @Type и @List — полиморфизм, циклические ссылки, массивы собственных классов — описаны в разделе Продвинутое использование: Преобразование типов и полиморфизм и Декоратор List.

Комбинирование декораторов

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

import { Body, Transform, MinLength } from 'express-cargo'

class CreateUserRequest {
    @Body('email')                              // Source: чтение из req.body.email
    @Transform((value: string) => value.trim()) // Transform: нормализация значения
    @MinLength(5)                               // Validation: применение правила
    email!: string
}

Ограничение действует внутри категории, а не между категориями: поле принимает один источник, один тип-помощник и одну стратегию отсутствующего значения, тогда как декораторы валидации можно объединять свободно. bindingCargo() проверяет эти правила при регистрации маршрута и выбрасывает CargoSchemaError ещё до того, как сервер обработает запрос.

Каждая категория описана на своей собственной странице, ссылки на которые приведены выше.