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

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

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

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

src/Services/<ServiceName>/<ModuleName>/Application/UseCases/<EntityName>/
├── Commands/
│   └── <CommandName>/
└── Queries/
    └── <QueryName>/

Такая организация дает понять, какому сервису, модулю и объекту принадлежит каждая функция. Он также сохраняет независимость модели записи и модели чтения, что полезно, когда экрану, API, интеграции или фоновому процессу требуется только одна сторона поведения.

Command или Query?

Что относится к варианту использования приложения

• Вступительный контракт: record из command или query, содержащий только данные, необходимые для операции.
• Валидация: правила, которые проверяют формат запроса, обязательные поля, диапазоны, идентификаторы, фильтры и другие ограничения ввода, прежде чем handler выполнит поток.
• handler оркестровка: вызовы зависимостей, доступ к репозиториям, контекстные запросы, использование Unit of Work, составление результатов, ведение журнала и трассировка.
• Результат контракта: небольшой объект ответа или бессодержательный результат, который дает caller именно то, что ему нужно для продолжения.

Что следует исключить из варианта использования

• Инварианты предметной области должен оставаться в сущностях, Value Objects, службах домена и методах домена.
• Детали инфраструктуры они должны оставаться за абстракциями, репозиториями, контекстами баз данных, файловыми службами, интеграцией обмена сообщениями и внешними клиентами.
• Проблемы с презентацией, такие как состояние UI, метки, макеты и поведение компонентов, должны оставаться на уровне веб-приложения.

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

Commands

Один Command — неизменяемое сообщение, содержащее только данные, необходимые для выполнения действия, изменяющего состояние системы. Распространенными примерами являются CreateCustomer, UpdateVehicle, DeleteMaintenance, ConfirmOrder и SavePermissionsByRoleId. Commands следует называть действиями, поскольку они сообщают приложению что-то сделать.

В Lino генерируемые Commands представляют собой record, которые реализуют абстракцию command и возвращают стандартизированный результат. Создание Commands обычно возвращает объект результата с идентификатором или минимальной информацией, требуемой caller, а обновление и удаление commands обычно возвращают no-content при успешном завершении операции.

Характеристики Command

• Неизменяемость: реализовано как record или класс только с get, без изменяемых публичных установщиков.
• Имя в императиве: отражает деловые действия, такие как CreateOrder, UpdateCustomerAddress или ChangeProductPrice.
• Минимальные данные: содержит только поля, необходимые для выполнения операции, без транспортировки целых сущностей или больших объемов данных.
• Изолированная проверка: каждый Command имеет свои собственные правила, гарантирующие согласованность запроса до достижения handler.
• Независимость от UI: Command представляет намерение приложения, а не кнопку, форму или компонент, вызвавший операцию.

Когда создавать Command

• Используйте Command, когда данные будут созданы, изменены, удалены, объединены, импортированы, утверждены, отменены или изменены каким-либо образом.
• Сосредоточьте внимание payload на операции; не передавайте весь объект, если достаточно нескольких полей.
• Выбирайте названия, которые описывают бизнес-действие, а не визуальное событие, которое его инициировало.
• Проверьте, принадлежит ли действие текущему модулю или оно должно быть выражено посредством интеграции, события или теневой сущности в другом модуле.

Command Validators

Ты Command Validators убедитесь, что Command правильно сформирован и соответствует требованиям ввода, прежде чем он будет отправлен в handler. В Lino эти проверки реализованы с помощью FluentValidation, обычная библиотека в проектах .NET, поскольку она предлагает свободный и удобочитаемый API для создания правил.

Общие правила проверки

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

validator защищает передний край. Фактические инварианты домена, такие как границы состояний, разрешенные переходы и правила, которые должны соблюдаться независимо от caller, продолжают принадлежать aggregate, сущности, Value Object или службе домена.

Command Handlers

ТО Command Handler выполняет логику приложения, связанную с Command. Он организует репозитории, контексты, IUnitOfWork, вспомогательные службы, ведение журнала, отслеживание, интеграционные вызовы и события домена при необходимости.

Шаблон реализации для handler

• Получайте зависимости посредством внедрения зависимостей, например репозитории, внешние сервисы, контексты и Unit of Work.
• Подтвердить наличие и доступность данных, необходимых для работы.
• Загрузите правильный aggregate или объект, если операция зависит от существующего состояния.
• Вызовите методы домена вместо дублирования инвариантов в handler.
• Сохранение изменений посредством IUnitOfWork или абстракции постоянства проекта.
• Регистрируйте домен, Outbox или события интеграции, когда операции необходимо обмениваться данными с другими частями системы.
• Возвращаться Result или Result<T> успех, известный отказ или минимальные данные ответа.

Command Results и Result Pattern

ТО Command Result должен быть простым DTO, содержащим только данные, необходимые для продолжения работы caller. При создании он обычно включает в себя Id генерируется. При обновлении или удалении payload может отсутствовать. Если операция завершается неудачей из-за ожидаемого условия, возврат должен содержать стандартизированную информацию об ошибке.

ТО Result Pattern инкапсулирует результат операции как успех или неудачу. Вместо того, чтобы создавать исключения для предсказуемых сценариев, таких как объект не найден, недопустимое состояние или бизнес-проверка, handler возвращает тип, например Result<T> со значением, ошибкой и метаданными, когда это необходимо.

• В случае успеха результат может выявить Value, например небольшой DTO или созданный идентификатор.
• В случае сбоя результат сохраняет стандартизированные коды или сообщения, часто определяемые в многоразовых определениях ошибок.
• Поток обработки ошибок согласован между Application, API, typed clients и UI.

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

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

lino command new

CLI также поддерживает опции, позволяющие сократить количество вопросов в мастере:

lino command new --service <ServiceName> --module <ModuleName> --entity <EntityName> --name <CommandName>
lino command new --name <CommandName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino command list --service <ServiceName> --module <ModuleName> --entity <EntityName>

• -s или --service: целевой сервис.
• -m или --module: целевой модуль в модульных сервисах.
• -e или --entity: объект, связанный с Command.
• -n, --name, -c или --command: имя Command.

Во время интерактивного потока Lino подтверждает службу, модуль, объект, имя Command, тип Command и, для операций создания или обновления, свойства, которые будут частью запроса. Типы, предоставляемые CLI: Создавать, Обновлять и Удалить.

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

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

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

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

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Application/
                ├── <ProjectName>.<ServiceName>.Application.csproj
                └── UseCases/
                    └── People/
                        ├── Commands/
                        │   └── CreatePerson/
                        │       ├── CreatePersonCommand.cs
                        │       ├── CreatePersonCommandValidator.cs
                        │       ├── CreatePersonCommandHandler.cs
                        │       └── CreatePersonCommandResult.cs
                        └── Queries/
                            └── ...

Для настроенного парка Command структура соответствует тому же шаблону:

Application/UseCases/Vehicles/Commands/UpdateVehicle/
├── UpdateVehicleCommand.cs
├── UpdateVehicleCommandValidator.cs
├── UpdateVehicleCommandHandler.cs
└── UpdateVehicleCommandResult.cs

Обязанности файлов Command

• Command: неизменяемый контракт запроса с записью операции.
• Validator: проверка ввода, обычно с обязательными правилами, размером, диапазоном, идентификаторами и коллекциями.
• Handler: оркестровка репозиториев, Unit of Work, контексты, методы предметной области, ведение журнала, трассировка и создание результатов.
• Result: Контракт минимального ответа для успешных операций, требующих возврата данных.

Контрольный список реализации

1. Бегать lino command new и выберите правильную службу, модуль, сущность, тип и свойства.
2. Откройте сгенерированный Command и удалите все поля, которые не являются частью контракта операции.
3. Усильте validator правилами входа в бизнес, которые нельзя вывести автоматически.
4. Просмотрите handler и убедитесь, что он вызывает поведение домена, а не дублирует инварианты на уровне приложения.
5. Использовать IUnitOfWork для устойчивости и предпочитают сохранение транзакций, когда операция также требует событий или надежного Outbox.
6. Невозможность возврата из-за ошибок Result, а не исключениями из ожидаемых бизнес-результатов.
7. Создайте и протестируйте конечную точку, страницу или интеграцию, которая будет вызывать Command.

Queries

Один Query представляет намерение получить данные без изменения состояния домена. Queries предназначены для эффективного чтения, возвращая именно те поля, которые нужны caller, без загрузки целых объектов, когда в этом нет необходимости.

Распространенными примерами являются GetCustomerById, ListCustomers, ListPhoneTypes, ListOrdersByDateRange и специальный query типа GetVehicleAvailability. Query должен отвечать на вопрос, специфичный для приложения.

Характеристики Query

• Неизменяемый: Как и Commands, Query не должен допускать изменений после создания.
• Описательное имя: отражает искомую информацию, например GetCustomerById или ListOrdersByDateRange.
• Фильтры и нумерация страниц: может загружать даты, статус, страницу, размер страницы, текст поиска, порядок и другие параметры чтения.
• Проекция: должен возвращать DTO или просматривать модель только с необходимыми полями, избегая прямого раскрытия объектов предметной области.
• Никаких побочных эффектов: нельзя вызывать методы, которые меняют состояние или сохраняют изменения в базе данных.

Когда создавать Query

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

Query Validators

Ты Query Validators проверять входные параметры, такие как фильтры, значения нумерации страниц, диапазоны дат, идентификаторы и правила видимости. Они также реализованы с FluentValidation.

Общие правила проверки в Queries

• GreaterThanOrEqualTo и LessThanOrEqualTo для фильтров диапазона, таких как даты начала и окончания.
• Length, MaximumLength и MinimumLength для текстовых фильтров, таких как имя, адрес электронной почты или поисковый запрос.
• InclusiveBetween для пейджинга, ограничения page и pageSize.
• NotEmpty для обязательных идентификаторов в подробных запросах.
• Must для недопустимых комбинаций фильтров, например, дата окончания меньше даты начала.

Query Handlers

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

handler из Query должен быть read-only: он не вызывает методы домена, изменяющие состояние, не вызывает постоянные изменения и не выполняется. SaveChanges. Если при чтении необходимо зарегистрировать аудит, инициировать интеграцию или пересчитать состояние, это обычно указывает на другой вариант использования или отдельный процесс.

Query Results

В Lino результаты из Queries представлены record с суффиксом QueryResult. Это соглашение применяется к одному ответу, простому списку, постраничному списку или DTO, API для конкретного экрана, интеграции или фоновому процессу.

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

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

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

lino query new

CLI также принимает такие параметры, как:

lino query new --service <ServiceName> --module <ModuleName> --entity <EntityName> --name <QueryName>
lino query new --name <QueryName> --service <ServiceName> --module <ModuleName> --entity <EntityName>
lino query list --service <ServiceName> --module <ModuleName> --entity <EntityName>

• -s или --service: целевой сервис.
• -m или --module: целевой модуль.
• -e или --entity: объект, связанный с Query.
• -n, --name, -q или --query: имя Query.

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

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

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

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

<ProjectName>/
└── src/
    └── Services/
        └── <ServiceName>/
            └── Application/
                ├── <ProjectName>.<ServiceName>.Application.csproj
                └── UseCases/
                    └── Orders/
                        ├── Commands/
                        |   └── ...
                        └── Queries/
                            └── GetOrderById/
                                ├── GetOrderByIdQuery.cs
                                ├── GetOrderByIdQueryValidator.cs
                                ├── GetOrderByIdQueryHandler.cs
                                └── GetOrderByIdQueryResult.cs

Для индивидуальной доступности автомобиля Query структура соответствует тому же шаблону:

Application/UseCases/Vehicles/Queries/GetVehicleAvailability/
├── GetVehicleAvailabilityQuery.cs
├── GetVehicleAvailabilityQueryValidator.cs
├── GetVehicleAvailabilityQueryHandler.cs
└── GetVehicleAvailabilityQueryResult.cs

Обязанности файлов Query

• Query: неизменяемый контракт запроса с идентификаторами, фильтрами, упорядочением, нумерацией страниц или диапазонами дат.
• Validator: проверка идентификаторов, нумерация страниц, обязательные фильтры, диапазоны дат и критерии поиска.
• Handler: оркестровка чтения с использованием контекста приложения, проекций, фильтров, упорядочивания, нумерации страниц, ведения журналов, трассировки и создания результатов.
• Result: ответ DTO, созданный по образцу caller, часто с внутренними record для элементов списка.

Контрольный список реализации

1. Бегать lino query new и выберите службу, модуль, объект, имя Query, тип возвращаемого значения, режим подкачки и свойства.
2. Просмотрите контракт запроса и сохраняйте только те фильтры, которые действительно необходимы для caller.
3. Усильте validator, особенно для обязательных идентификаторов, диапазонов дат, ограничений размера страницы и недопустимых комбинаций фильтров.
4. Настройте проекцию handler так, чтобы она возвращала только поля, необходимые для UI, API, интеграции или фонового процесса.
5. Сохраните Query read-only: не вызывайте методы домена, которые изменяют состояние, и не сохраняйте изменения в handler.
6. Распространяйте ожидаемые сбои по Result, используя существующие стандартизированные ошибки, где это возможно.
7. Создайте и протестируйте потребителя, который вызывает Query, например конечную точку API, страницу Blazor, внутрипроцессную интеграцию или typed client.

Пример пользовательского Query

В процессе интеграции между модулями SaaS можно создать индивидуальную доступность транспортных средств Query с помощью lino query new. Сгенерированная структура содержит Query, Handler, Result и Validator. Затем разработчик добавляет необходимые входные данные, такие как идентификатор транспортного средства, дату начала и дату окончания, проверяет правильность диапазона и реализует логику handler. Это ожидаемый процесс: сначала сгенерируйте согласованную структуру, а затем завершите поведение, специфичное для предметной области, с помощью явного кода.

Заключение

Определение вариантов использования в Lino преобразует модель предметной области в понятные операции приложения. Commands обрабатывает изменения состояния, Queries обрабатывает чтение, validators защищает границу ввода, handlers организует поток, а объекты результата стандартизируют вывод.

Самый быстрый процесс обычно следующий: смоделировать домен, сгенерировать необходимые Commands и Queries, просмотреть сгенерированные файлы, завершить бизнес-поведение, представить вариант использования через API или страницу, когда это необходимо, и проверить все с помощью сборки и тестов. Это позволяет ускорить разработку без потери архитектурного контроля.

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