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):**
```bash
cargo run -p user_service
```

**Терминал 2 - API (gRPC клиент на 8001):**
```bash
cargo run -p api
```

**Терминал 3 - API Gateway (REST + Swagger на 8000):**
```bash
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
```bash
curl http://localhost:8000/api/health
```

Ответ:
```json
{
  "status": "OK"
}
```

### Get All Users
```bash
curl http://localhost:8000/api/users
```

Ответ:
```json
[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com"
  }
]
```

### Create User
```bash
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** - Логирование

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

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

```bash
# 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**

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

### Проверить что всё компилируется
```bash
cargo check
```

### Собрать всё
```bash
cargo build
```

### Запустить отдельный сервис
```bash
cargo run -p api_gateway
cargo run -p api
cargo run -p user_service
```

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

- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Полная архитектура системы
- **[MICROSERVICE_GUIDE.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:**
```rust
let addr = SocketAddr::from(([127, 0, 0, 1], 8000));
```

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

**User Service:**
```rust
let addr = "127.0.0.1:13001".parse()?;
```

## 🐛 Отладка

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

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

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

```bash
# Установить 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