YA.ServiceTemplate

RU, EN

О проекте

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

Приложение полностью готово к

• использованию вашего любимого ORM-фреймворка вместо репозитория в памяти
• подключению аутентификации на базе JWT-токенов

Статья с подробностями о системе логирования: https://habr.com/ru/post/489188/

Компоненты

• Платформа: .Net 6
• Взаимодействие: очереди сообщений (MassTransit + RabbitMQ)
• Логирование и трассировка: Serilog, ELK, ApplicationInsights
• Секреты: AWS Parameter Store
• Валидация моделей: FluentValidation
• Документация: Swagger (OpenAPI v3)

Ключевые особенности

Дизайн

Предметно-ориентированная структура приложения (DDD) отделяет бизнес-логику от ядра и инфраструктуры. Слой команд отделяет бизнес-логику от слоя представления (напр. веб-запроса или события шины данных). Вся поддерживающая инфраструктура реализована в виде внутренних сервисов.

Идемпотентность

При получении дубликата HTTP-запроса (запрос с одинаковым ключом идемпотентности) приложение выдаёт ответы из кеша, чтобы защитить целостность данных.

Состояние

Приложение бессостоятельное, поэтому может использоваться c системами оркестрации (напр. Kubernetes) для горизонтального масштабирования.

Обновление

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

Логирование

Для сквозного межпроцессного журналирования:

• все http-запросы имеют заголовки с корелляционным ИД (добавляется на бекенде)
• все сообщения в шину данных содержат корелляционный ИД

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

Мониторинг

Микросервис включает в себя страницу с проверками здоровья (/status) и метриками (/metrics), которую может использовать система мониторинга, работающая по модели считывания (напр. Prometheus).

Секреты

Конфиденциальные настройки приложения хранятся в переменных окружения и на внешнем хранилище (AWS Systems Manager).

Документация

Для фронтенд разработчиков имеется веб-апи документация на базе Swagger (/swagger)

Настройка и запуск

Перед запуском приложение необходимо сконфигурировать.

Достать ресурсы

Для запуска приложению необходимы следующие ресурсы:

• Хранилище Секретов AWS
• Брокер сообщений RabbitMQ

Опционально:

• Токен доступа Logz.IO
• Ключ инструментирования Application Insights

Хранилище Секретов

• Откройте https://aws.amazon.com/ru/ и создайте бесплатную учётную запись
• Откройте https://console.aws.amazon.com и перейдите в раздел Security Credentials (IAM)
  • Создайте новую политику доступа, которая будет содержать следующие права

  {
   "Version": "2012-10-17",
   "Statement": [
       {
           "Action": [
               "ssm:DescribeParameters",
               "ssm:GetParameter",
               "ssm:GetParametersByPath",
               "ssm:GetParameters",
               "ssm:GetParameter"
           ],
           "Effect": "Allow",
           "Resource": "arn:aws:ssm:*:*:*"
       }
     ]
   }

  • Создайте новую учётную запись пользователя с доступом на основе созданной политики (выберите "программный доступ") чтобы получить Ключ Доступа и Секретный Ключ

Брокер сообщений RabbitMQ

Откройте https://www.cloudamqp.com/ и зарегистрируйтесь на бесплатном тарифе чтобы получить строку подключения вида amqp://{login}:{password}@{host}/{vhost}

Логирование LogzIO

Если вы хотите использовать Логстеш и Кибану для управления логами, то можете воспользоваться логированием от Logz.IO. Откройте https://logz.io и зарегистрируйтесь на бесплатном тарифе (выберите один из европейских датацентров), чтобы получить токен доступа

Телеметрия Application Insights

Если вы хотите развернуть приложение на платформе Miscrosoft Azure, то можете дополнительно воспользоваться телеметрией Application Insights. Откройте https://portal.azure.com, перейдите в раздел Application Insights и добавьте новый ресурс чтобы получить ключ инструментирования

Конфигурация

• Снова откройте https://console.aws.amazon.com, выберите регион Амазона "Europe (Frankfurt) eu-central-1" и перейдите в сервис Systems Manager

• Откройте раздел "Управление Приложениями -> Хранилище Параметров" и добавьте параметры с полученными в предыдущих пунктах значениями:

  • /development/messagebushost
  • /development/messagebusvhost
  • /development/messagebuslogin
  • /development/messagebuspassword
  • /development/logziotoken (опционально)
  • /development/appinsightsinstrumentationkey (опционально)

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

  • AWS_ACCESS_KEY_ID: {Ключ Доступа}
  • AWS_SECRET_ACCESS_KEY: {Секретный Ключ}

Запуск

Выберите профиль запуска 'Kestrel' и запустите приложение.

Лицензия

МИТ