cubenet_backend/README.md

Cubenet Backend - Микросервисная архитектура на Rust

Backend приложение с современной архитектурой микросервисов на Rust. Использует REST API для клиентов, gRPC для inter-service communication и Swagger для автоматической документации.

🏗️ Архитектура системы

┌─────────────┐
│   Клиент    │
└──────┬──────┘
       │ REST API
       ▼
┌──────────────────────────────────┐
│  API Gateway (8000)              │
│ ✓ REST endpoints                 │
│ ✓ Swagger UI (/swagger-ui)       │
│ ✓ OpenAPI docs (/api-docs)       │
└──────────┬───────────────────────┘
           │ gRPC
           ▼
    ┌──────────────────┐
    │  API (8001)      │
    │ ✓ gRPC Client    │
    └────────┬─────────┘
             │ gRPC
             ▼
  ┌────────────────────────────────┐
  │ Microservices (13000-14000)    │
  ├────────────────────────────────┤
  │ ✓ User Service (13001)         │
  │ ✓ Template Service (13000)     │
  │ ✓ Your Services (13002+)       │
  └────────────────────────────────┘

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

cubenet_backend/
├── api_gateway/              # REST Gateway с Swagger
│   ├── Cargo.toml
│   └── src/
│       └── main.rs          # REST endpoints + Swagger UI
│
├── api/                      # API слой (gRPC клиент)
│   ├── Cargo.toml
│   └── src/
│       └── main.rs          # gRPC->REST маршрутизация
│
├── microservices/
│   ├── user_service/        # Пример: User gRPC сервис
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   │
│   └── template_service/    # Шаблон для новых сервисов
│       ├── Cargo.toml
│       └── src/main.rs
│
├── shared_proto/            # Shared Proto Buffers
│   ├── build.rs            # Build script
│   ├── Cargo.toml
│   ├── src/lib.rs
│   └── proto/
│       ├── user.proto
│       └── api.proto
│
├── ARCHITECTURE.md          # Подробная документация архитектуры
├── MICROSERVICE_GUIDE.md    # Гайд создания микросервисов
└── Cargo.toml              # Workspace конфигурация

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

Требования

• Rust 1.70+
• Cargo

Запуск всех компонентов (в разных терминалах)

Терминал 1 - User Service (gRPC на 13001):

cargo run -p user_service

Терминал 2 - API (gRPC клиент на 8001):

cargo run -p api

Терминал 3 - API Gateway (REST + Swagger на 8000):

cargo run -p api_gateway

Доступ к Swagger UI

После запуска API Gateway, откройте в браузере:

http://localhost:8000/swagger-ui

Или просмотрите OpenAPI JSON:

http://localhost:8000/api-docs

🔌 API endpoints

Health Check

curl http://localhost:8000/api/health

Ответ:

{
  "status": "OK"
}

Get All Users

curl http://localhost:8000/api/users

Ответ:

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com"
  }
]

Create User

curl -X POST http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Charlie","email":"charlie@example.com"}'

📊 Протоколы коммуникации

Компонент	Порт	Протокол	Назначение
API Gateway	8000	HTTP/REST	Клиент ↔ Система
API	8001	HTTP/REST	Internal
User Service	13001	gRPC	Микросервис
Custom Services	13000-14000	gRPC	Микросервисы

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

• Axum 0.7 - Веб-фреймворк (REST)
• Tonic 0.11 - gRPC framework
• Tokio 1.35 - Async runtime
• Serde - Сериализация JSON
• Prost 0.12 - Protocol Buffers компилятор
• Tower - Middleware и utilities
• Tracing - Логирование

📚 Создание нового микросервиса

Быстрый способ

# 1. Скопировать шаблон
cp -r microservices/template_service microservices/my_service

# 2. Обновить Cargo.toml
sed -i 's/template_service/my_service/g' microservices/my_service/Cargo.toml

# 3. Добавить в workspace Cargo.toml
# Добавьте "microservices/my_service" в members

# 4. Выбрать порт и реализовать сервис
# Отредактируйте microservices/my_service/src/main.rs

Подробнее см. MICROSERVICE_GUIDE.md

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

Проверить что всё компилируется

cargo check

Собрать всё

cargo build

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

cargo run -p api_gateway
cargo run -p api
cargo run -p user_service

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

• ARCHITECTURE.md - Полная архитектура системы
• MICROSERVICE_GUIDE.md - Гайд создания микросервисов

🔐 Выделение портов

Зарезервированные порты

• 8000 - API Gateway (REST)
• 8001 - API (REST/Internal)
• 13000-14000 - Микросервисы (gRPC)

Используемые микросервисы

• 13001 - User Service

Доступные для вас

• 13000 - Template Service (шаблон)
• 13002-14000 - Ваши сервисы

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

Все конфигурационные параметры расположены в src/main.rs каждого компонента:

API Gateway:

let addr = SocketAddr::from(([127, 0, 0, 1], 8000));

API:

let addr = SocketAddr::from(([127, 0, 0, 1], 8001));

User Service:

let addr = "127.0.0.1:13001".parse()?;

🐛 Отладка

Включить подробное логирование

RUST_LOG=debug cargo run -p api_gateway
RUST_LOG=trace cargo run -p user_service

Проверить что gRPC сервис запущен

# Установить grpcurl
# https://github.com/fullstorydev/grpcurl

grpcurl -plaintext localhost:13001 list

📝 Особенности

✅ Модульная архитектура - Каждый сервис независим
✅ REST API - Standard HTTP endpoints
✅ Swagger UI - Автоматическая документация
✅ gRPC - Высокопроизводительный inter-service communication
✅ Proto Buffers - Типобезопасные структуры данных
✅ Масштабируемость - Легко добавлять новые микросервисы
✅ Логирование - Встроенное логирование через Tracing

🤝 Лучшие практики

1. Изолируйте сервисы - Каждый микросервис в отдельной папке
2. Используйте Proto - Все API-контракты через .proto файлы
3. Назначайте порты - Микросервисы должны быть в диапазоне 13000-14000
4. Логируйте правильно - Используйте tracing вместо println!
5. Обрабатывайте ошибки - Возвращайте gRPC Status вместо паники

📞 Помощь

• Читайте ARCHITECTURE.md для понимания системы
• Читайте MICROSERVICE_GUIDE.md при создании нового сервиса
• Проверяйте логи сервисов для отладки
• Используйте Swagger UI для тестирования endpoints

📄 Лицензия

MIT License