291 lines
8.8 KiB
Markdown
291 lines
8.8 KiB
Markdown
# 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
|