Создание полноценного .NET-приложения с Lino: пошаговое руководство

Установка и настройка Lino CLI

Первый шаг к началу работы с Lino CLI заключается в установке инструмента в вашей среде разработки. Он распространяется как глобальный инструмент dotnet, что означает, что он будет доступен для любого проекта.NET на вашем компьютере. Перед установкой убедитесь, что.NET SDK, необходимый для текущих шаблонов, доступен и что терминал может работать. dotnet и что глобальный каталог инструментов.NET находится в папке PATH.

Шаг 1: Установка

Чтобы установить (или обновить) Lino CLI, выполните в терминале следующую команду:

dotnet tool install --global Tolitech.Lino

Важные примечания:

• Если версия уже установлена, вы можете использовать dotnet tool update --global Tolitech.Lino обновить.
• Убедитесь, что глобальный каталог инструментов.NET находится в папке PATH системы так, чтобы команда lino функционировать правильно.

Шаг 2. Настройте язык

После установки рекомендуется настроить язык (или культуру), который CLI будет использовать в сообщениях, подсказках и журналах:

lino preferences culture set

Вам будет предложено выбрать один из доступных языков. Этот параметр гарантирует, что все инструкции и подсказки будут отображаться на нужном языке одинаково. Это предпочтение изменяет локализованные сообщения, подсказки и инструкции CLI; он не переименовывает сущности, услуги, модули или бизнес-термины, созданные в проекте.

Шаг 3: Аутентификация и регистрация

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

- Если вы еще не зарегистрированы, зарегистрируйтесь командой:

lino user register

- Если вы уже зарегистрированы, войдите с помощью:

lino auth login

Что происходит: CLI хранит токен аутентификации локально, что позволяет вам выполнять команды, требующие доступа к защищенным ресурсам, без необходимости входа в систему каждый раз, когда вы его используете. Сохраняйте этот токен конфиденциальным и избегайте совместного использования одного и того же профиля пользователя разными разработчиками, агентами CI или компьютерами.

Шаг 4: Проверка

Чтобы убедиться, что установка и аутентификация прошли успешно, запустите:

lino --version

Если команда вернет установленную версию, вы готовы начать использовать Lino CLI в ваших проектах.

Создание проекта MyApp

На этом этапе мы создадим первоначальную структуру проекта, используя Lino CLI. Этот проект послужит основой для демонстрации создания сервисов, модулей, интерфейса и всей интеграции событий. Проект Lino — это не просто папка с решением: он определяет соглашения о границах сервисов, общих библиотеках, хосте Aspire, платформе внешнего интерфейса, тестах, управлении пакетами, анализаторах и конфигурациях, которые повторно используются следующими командами.

Шаг 1. Запуск команды создания

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

lino project new

CLI будет вести вас шаг за шагом, запрашивая такую ​​информацию, как:

• Название проекта: мы будем использовать MyApp, но вы можете выбрать любое имя;
• Дополнительные возможности: анализаторы кода, распределенное кэширование, поддержка асинхронных событий и т. д.

Шаг 2. Настройка основных функций

Для этого проекта мы рекомендуем с самого начала включить следующие функции:

• Анализаторы кода: гарантировать, что код соответствует передовой практике и последовательным стандартам, предотвращая распространенные ошибки реализации;
• Распределенный кэш: повышает производительность приложений в сценариях с несколькими сервисами, избегая ненужных запросов к базе данных;
• Асинхронная связь: позволяет использовать события и очереди для интеграции между сервисами, обеспечивая масштабируемость и развязку.

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

Шаг 3: Сгенерированная структура

После выполнения команды и настройки ресурсов CLI сгенерирует исходную структуру проекта. Он будет включать:

• Папки служб и модулей;
• Шаблоны внешнего интерфейса (если применимо);
• Начальные настройки кэша, событий и интеграций;
• Файлы решения (.slnx) и проекта (.csproj), готовые к компиляции.

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

Добавление веб-приложения Backoffice

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

Веб-приложение не заменяет доменные службы. Он действует как визуальная точка входа для использования API, запуска команд, просмотра запросов и отображения экранов в соответствии с правилами, уже смоделированными в сервисах.

Шаг 1. Запуск команды создания

Чтобы добавить в проект новое веб-приложение, используйте:

lino web-app new

Alias lino webapp new также доступен для более удобного ввода. Во время выполнения укажите понятное имя веб-приложения; в этом примере мы используем Backoffice.

lino web-app new --name Backoffice

Шаг 2. Понимание созданной структуры

В конце процесса Lino создает начальную структуру Web App в src/WebApps/<WebAppName>. Для приложения Blazor структура может включать server/client проекты, общие ресурсы, файлы локализации, clients для потребления APIs и соглашения, которые позже будут использоваться lino page new.

• Папки для страниц, компонентов, макетов, сервисов и ресурсов приложения;
• Клиенты и контракты HTTP, необходимые для использования API, предоставляемых службами проекта;
• Ресурсы локализации и исходные шаблоны, используемые в веб-интерфейсе;
• Клиент-серверные проекты, когда тип приложения требует такого разделения;
• Соглашения о маршрутах, навигации и интеграции, которые будут повторно использоваться при создании страниц;
• Точки интеграции с аутентификацией и авторизацией при добавлении функции аутентификации в проект.

Шаг 3. Когда создавать веб-приложение в потоке

Если вы уже знаете, что у системы будет интерфейс Blazor, создайте Web App в самом начале, сразу после создания проекта. Так services, modules, entities, APIs и pages, созданные позже, уже будут согласованы с веб-приложением, которое будет их потреблять.

Этот поток особенно полезен, потому что services, созданные позже, также генерируют типизированные проекты Api.Contracts и Api.Client, потребляемые проектом Blazor. Когда Web App присутствует с самого начала, проще проверить полный путь: domain, API, contracts, HttpClient и экран.

Важные примечания

• Бэк-офис должен использовать данные через сгенерированные API, поддерживая бизнес-логику в правильных службах и модулях.
• Прежде чем открывать доступ к административным страницам, просмотрите аутентификацию, авторизацию, роли, разрешения и политики доступа.
• Вы можете создать несколько веб-приложений, например Backoffice внутренний и Site общедоступный, когда аудитории, разрешения, развертывания или обязанности различаются.
• Избегайте смешивания общедоступных и административных потоков в одном веб-приложении, если это затрудняет безопасность, навигацию, развертывание или владение командой.

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

Создание сервисов и модулей

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

Шаг 1: Определение услуг

Первоначально мы создадим следующие службы, каждая из которых будет иметь четко определенные обязанности:

• Catalog (модульный) – отвечает за управление товарами, категориями и ценами;
• Sales – отвечает за обработку продаж и заказов;
• Stock – отвечает за управление запасами и движением;
• Security – отвечает за аутентификацию, авторизацию и управление пользователями.

Чтобы создать services из примера, выполните по одной команде для каждого service. В wizard для Catalog выберите modular architecture; для остальных выберите architecture, подходящую для простой границы.

lino service new --name Catalog
lino service new --name Sales
lino service new --name Stock
lino service new --name Security

Во время выполнения команды CLI запросит:

• Имя service: например, Catalog;
• Отображаемое имя и архитектурный стиль: выберите простую architecture для компактных границ или modular, когда service имеет независимые связные области;
• База данных: выберите технологию, которая лучше всего подходит вашему проекту (SQL Server, PostgreSQL и т. д.);

Шаг 2: Создание modules внутри services

Не все services должны быть modular. В нашем project только service Catalog будет иметь modules, чтобы разделить ответственности, такие как merchandising и pricing.

Для service Catalog мы определяем следующие modules:

• Merchandising – управление продуктами и категориями;
• Pricing – управление ценами, акциями и историей изменений.

Чтобы создать modules для Catalog, выполните:

lino module new --service Catalog --name Merchandising
lino module new --service Catalog --name Pricing

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

Окончательная структура проекта

После создания сервисов и модулей ваше решение должно иметь структуру, подобную следующей:

MyApp/
└── src/
    ├── Aspire/
    ├── Integrations/
    ├── Services/
    │   ├── Catalog/
    │   │   ├── Modules/
    │   │   │   ├── Merchandising/
    │   │   │   └── Pricing/
    │   │   ├── MyApp.Catalog.Host
    │   │   └── MyApp.Catalog.Infrastructure
    │   ├── Sales/
    │   ├── Security/
    │   ├── Shared/
    │   └── Stock/
    └── WebApps/
        ├── Backoffice/
        │   ├── Services/
        │   │   ├── Catalog/
        │   │   ├── Sales/
        │   │   ├── Security/
        │   │   └── Stock/
        │   ├── MyApp.WebApp.Backoffice
        │   └── MyApp.WebApp.Backoffice.Client
        └── Shared/
            └── MyApp.WebApp.Shared
└── tests/
    └── Services/
        ├── Catalog/
        │   ├── Merchandising/
        │   └── Pricing/
        ├── Sales/
        ├── Security/
        ├── Shared/
        └── Stock/

Объяснение структуры:

• Services/: содержит все системные сервисы, каждый из которых изолирован своей бизнес-логикой, инфраструктурой и хостингом;
• Modules/: папки внутри модульных сервисов, позволяющие организовать определенные функции и поддерживать целостный код;
• WebApps/: интерфейсы, связанные с системой, уже интегрированные с сервисами;
• Shared/: библиотеки и ресурсы, совместно используемые службами и интерфейсами;
• tests/: модульные и интеграционные тесты, организованные по сервисам и модулям.

Благодаря такой модульной структуре каждая команда или разработчик может работать независимо над различными частями системы, что облегчает масштабируемость, обслуживание и тестирование. После создания сервисов и модулей запустите dotnet build чтобы убедиться, что проекты правильно подключены к решению, хосту Aspire, общим проектам и платформе тестирования.

Добавляем аутентификацию и авторизацию

Аутентификация и авторизация являются важными элементами любой современной системы. Аутентификация доказывает, кем является пользователь; авторизация определяет, что может выполнять этот пользователь. В Lino CLI функция аутентификации генерирует необходимую базу для пользователей, ролей, разрешений, токенов, политик доступа и интеграции с APIs.

Шаг 1. Запуск команды аутентификации

Чтобы добавить функции аутентификации и авторизации, используйте команду:

lino feature auth add

CLI проведет вас через следующие шаги:

• Выбор услуги или модуля: вам необходимо указать, куда будут установлены артефакты аутентификации. В нашем примере проекта мы используем сервис Security, который централизует всю логику безопасности системы;
• Дополнительные настройки: создание таблиц пользователей, ролей, разрешений, токенов и настройка политик доступа;
• Срок действия токена: определение срока действия токена доступа и токена обновления в соответствии с политикой безопасности продукта;
• Тип идентификатора пользователя: выбор типа, используемого пользовательской моделью и генерируемыми контрактами.

Шаг 2: Сгенерированная структура

После выполнения команды служба Security будет содержать файлы и папки, такие как:

• Домен/Объекты: агрегаты, сущности и правила для пользователей, ролей, разрешений и токенов;
• Инфраструктура/постоянство: конфигурации базы данных, сопоставления Entity Framework и миграции для таблиц безопасности;
• Приложение: Команды, запросы, обработчики, службы аутентификации, генерация токенов, проверка учетных данных и проверки разрешений;
• API/Хост: конечные точки для входа в систему, выхода из системы, регистрации, обновления токена и защищенных операций;
• Интеграция с веб-приложением: поддержка аутентифицированных потоков при наличии веб-приложения.

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

Добавление фоновых заданий

В распределенных и модульных системах, подобных той, которую мы строим. Lino CLI, не все службы взаимодействуют друг с другом напрямую. Чтобы обеспечить согласованность и надежность обмена информацией, мы используем интеграционные мероприятия. Однако для эффективной и асинхронной обработки этих событий нам необходимо Background Jobs.

Lino использует Outbox Pattern, чтобы гарантировать, что все сообщения, генерируемые службами, надежно записываются перед отправкой. Благодаря этому мы добились:

• Избегайте потери событий в случае сбоев или перезапусков сервиса;
• Убедитесь, что одно и то же сообщение отправляется только один раз;
• Разрешить повторную обработку сообщений в случае сбоя доставки;
• Отделите обработку событий от основной логики приложения, улучшая производительность и масштабируемость.

Шаг 1: Выполнение команды

Чтобы добавить поддержку фоновых заданий в ваш проект, выполните команду:

lino feature background-job add

CLI попросит вас выбрать службу, в которую будет установлено Background Job. Как правило, вы выбираете службу, которая централизует создание событий, например Catalog или Sales. В текущих опциях мастер также может запросить модуль, библиотеку заданий, необходимость обработки событий Outbox, расписание и размер пакета. Текущий поток шаблонов использует Hangfire для повторяющегося выполнения заданий.

Шаг 2. Настройка выполнения

В ходе настройки вы сможете определить:

• Интервал проверки: определяет, как часто Background Job будет проверять таблицу Outbox для новых сообщений. Слишком короткий интервал может увеличить использование ресурсов, а слишком длинный интервал может задержать доставку событий;
• Пакет записей, обрабатываемых одновременно: контролирует, сколько событий будет прочитано и отправлено за один запуск. Большие пакеты могут повысить производительность, но требуют больше памяти и обработки;
• Политика поиска: В случае сбоя отправки сообщений вы можете настроить, сколько раз задание будет пытаться отправить сообщение повторно.

Эти параметры зависят от размера вашей системы, мощности машины и ожидаемого объема событий.

Шаг 3: Сгенерированная структура

После настройки в проекте появится Background Job, готовое к обработке сообщений из таблиц. Outbox в каждом сервисе.

1. Вариант использования меняет домен и записывает домен или событие интеграции.
2. Единица работы сохраняет бизнес-данные и сообщения из Outbox в одной транзакции.
3. Hangfire запускает повторяющиеся задания, которые считывают ожидающие сообщения в пакетном режиме.
4. Сообщения публикуются в настроенном механизме интеграции, например RabbitMQ, когда асинхронная связь включена.
5. Завершенные, неудачные, старые или застрявшие сообщения могут обрабатываться с помощью логики и конфигурации, созданных для задания.

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

Создание сущностей и перечислений

В этом разделе мы подробно опишем дизайн сущностей приложения, перечислений и объектов значений, показав, в каких сервисах и модулях будет создан каждый элемент.

1. Создание сущности Category

Чтобы создать entity Category в сервисе Catalog и модуле Merchandising, выполните:

lino entity new --service Catalog --module Merchandising --name Category