Instruction file imported from denis-peshkov/Cross.CQRS.EF (.cursor/rules/101-backend-cqrs.mdc). Copyright stays with the author.

CQRS и модули

Модули

Код организовывать по модулям в Web.Api/Modules/{ModuleName}/ (или эквивалент Modules/ у library/sample).

Структура модуля:

• Controllers/ — контроллеры API
• Dtos/ — Data Transfer Objects
• Handlers/ — обработчики команд и запросов

Modules/
└─ Vacancies/
   ├─ Controllers/
   │  └─ VacanciesController.cs
   ├─ Dtos/
   │  └─ SubmitResumeDto.cs
   └─ Handlers/
      └─ Create
      │  └─ SubmitResumeCommand.cs
      │  └─ SubmitResumeCommandHandler.cs
      │  └─ SubmitResumeCommandValidator.cs
      └─ Read
         └─ GetByIdQuery.cs
         └─ GetByIdQueryHandler.cs
         └─ GetByIdQueryValidator.cs

• контроллеры только для маршрутизации, логика в handlers
• CQRS с MediatR

CQRS с MediatR

• отдельные классы для команд (изменение данных) и запросов (чтение)
• вся бизнес-логика в обработчиках, не в контроллерах
• взаимодействие через IMediator.Send() и IMediator.Send<T>()

public class SubmitResumeCommand : Command<bool>
{
    public SubmitResumeDto Dto { get; set; }
}

public class SubmitResumeCommandHandler : CommandHandler<SubmitResumeCommand, bool>
{
    protected override async Task<bool> HandleAsync(SubmitResumeCommand command, CancellationToken cancellationToken)
    {
        // Business logic
        return true;
    }
}

DTOs

• отдельные классы для запросов и ответов
• FluentValidation для валидации DTOs
• суффикс Dto

public class SubmitResumeDto
{
    public string Name { get; set; }
    public string Email { get; set; }
    public string Phone { get; set; }
    public IFormFile Resume { get; set; }
}

Dependency Injection

• constructor injection
• интерфейсы для всех зависимостей

Нормализация ввода

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

Где нормализовать:

1. Примитивы — InputNormalizer (NormalizeTrimmedText и расширения по мере надобности). Типичный путь хоста: server/Web.Api/Common/InputNormalizer.cs.
2. Применение — IRequestFilter<TCommand> / *CommandRequestFilter рядом с командой; цепочка Cross.CQRS: RequestFilterBehavior до ValidationBehavior.
3. Не в handler — нормализация до валидации, чтобы NotEmpty / EmailAddress видели уже очищенные строки.

Исключения:

• domain (UserService, CodeService) может дублировать нормализацию идентификаторов как страховку
• пароли в InputNormalizer не трогать — явно в комментарии к классу

// *CommandRequestFilter.cs
dto.Email = InputNormalizer.NormalizeTrimmedText(dto.Email);
dto.Code = InputNormalizer.NormalizeTrimmedText(dto.Code);
// dto.Password — do not normalize