evo-virtual-machine-sonarqube-lab

Проект служит демонстрацией интеграции SonarQube с приложением NestJS. Приложение предоставляет функциональный API сервис курсов валют, который получает данные о валютах в реальном времени от API Центрального Банка России (ЦБР). Основная цель - показать, как интегрировать и настроить SonarQube для анализа качества кода в проекте TypeScript/Node.js.

Цель проекта

Проект демонстрирует:

• Интеграция SonarQube: Полная настройка и конфигурация для анализа качества кода
• Лучшие практики качества кода: Реализация принципов чистого кода и тестирования
• Интеграция CI/CD: Как интегрировать SonarQube с рабочими процессами разработки
• Реальный пример: Практический NestJS сервис с комплексным тестированием и документацией

Функциональность API курсов валют служит примером реализации, в то время как интеграция SonarQube является основным фокусом.

Возможности

• Курсы валют в реальном времени: Получение текущих курсов валют от API ЦБР
• Запросы по конкретным валютам: Получение курсов валют для конкретных валют
• Мониторинг состояния: Комплексные эндпоинты проверки состояния для развертывания в production-окружение.
• Документация API: Автоматически генерируемая документация Swagger
• Поддержка CORS: Включен обмен ресурсами между источниками
• Обработка ошибок: Надежная обработка ошибок с HTTP статус-кодами

API Эндпоинты

Курсы валют

• GET /api/exchange-rates
  - Получить все доступные курсы валют
• GET /api/exchange-rates/:currency
  - Получить курс валюты для конкретной валюты (например, USD, EUR)

Проверки состояния

• GET /api/health-check
  - Простой статус состояния
• GET /api/health-check/detailed
  - Детальный статус состояния со всеми проверками
• GET /api/health-check/ready
  - Проверка готовности для Kubernetes
• GET /api/health-check/live
  - Проверка жизнеспособности для Kubernetes

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

• GET /api/docs
  - Документация API Swagger

Технологический стек

• Фреймворк: NestJS 11.x
• Язык: TypeScript
• HTTP клиент: Axios с @nestjs/axios
• Документация: Swagger/OpenAPI
• Тестирование: Jest
• Менеджер пакетов: Yarn
• Качество кода: SonarQube

Предварительные требования

• Node.js (v18 или выше)
• Менеджер пакетов Yarn

Установка

Запуск приложения

Тестирование

Интеграция SonarQube

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

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

Проект включает файл

Запуск анализа SonarQube

Предварительные требования

• Работающий сервер SonarQube (локальный или облачный)
• Установленный SonarQube Scanner
• Действительный токен SonarQube

Просмотр результатов SonarQube

После запуска анализа в CI/CD, вы можете просмотреть результаты в панели управления SonarQube:

1. Доступ к панели: Перейдите на ваш сервер SonarQube
2. Найти проект: Найдите
   evo-virtual-machine-sonar-qube-lab
   в списке проектов
3. Просмотр метрик: Проверьте страницу обзора для:
   • Общего статуса quality gate
   • Процента покрытия кода
   • Количества ошибок, уязвимостей и запахов кода
   • Оценки технического долга
4. Детальный анализ: Нажмите на конкретные проблемы, чтобы увидеть:
   • Расположение проблемы в коде
   • Серьезность и тип
   • Предлагаемые исправления
   • Исторические тренды

Quality Gates

Проект настроен с SonarQube Quality Gates, которые обеспечивают:

• Дублирование кода: Менее 3% дублированного кода
• Поддерживаемость: Рейтинг A или B
• Надежность: Рейтинг A или B
• Безопасность: Рейтинг A или B
• Точки безопасности: Рейтинг A или B

Метрики качества кода

SonarQube анализирует следующие метрики:

• Ошибки: Потенциальные ошибки времени выполнения
• Уязвимости: Уязвимости безопасности
• Запахи кода: Проблемы поддерживаемости
• Покрытие: Процент покрытия тестами
• Дублирования: Процент дублирования кода
• Технический долг: Оценка времени на исправление проблем

Реализованные лучшие практики

Этот проект демонстрирует несколько лучших практик качества кода:

• Комплексное тестирование: Модульные тесты с высоким покрытием
• Типобезопасность: Полная реализация TypeScript
• Обработка ошибок: Правильная обработка исключений
• Документация: Документация API с Swagger
• Структура кода: Чистая архитектура с разделением ответственности
• Линтинг: Конфигурация ESLint для согласованности кода

Получение помощи

• Документация SonarQube: https://docs.sonarqube.org/
• Форум сообщества: https://community.sonarsource.com/

Переменные окружения

• PORT
  - Порт сервера (по умолчанию: 3000)

Внешние зависимости

• API ЦБР: https://www.cbr-xml-daily.ru/daily_json.js
  • Предоставляет курсы валют в реальном времени для российского рубля
  • Обновляется ежедневно Центральным Банком России

Структура проекта

├── src/                    # Исходный код
│   ├── exchange-rates/     # Модуль курсов валют
│   │   ├── dto/           # Объекты передачи данных
│   │   ├── interfaces/    # TypeScript интерфейсы
│   │   ├── exchange-rates.controller.ts
│   │   ├── exchange-rates.service.ts
│   │   └── exchange-rates.module.ts
│   ├── health-check/      # Модуль мониторинга состояния
│   │   ├── health-check.controller.ts
│   │   ├── health-check.service.ts
│   │   └── health-check.module.ts
│   ├── app.controller.ts  # Основной контроллер приложения
│   ├── app.service.ts     # Основной сервис приложения
│   ├── app.module.ts      # Корневой модуль
│   └── main.ts           # Загрузка приложения
├── test/                  # Тестовые файлы
├── sonar-project.properties # Конфигурация SonarQube
├── package.json           # Зависимости и скрипты
├── tsconfig.json          # Конфигурация TypeScript
├── eslint.config.mjs      # Конфигурация ESLint
└── README.md             # Документация проекта

Разработка

Качество кода

Сборка

Развертывание

Этот сервис предназначен для развертывания в контейнеризованных средах (Docker, Kubernetes) с правильными эндпоинтами проверки состояния для систем оркестрации.

Лицензия

Этот проект лицензирован под MIT License.