evo-managed-kafka-microservices Kafka Microservices

Микросервисная архитектура на базе NestJS и Apache Kafka для демонстрации архитектуры на основе брокеров сообщений.

Пример носит демонстрационный характер без реальной реализации сервисов.

Описание

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

• API Service - REST API для приема HTTP-запросов и публикации событий в Kafka
• Orders Service - сервис обработки заказов, подписанный на топик заказов
• Notifications Service - сервис уведомлений, подписанный на топик заказов

Архитектура

┌─────────┐      HTTP       ┌─────────┐
│ Client  │ ──────────────> │   API   │
└─────────┘                 └────┬────┘
                                 │
                                 │ Kafka Producer
                                 │ (orders-topic)
                                 │
                    ┌────────────┴────────────┐
                    │                         │
                    ▼                         ▼
            ┌──────────────────────────────────────┐
            │         Apache Kafka Broker          │
            │         (orders-topic)               │
            └────────────┬─────────────────────────┘
                         │
                         │ Kafka Consumers
                         │
            ┌────────────┴────────────┐
            │                         │
            ▼                         ▼
    ┌──────────────┐         ┌──────────────┐
    │   Orders     │         │Notifications │
    │   Service    │         │   Service    │
    │ (Consumer)   │         │ (Consumer)   │
    └──────────────┘         └──────────────┘

Поток данных:

1. Клиент отправляет HTTP POST запрос на API сервис
2. API сервис валидирует данные и публикует событие в Kafka топик orders-topic
3. Orders Service и Notifications Service подписаны на этот топик и получают события параллельно
4. Каждый сервис обрабатывает событие независимо

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

• NestJS - фреймворк для построения масштабируемых Node.js приложений
• Apache Kafka - распределенная платформа потоковой обработки данных
• TypeScript - типизированный JavaScript
• Docker - контейнеризация приложений
• Docker Compose - оркестрация микросервисов

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

kafka_microservices/
├── apps/
│   ├── api/              # API сервис (REST API + Kafka Producer)
│   │   ├── src/
│   │   │   ├── orders/   # Контроллер заказов
│   │   │   ├── kafka/    # Модуль Kafka
│   │   │   └── main.ts   # Точка входа
│   │   └── Dockerfile
│   ├── orders/           # Сервис обработки заказов (Kafka Consumer)
│   │   ├── src/
│   │   │   ├── orders/   # Обработчик событий заказов
│   │   │   └── main.ts   # Точка входа
│   │   └── Dockerfile
│   └── notifications/    # Сервис уведомлений (Kafka Consumer)
│       ├── src/
│       │   ├── notifications/  # Обработчик уведомлений
│       │   └── main.ts   # Точка входа
│       └── Dockerfile
├── shared/
│   └── dto/              # Общие DTO для всех сервисов
│       └── create-order.dto.ts
├── docker-compose.yml    # Конфигурация для внешнего Kafka
└── package.json          # Зависимости и скрипты проекта

Требования

• Node.js (версия 18 или выше)
• Yarn
• Docker и Docker Compose
• Apache Kafka (локально или удаленно)

Установка

1. Клонируйте репозиторий:

git clone <repository-url>
cd kafka_microservices

2. Установите зависимости:

yarn install

3. Создайте файл .env в корне проекта:

# Скопируйте пример конфигурации
cp .env.example .env

Или создайте .env вручную на основе .env.example. Пример минимальной конфигурации:

KAFKA_BROKERS=localhost:9092
API_PORT=3000
KAFKA_CLIENT_ID_API=api-service
KAFKA_CLIENT_ID_ORDERS=orders-service
KAFKA_CLIENT_ID_NOTIFICATIONS=notifications-service
KAFKA_TOPIC_ORDERS=orders-topic
# Optional: auth for secured Kafka cluster
# KAFKA_USERNAME=my-user
# KAFKA_PASSWORD=my-password
# KAFKA_SASL_MECHANISM=scram-sha-512    # default: scram-sha-512 (matches Python config)
# KAFKA_SSL=false                       # default: false (SASL_PLAINTEXT)

Запуск

Локальная разработка

Запуск всех сервисов в режиме разработки:

# Терминал 1: API сервис
yarn start:api:dev

# Терминал 2: Orders сервис
yarn start:orders:dev

# Терминал 3: Notifications сервис
yarn start:notifications:dev

Запуск через Docker Compose

Использует docker-compose.yml и требует внешний Kafka брокер:

# Создайте .env файл с настройками Kafka
# KAFKA_BROKERS=host.docker.internal:9092

# Сборка и запуск всех сервисов
yarn docker:deploy

# Просмотр логов
yarn docker:logs

# Остановка сервисов
yarn docker:down

Использование API

Swagger документация

После запуска API сервиса, Swagger документация доступна по адресу:

• http://localhost:3000/api

Создание заказа

curl -X POST http://localhost:3000/orders \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "goodId": "prod-123",
    "count": 5
  }'

Ответ:

{
  "message": "Order published to Kafka",
  "order": {
    "email": "customer@example.com",
    "goodId": "prod-123",
    "count": 5
  }
}

Параметры запроса:

• email (string, required) - Email адрес клиента
• goodId (string, required) - ID товара/продукта
• count (number, required, min: 1) - Количество товара

После публикации заказа в Kafka, события автоматически получают:

• Orders Service - обрабатывает заказ
• Notifications Service - отправляет уведомление

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

Переменная	Описание	Значение по умолчанию	Где используется
KAFKA_BROKERS	Адреса брокеров Kafka (через запятую)	localhost:9092	Все сервисы
API_PORT	Порт API сервиса	3000	API сервис
KAFKA_CLIENT_ID_API	ID клиента для API сервиса	api-service	API сервис
KAFKA_CLIENT_ID_ORDERS	ID клиента для Orders сервиса	orders-service	Orders сервис
KAFKA_CLIENT_ID_NOTIFICATIONS	ID клиента для Notifications сервиса	notifications-service	Notifications сервис
KAFKA_TOPIC_ORDERS	Название топика для заказов	orders-topic	Все сервисы
KAFKA_USERNAME	Логин для Kafka (SASL)	-	Все сервисы (опционально)
KAFKA_PASSWORD	Пароль для Kafka (SASL)	-	Все сервисы (опционально)
KAFKA_SASL_MECHANISM	Механизм SASL (plain, scram-*)	scram-sha-512	Все сервисы (опционально)
KAFKA_SSL	Включить SSL (true/false)	false	Все сервисы (опционально)
NODE_ENV	Окружение выполнения	-	Docker контейнеры

Доступные команды

Разработка

• yarn build - сборка проекта
• yarn start - запуск проекта (по умолчанию API)
• yarn start:dev - запуск в режиме разработки с hot-reload
• yarn start:debug - запуск в режиме отладки
• yarn start:prod - запуск в production режиме

Запуск отдельных сервисов

• yarn start:api - запуск API сервиса
• yarn start:api:dev - запуск API сервиса в режиме разработки
• yarn start:orders - запуск Orders сервиса
• yarn start:orders:dev - запуск Orders сервиса в режиме разработки
• yarn start:notifications - запуск Notifications сервиса
• yarn start:notifications:dev - запуск Notifications сервиса в режиме разработки

Docker команды

• yarn docker:build - сборка Docker образов
• yarn docker:deploy - развертывание через Docker Compose
• yarn docker:down - остановка контейнеров
• yarn docker:logs - просмотр логов всех сервисов

Инструменты разработки

• yarn lint - проверка кода линтером с автоматическим исправлением
• yarn format - форматирование кода с помощью Prettier

Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE для подробностей.