Определение случаев использования приложения

Обзор вариантов использования

Вариант использования представляет собой полное взаимодействие между пользователями или внешними системами и приложением, описывая конкретные бизнес-сценарии. В Lino каждый вариант использования разделён на:

• Команда (Command): представляет намерение изменить состояние системы (создание, обновление, удаление и т.д.).
• Запрос (Query): представляет намерение получить данные без изменения состояния домена.

Такое разделение способствует ясности кода, облегчает тестирование, позволяет независимо масштабировать операции чтения и записи, и соответствует принципам чистой архитектуры и хорошим практикам Domain-Driven Design (DDD).

Команды

Команда — это неизменяемое сообщение, которое содержит только необходимые данные для выполнения действия, изменяющего состояние системы (например, CreateInvoice, DeactivateUser). Она должна содержать только свойства, представляющие основную информацию для выполнения операции.

Характеристики команды

• Неизменяемость: реализована как record или класс только с get без публичных сеттеров.
• Императивное имя: отражает выполняемое действие, например, CreateOrder, UpdateCustomerAddress.
• Минимальные данные: содержит только необходимые поля для выполнения операции, без возврата больших объёмов данных.
• Изолированная валидация: каждая команда имеет свои правила валидации, гарантируя консистентность перед обработчиком (Handler).

Валидаторы команд

Валидаторы команд обеспечивают, что команда корректна и соответствует бизнес-требованиям до передачи обработчику. В Lino мы используем библиотеку FluentValidation для реализации этих проверок, так как она широко применяется в .NET проектах и предлагает Fluent API для создания правил.

Общие правила валидации

• NotEmpty, NotNull для обязательных полей.
• InclusiveBetween для числовых диапазонов (например, денежные суммы, минимальные/максимальные количества).
• MaximumLength и MinimumLength для длины строк.
• RuleForEach для проверки элементов в коллекциях (List<T>).
• Must для пользовательских правил (например, формат документов, проверка дат).

Обработчики команд

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

Шаблон реализации обработчика

• Получение зависимостей (репозитории, внешние сервисы, UnitOfWork) через внедрение зависимостей.
• Маппинг и создание доменных сущностей, обеспечивая начальную консистентность.
• Применение бизнес-правил (дополнительные проверки, расчёт значений, вызов доменных событий).
• Сохранение изменений через IUnitOfWork или напрямую через репозитории.
• Возврат результата команды, указывающего успех или неудачу (Result<T>).

Результаты команд и паттерн Result

Результат команды должен быть простым DTO, содержащим только минимальные данные, необходимые вызывающему (например, API или фронтенду) для продолжения работы. Обычно включает идентификатор созданной или обновлённой сущности (Id) и, в случае ошибки, стандартизированную информацию об ошибке.

Для сценариев, где команда может завершиться неудачей, используется паттерн Result: абстракция, которая инкапсулирует результат операции, который может быть успешным или неудачным. В .NET часто используют типы вроде Result<T> (или похожие библиотеки), которые:

• Позволяют задать Value при успехе (например, простой DTO).
• В случае неудачи содержат стандартизированные коды или сообщения (Error), возможно с дополнительными метаданными (HTTP-коды, детали валидации и др.).
• Облегчают унификацию обработки ошибок по всей API, поддерживая консистентность между слоями.

Создание команды с помощью CLI

Lino упрощает генерацию всех артефактов, необходимых для новой команды, через команду:

lino command new

При выполнении этой команды интерактивный помощник запросит:

• Сервис — имя сервиса, в котором будет создана команда.
• Модуль — в модульных сервисах определяет целевой модуль.
• Сущность — связанная доменная сущность (опционально, но рекомендуется).
• Имя команды — конечное имя команды (например, CreateOrder).

После подтверждения Lino автоматически создаст файлы:

• CreateOrderCommand.cs
• CreateOrderCommandValidator.cs
• CreateOrderCommandHandler.cs
• CreateOrderCommandResult.cs

Пример сгенерированной структуры

Рассмотрим команду CreatePerson. Сгенерированная структура будет выглядеть примерно так:

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Application/
                ├── MyApp.MyService.Application.csproj
                └── UseCases/
                    └── People/
                        ├── Commands/
                        │   └── CreatePerson/
                        │       ├── CreatePersonCommand.cs
                        │       ├── CreatePersonCommandValidator.cs
                        │       ├── CreatePersonCommandHandler.cs
                        │       └── CreatePersonCommandResult.cs
                        └── Queries/
                            └── ...

Запросы (Queries)

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

Характеристики запроса

• Неизменяемость — как и команды, запрос не должен изменяться после создания.
• Описательное имя — отражает запрашиваемую информацию, например, GetCustomerById, ListOrdersByDateRange.
• Фильтры и пагинация — может включать параметры для выполнения специфических запросов (даты, статус, страница, сортировка).
• Проекция — должен возвращать DTO или модель представления только с необходимыми полями, избегая загрузки полных доменных объектов.

Валидаторы запросов

Валидаторы запросов отвечают за проверку входных параметров, таких как фильтры, значения пагинации (page, pageSize) и правила безопасности (права пользователя, видимость данных). Они также реализуются с помощью FluentValidation.

Общие правила валидации запросов

• GreaterThanOrEqualTo или LessThanOrEqualTo для фильтров по диапазону (например, даты).
• Length для текстовых фильтров (например, поиск по имени или электронной почте).
• InclusiveBetween для параметров пагинации (например, минимальное/максимальное количество элементов на странице).

Обработчики запросов

Обработчик запроса отвечает за обращение к репозиториям или контексту базы данных и возврат оптимизированных проекций, избегая полной загрузки доменных сущностей. В Lino рекомендуется использовать проекции с методами вроде .Select() для непосредственного отображения данных в формате DTO, обеспечивая эффективность и высокую производительность.

Результаты запросов

В Lino результаты запросов всегда представлены записями (records) с суффиксом QueryResult. Это соглашение применяется независимо от типа ответа — будь то список элементов (с пагинацией или без неё) или одна детализированная запись.

Создание запроса через CLI

Подобно командам, Lino предоставляет команду:

lino query new

Мастер предложит ввести:

• Сервис — Сервис, в котором будет создан запрос.
• Модуль — При необходимости, определяет доменный модуль.
• Сущность — Сущность или агрегат, к которым относится запрос (необязательно).
• Имя запроса — Например, GetOrderById или ListProductsByCategory.

Lino автоматически сгенерирует:

• GetOrderByIdQuery.cs
• GetOrderByIdQueryValidator.cs
• GetOrderByIdQueryHandler.cs
• GetOrderByIdQueryResult.cs

Пример сгенерированной структуры для запросов

MyApp/
└── src/
    └── Services/
        └── MyService/
            └── Application/
                ├── MyApp.MyService.Application.csproj
                └── UseCases/
                    └── Orders/
                        ├── Commands/
                        |   └── ...
                        └── Queries/
                            └── GetOrderById/
                                ├── GetOrderByIdQuery.cs
                                ├── GetOrderByIdQueryValidator.cs
                                ├── GetOrderByIdQueryHandler.cs
                                └── GetOrderByIdQueryResult.cs

Заключение

После того как вы поймёте, как определять и структурировать Use Cases (Commands и Queries) в Lino, вы будете готовы создавать надёжные и масштабируемые бизнес-сценарии, чётко разделяя логику записи и чтения. Используйте CLI для ускорения разработки, но всегда проверяйте и корректируйте реализации в соответствии с особыми требованиями вашего домена.

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