🚀 Микросервисная архитектура на Go

Проект представляет собой современную микросервисную систему для управления заказами на сборку космических кораблей. Реализована с использованием cloud-native паттернов: event-driven архитектура, distributed tracing, централизованное логирование и строгий контроль качества кода.

🏗 Архитектура

Схема взаимодействия сервисов

                    ┌─────────────────┐
                    │   Client (UI)   │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
              ▼              ▼              ▼
        ┌─────────┐   ┌──────────┐   ┌──────────┐
        │  Order  │   │ Inventory│   │ Payment  │
        │  :8080  │   │  :8081   │   │  :8082   │
        └────┬────┘   └────┬─────┘   └────┬─────┘
             │             │              │
             └─────────────┼──────────────┘
                           │ gRPC
                    ┌──────▼──────┐
                    │     IAM     │
                    │   :50053    │
                    └──────┬──────┘
                           │
                    ┌──────▼──────┐
                    │    Kafka    │
                    │   :9092     │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
        ┌──────────┐ ┌────────────┐ ┌────────────┐
        │ Assembly │ │Notification│ │   Order    │
        │ Consumer │ │  Consumer  │ │  Consumer  │
        └──────────┘ └────────────┘ └────────────┘

Бизнес-процесс заказа

Клиент → Order API → Создание заказа (статус: PENDING_PAYMENT)
Клиент → Payment API → Оплата заказа
Payment → Kafka: order.paid → Событие оплаты
Assembly (consumer) → Сборка корабля
Assembly → Kafka: order.assembled → Событие сборки
Notification (consumer) → Отправка уведомления клиенту

Сервисы

Сервис	Порт gRPC	Порт HTTP	Описание
IAM	50053	—	Аутентификация, авторизация, управление сессиями
Inventory	50051	8081	Каталог деталей (REST + gRPC)
Order	—	8080	REST API для заказов
Payment	50052	8082	Обработка платежей (REST + gRPC)
Assembly	—	—	Consumer Kafka событий
Notification	—	—	Consumer Kafka событий (Telegram, Email)

Kafka топиков

Топик	Продюсер	Консьюмер	Описание
`order.paid`	Payment	Assembly, Notification, Order	Событие оплаты заказа
`order.assembled`	Assembly	Notification	Событие сборки заказа

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

Основные технологии

Компонент	Версия	Описание
Go	1.25.5	Язык программирования
gRPC	1.78.0	RPC-фреймворк для межсервисной коммуникации
Protobuf	1.36.11	Сериализация данных
gRPC-Gateway	2.27.7	REST-to-gRPC проксирование
OGen	1.18.0	Генерация HTTP-клиентов из OpenAPI
Buf	1.53.0	Управление Protobuf файлами

Базы данных и хранилища

Сервис	БД	Назначение
IAM	PostgreSQL 17.0	Хранение пользователей и сессий
IAM	Redis 7.2.5	Кэширование сессий
Inventory	MongoDB 7.0.5	Каталог деталей
Order	PostgreSQL 17.0	Заказы

Message Broker

Компонент	Версия	Назначение
Kafka	Confluent 7.9.0	Асинхронная коммуникация между сервисами
Kafka UI	0.7.2	Веб-интерфейс для управления Kafka

Логирование и мониторинг

Компонент	Версия	Назначение
OpenTelemetry Collector	0.123.0	Сбор телеметрии
Jaeger	2.6.0	Distributed tracing
Prometheus	3.3.1	Метрики
Grafana	12.0.0	Визуализация метрик
Elasticsearch	9.0.4	Централизованное логирование
Kibana	9.0.4	UI для Elasticsearch
Zap	1.27.1	Структурированное логирование

Веб-фреймворки

Библиотека	Назначение
chi/v5	HTTP-роутер для Order сервиса
grpc-gateway	REST-to-gRPC для Inventory и Payment

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

Инструмент	Версия	Назначение
golangci-lint	latest	Линтер
gci	v0.13.6	Сортировка импортов
gofumpt	v0.8.0	Строгий форматтер
mockery	v2.53.3	Генерация моков
grpcurl	v1.9.3	Тестирование gRPC
yq	v4.45.2	Работа с YAML
envsubst	v1.4.3	Подстановка переменных окружения

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

microservices_golang-main/
├── assembly/              # Сервис сборки кораблей (Kafka consumer)
│   ├── cmd/
│   ├── internal/
│   │   ├── config/
│   │   └── service/
│   └── go.mod
│
├── iam/                   # Identity & Access Management
│   ├── cmd/
│   ├── internal/
│   │   ├── api/          # gRPC handlers
│   │   ├── app/
│   │   ├── config/
│   │   ├── converter/
│   │   ├── interceptor/
│   │   ├── model/
│   │   ├── repository/
│   │   └── service/
│   ├── migrations/       # SQL миграции (goose)
│   └── go.mod
│
├── inventory/            # Каталог деталей
│   ├── cmd/
│   ├── internal/
│   │   ├── api/
│   │   ├── config/
│   │   ├── converter/
│   │   ├── model/
│   │   ├── repository/
│   │   └── service/
│   └── go.mod
│
├── notification/         # Уведомления (Telegram, Email)
│   ├── cmd/
│   ├── internal/
│   └── go.mod
│
├── order/                # Управление заказами
│   ├── cmd/
│   ├── internal/
│   │   ├── api/
│   │   ├── config/
│   │   ├── converter/
│   │   ├── model/
│   │   ├── repository/
│   │   └── service/
│   ├── migrations/
│   └── go.mod
│
├── payment/              # Обработка платежей
│   ├── cmd/
│   ├── internal/
│   │   ├── api/
│   │   ├── config/
│   │   ├── converter/
│   │   ├── model/
│   │   ├── repository/
│   │   └── service/
│   └── go.mod
│
├── pkg/                  # Сгенерированные Protobuf модели
│   └── proto/
│       ├── auth/v1/
│       ├── inventory/v1/
│       └── payment/v1/
│
├── platform/             # Общие утилиты платформы
│   ├── pkg/
│   │   ├── cache/        # Redis клиент
│   │   ├── closer/       # Graceful shutdown
│   │   ├── grpc/         # gRPC утилиты
│   │   ├── kafka/        # Kafka продюсер/консьюмер
│   │   ├── logger/       # Zap + OpenTelemetry
│   │   ├── metrics/      # Prometheus метрики
│   │   ├── middleware/   # HTTP/gRPC middleware
│   │   ├── migrator/     # Goose миграции
│   │   ├── testcontainers/
│   │   └── tracing/      # OpenTelemetry трейсинг
│   └── go.mod
│
├── shared/               # Общие Primitives
│   ├── api/              # OpenAPI спецификации
│   │   └── order/v1/
│   └── proto/            # Protobuf определения
│       ├── auth/v1/
│       ├── common/v1/
│       ├── events/v1/
│       ├── inventory/v1/
│       ├── payment/v1/
│       └── user/v1/
│
├── deploy/
│   ├── compose/          # Docker Compose конфигурация
│   │   ├── core/         # Инфраструктура
│   │   ├── iam/
│   │   ├── inventory/
│   │   ├── order/
│   │   ├── payment/
│   │   ├── assembly/
│   │   └── notification/
│   ├── docker/           # Dockerfile'ы
│   └── env/              # Переменные окружения
│       ├── .env.template
│       └── generate-env.sh
│
├── .golangci.yml         # Конфигурация линтера
├── .mockery.yaml         # Конфигурация генерации моков
├── buf.work.yaml         # Buf workspace конфигурация
├── go.work               # Go workspace
├── Taskfile.yml          # Задачи сборки (task)
└── package.json          # Node.js зависимости (redocly)

🚀 Быстрый старт

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

Go 1.25.5+
Docker и Docker Compose
Task (task runner)
Node.js (для redocly)

Установка зависимостей

# Установить все инструменты разработки
task install-formatters
task install-golangci-lint
task install-buf
task proto:install-plugins
task mockery:install
task redocly-cli:install

# Или одной командой (неявно установится при запуске соответствующих задач)

Генерация конфигурации

# Сгенерировать .env файлы из шаблона
task env:generate

Запуск всех сервисов

# Поднять всю инфраструктуру и сервисы
task up-all

Генерация кода

# Сгенерировать код из Protobuf и OpenAPI спецификаций
task gen

Проверка сервисов

# Тестирование IAM сервиса
task test-iam

# Тестирование безопасности API
task test-api-auth-rejection

💻 Разработка

Форматирование кода

# Отформатировать весь проект
task format

Линтинг

# Запустить линтер для всех модулей
task lint

Генерация кода

# Генерация Go-кода из Protobuf
task proto:gen

# Генерация из OpenAPI спецификаций
task ogen:gen

# Генерация mock-объектов
task mockery:gen

# Вся генерация сразу
task gen

Обновление зависимостей

task deps:update

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

Юнит-тесты

# Запустить юнит-тесты для всех модулей
task test

Интеграционные тесты

# Запустить интеграционные тесты
task test-integration

E2E тесты по сервисам

# Payment сервис
task e2e:test:payment

# Inventory сервис
task e2e:test:inventory

# Order сервис
task e2e:test:order

Покрытие тестами

# Запустить тесты с расчётом покрытия
task test-coverage

# Сгенерировать HTML-отчёт и открыть в браузере
task coverage:html

🌐 API

IAM Service (gRPC)

Protobuf: shared/proto/auth/v1/auth.proto

service IAMService {
    rpc Login(LoginRequest) returns (LoginResponse);
    rpc Whoami(WhoamiRequest) returns (WhoamiResponse);
}

Аутентификация:

Session-based через Redis
Заголовок HTTP: X-Session-Uuid
gRPC Metadata: session-uuid
TTL сессии: 24 часа

Inventory Service (gRPC + REST)

Protobuf: shared/proto/inventory/v1/inventory.proto

Метод	gRPC	REST
GetPart	`GetPart()`	`GET /api/v1/parts/{uuid}`
ListParts	`ListParts()`	`GET /api/v1/parts`

Order Service (REST)

OpenAPI: shared/api/order/v1/order.openapi.yaml

Метод	Endpoint	Описание
`POST`	`/api/v1/orders`	Создание заказа
`GET`	`/api/v1/orders/{uuid}`	Получение заказа
`POST`	`/api/v1/orders/{uuid}/pay`	Оплата заказа
`POST`	`/api/v1/orders/{uuid}/cancel`	Отмена заказа

Payment Service (gRPC + REST)

Protobuf: shared/proto/payment/v1/payment.proto

Метод	gRPC	REST
PayOrder	`PayOrder()`	`POST /api/v1/payments`

📊 Мониторинг и наблюдаемость

Prometheus

URL: http://localhost:9090
Scrape interval: 15s

Grafana

URL: http://localhost:3000
Login: admin / admin
Анонимный доступ: включён (только просмотр)

Jaeger

URL: http://localhost:16686
Хранение: Badger (7 дней)

Elasticsearch + Kibana

Elasticsearch: http://localhost:9200
Kibana: http://localhost:5601
Data View: easy-logs* (создаётся автоматически)

Kafka UI

URL: http://localhost:8090

📦 Полезные команды

Управление сервисами

# Поднять все сервисы
task up-all

# Остановить все сервисы
task down-all

# Поднять только инфраструктуру (Kafka, Jaeger, Prometheus, etc.)
task up-core

# Остановить инфраструктуру
task down-core

# Поднять конкретный сервис с зависимостями
task up-inventory
task up-order
task up-iam

# Остановить конкретный сервис
task down-inventory
task down-order
task down-iam

Работа с Protobuf

# Сгенерировать код из .proto файлов
task proto:gen

# Проверить .proto файлы на соответствие стилю
task proto:lint

Работа с OpenAPI

# Собрать OpenAPI спецификации в один файл
task redocly-cli:bundle

# Сгенерировать код из OpenAPI
task ogen:gen

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

# Тестирование IAM (регистрация, логин, whoami)
task test-iam

# Тестирование отклонения неавторизованных запросов
task test-api-auth-rejection

# Тестирование API с аутентификацией
task test-api-with-auth

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

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

Все переменные окружения находятся в deploy/env/.env. Для генерации из шаблона:

task env:generate

Ключевые переменные

# IAM
IAM_GRPC_PORT=50053
IAM_POSTGRES_PORT=5444
IAM_REDIS_PORT=6333
IAM_SESSION_TTL=24h

# Inventory
INVENTORY_GRPC_PORT=50051
INVENTORY_GATEWAY_PORT=8081
INVENTORY_MONGO_PORT=27018

# Order
ORDER_HTTP_PORT=8080
ORDER_POSTGRES_PORT=5435
ORDER_KAFKA_BROKERS=localhost:9092

# Kafka
KAFKA_EXTERNAL_PORT=9092
KAFKA_UI_PORT=8090

📝 Code Quality

golangci-lint

Включенные линтеры:

errcheck, staticcheck, govet, gocritic, revive
unused, gosec (безопасность), bodyclose
asciicheck, cyclop, dupl, ineffassign
unparam, errorlint, errname, forbidigo
contextcheck, containedctx

Запрещённые паттерны:

fmt.Print* — использовать структурированный логгер
time.Sleep — использовать таймеры/контекст
http.DefaultClient — создавать клиент с таймаутами

Форматирование

gofumpt — строгое форматирование кода
gci — сортировка импортов (Standard → Default → Project)

🐳 Docker

Структура compose файлов

deploy/compose/
├── core/           # Инфраструктура
├── iam/            # IAM + PostgreSQL + Redis
├── inventory/      # Inventory + MongoDB
├── order/          # Order + PostgreSQL
├── payment/        # Payment
├── assembly/       # Assembly (.env только)
└── notification/   # Notification (.env только)

Сеть

Все сервисы используют общую сеть microservices-net.

📚 Дополнительные ресурсы

🤝 Вклад в проект

Сделайте форк репозитория
Создайте ветку для фичи (git checkout -b feature/amazing-feature)
Закоммитьте изменения (git commit -m 'Add amazing feature')
Запушьте ветку (git push origin feature/amazing-feature)
Откройте Pull Request

Name		Name	Last commit message	Last commit date
Latest commit History 56 Commits
.github		.github
assembly		assembly
deploy		deploy
iam		iam
inventory		inventory
notification		notification
order		order
payment		payment
pkg		pkg
platform		platform
shared		shared
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.mockery.yaml		.mockery.yaml
.mockery_boilerplate_text.txt		.mockery_boilerplate_text.txt
README.md		README.md
Taskfile.yml		Taskfile.yml
buf.work.yaml		buf.work.yaml
go.work		go.work
go.work.sum		go.work.sum
main		main
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

🚀 Микросервисная архитектура на Go

📋 Содержание

🏗 Архитектура

Схема взаимодействия сервисов

Бизнес-процесс заказа

Сервисы

Kafka топиков

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

Основные технологии

Базы данных и хранилища

Message Broker

Логирование и мониторинг

Веб-фреймворки

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

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

🚀 Быстрый старт

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

Установка зависимостей

Генерация конфигурации

Запуск всех сервисов

Генерация кода

Проверка сервисов

💻 Разработка

Форматирование кода

Линтинг

Генерация кода

Обновление зависимостей

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

Юнит-тесты

Интеграционные тесты

E2E тесты по сервисам

Покрытие тестами

🌐 API

IAM Service (gRPC)

Inventory Service (gRPC + REST)

Order Service (REST)

Payment Service (gRPC + REST)

📊 Мониторинг и наблюдаемость

Prometheus

Grafana

Jaeger

Elasticsearch + Kibana

Kafka UI

📦 Полезные команды

Управление сервисами

Работа с Protobuf

Работа с OpenAPI

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

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

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

Ключевые переменные

📝 Code Quality

golangci-lint

Форматирование

🐳 Docker

Структура compose файлов

Сеть

📚 Дополнительные ресурсы

🤝 Вклад в проект

📄 Лицензия

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages