218 lines
6.9 KiB
Markdown
218 lines
6.9 KiB
Markdown
# Архитектура 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):**
|
||
```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 Documentation
|
||
|
||
После запуска API Gateway, откройте браузер:
|
||
```
|
||
http://localhost:8000/swagger-ui/
|
||
```
|
||
|
||
Здесь вы сможете:
|
||
- Просмотреть все доступные endpoints
|
||
- Тестировать API requests
|
||
- Изучать схему данных
|
||
|
||
## 🔧 Создание нового микросервиса
|
||
|
||
### Шаг 1: Скопировать шаблон
|
||
```bash
|
||
cp -r microservices/template_service microservices/my_service
|
||
```
|
||
|
||
### Шаг 2: Обновить Cargo.toml
|
||
```toml
|
||
[package]
|
||
name = "my_service"
|
||
```
|
||
|
||
### Шаг 3: Добавить в workspace (корневой Cargo.toml)
|
||
```toml
|
||
[workspace]
|
||
members = ["api_gateway", "api", "microservices/user_service", "microservices/my_service"]
|
||
```
|
||
|
||
### Шаг 4: Определить proto файл
|
||
```bash
|
||
# Добавить my_service.proto в shared_proto/proto/
|
||
# Обновить shared_proto/src/lib.rs
|
||
```
|
||
|
||
### Шаг 5: Реализовать сервис
|
||
```bash
|
||
# Редактировать 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
|
||
```bash
|
||
# 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 сервисы
|
||
```bash
|
||
# Использовать 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` (по умолчанию)
|
||
|
||
## 🐛 Отладка
|
||
|
||
Включить подробное логирование:
|
||
```bash
|
||
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 коды вместо паники
|