cubenet_backend/ARCHITECTURE.md

Архитектура Cubenet Backend

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

┌─────────────┐
│   Клиент    │
└──────┬──────┘
       │ REST API
       ▼
┌─────────────────────────────────┐
│     API Gateway (8000)          │
│ - REST endpoints                │
│ - Swagger UI (/swagger-ui)      │
└──────────┬──────────────────────┘
           │ gRPC
           ▼
    ┌──────────────────┐
    │  API (8001)      │
    │ - gRPC Client    │
    └────────┬─────────┘
             │ gRPC
             ▼
    ┌──────────────────────────────────────┐
    │  Microservices (13000-14000)         │
    ├──────────────────────────────────────┤
    │ - User Service (13001)               │
    │ - Template Service (13000+)          │
    │ - [Ваши сервисы]                     │
    └──────────────────────────────────────┘

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

REST API (Client ↔ API Gateway)

• Порт: 8000
• Описание: REST endpoints для клиентов
• Документация: Swagger UI на /swagger-ui/
• Endpoints:
  • GET /api/health - проверка здоровья
  • GET /api/users - получить список пользователей
  • POST /api/users - создать пользователя

gRPC (API Gateway ↔ API)

• Порт: 9000 (зарезервирован)
• Описание: Internal communication

gRPC (API ↔ Microservices)

• Порты: 13000-14000
• Диапазон: Для каждого микросервиса свой порт
• Примеры:
  • User Service: 13001
  • Другие сервисы: 13002-14000

📁 Структура каталогов

cubenet_backend/
├── api_gateway/
│   ├── Cargo.toml
│   └── src/
│       └── main.rs          # REST endpoints + Swagger
│
├── api/
│   ├── Cargo.toml
│   └── src/
│       └── main.rs          # gRPC клиент + REST
│
├── microservices/
│   ├── user_service/        # gRPC сервис пользователей
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   │
│   └── template_service/    # Шаблон для новых сервисов
│       ├── Cargo.toml
│       └── src/main.rs
│
├── shared_proto/            # Proto определения
│   ├── Cargo.toml
│   ├── build.rs
│   ├── src/lib.rs
│   └── proto/
│       ├── user.proto
│       └── api.proto
│
└── Cargo.toml              # Workspace конфигурация

🚀 Запуск проекта

Всё сразу (требует 3 терминала)

Терминал 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 Documentation

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

http://localhost:8000/swagger-ui/

Здесь вы сможете:

• Просмотреть все доступные endpoints
• Тестировать API requests
• Изучать схему данных

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

Шаг 1: Скопировать шаблон

cp -r microservices/template_service microservices/my_service

Шаг 2: Обновить Cargo.toml

[package]
name = "my_service"

Шаг 3: Добавить в workspace (корневой Cargo.toml)

[workspace]
members = ["api_gateway", "api", "microservices/user_service", "microservices/my_service"]

Шаг 4: Определить proto файл

# Добавить my_service.proto в shared_proto/proto/
# Обновить shared_proto/src/lib.rs

Шаг 5: Реализовать сервис

# Редактировать microservices/my_service/src/main.rs

Шаг 6: Выбрать порт

Используйте порты из диапазона 13000-14000:

• 13001 - User Service
• 13002-14000 - Ваши сервисы

🔐 Порты и выделение

Компонент	Порт	Протокол	Тип
API Gateway	8000	HTTP/REST	Public
API	8001	HTTP/REST	Internal
User Service	13001	gRPC	Internal
Микросервисы	13000-14000	gRPC	Internal

📦 Зависимости

• axum - Веб-фреймворк (REST)
• tonic - gRPC framework
• tokio - Async runtime
• serde - Сериализация
• utoipa - OpenAPI/Swagger генератор
• prost - Protocol Buffers

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

Проверить REST endpoints

# Health check
curl http://localhost:8000/api/health

# Получить пользователей
curl http://localhost:8000/api/users

# Создать пользователя
curl -X POST http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}'

Проверить gRPC сервисы

# Использовать grpcurl или подобные инструменты
grpcurl -plaintext localhost:13001 list

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

Основные конфигурационные параметры:

• api_gateway адрес: 127.0.0.1:8000
• api адрес: 127.0.0.1:8001
• user_service gRPC: 127.0.0.1:13001
• template_service gRPC: 127.0.0.1:13000 (по умолчанию)

🐛 Отладка

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

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

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

1. Модульность: Каждый микросервис в отдельной папке
2. Proto files: Все определения в shared_proto/proto/
3. Порты: 13000-14000 зарезервированы для микросервисов
4. Логирование: Используйте tracing для логирования
5. Ошибки: Пробрасывайте gRPC Status коды вместо паники