cubenet_backend/QUICKSTART.md

🚀 Quickstart - Cubenet Backend

Структура архитектуры (готовая к использованию!)

REST Client → API Gateway (8000) ──gRPC→ API (8001) ──gRPC→ Microservices (13000+)
                                         ↓
                                   User Service (13001)

🎯 Три простых шага для запуска

Шаг 1: Откройте три терминала

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

cargo run -p user_service

Терминал 2 - API (на порту 8001):

cargo run -p api

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

cargo run -p api_gateway

✨ Доступ к API

📊 Swagger UI (интерактивная документация)

http://localhost:8000/swagger-ui

📋 OpenAPI JSON docs

http://localhost:8000/api-docs

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

Health Check:

curl http://localhost:8000/api/health
# Ответ: {"status":"OK"}

Получить пользователей:

curl http://localhost:8000/api/users
# Ответ: [{"id":1,"name":"Alice",...}, ...]

Создать пользователя:

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

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

Файл	Назначение
README.md	Главная документация
ARCHITECTURE.md	Подробная архитектура системы
MICROSERVICE_GUIDE.md	Создание новых микросервисов
PORT_ALLOCATION.md	Управление портами

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

Быстро (5 минут)

# 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. Добавить в Cargo.toml (workspace members):
# "microservices/my_service"

# 4. Выбрать порт (13002-14000)
# 5. Реализовать логику
# 6. Скомпилировать
cargo check

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

🔐 Порты (выделенные диапазоны)

Компонент	Порт	Статус
API Gateway	8000	✓ REST
API	8001	✓ REST
User Service	13001	✓ gRPC
Микросервисы	13002-14000	✓ Доступны

📦 Что входит в проект

✅ REST API - Axum веб-фреймворк
✅ Swagger UI - Автоматическая документация
✅ gRPC - Inter-service communication (Tonic)
✅ Proto Buffers - Типобезопасные структуры
✅ Microservices - User Service как пример
✅ Template - Шаблон для новых сервисов
✅ Logging - Встроенный Tracing

🐛 Отладка

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

RUST_LOG=debug cargo run -p api_gateway

Проверить что порты свободны (Linux/Mac)

lsof -i :8000
lsof -i :13001

Проверить gRPC endpoints

grpcurl -plaintext localhost:13001 list

⚡ Полезные команды

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

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

# Собрать оптимизированный релиз
cargo build --release

# Запустить тесты
cargo test

# Форматировать код
cargo fmt

# Проверить ошибки линтера
cargo clippy

🎓 Примеры использования

Пример 1: Вызвать gRPC User Service напрямую

# Если установлен grpcurl
grpcurl -plaintext \
  -d '{}' \
  localhost:13001 user.UserService/GetUsers

Пример 2: Создать Product Service

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

# 2. Создать proto файл
cat > shared_proto/proto/product.proto << 'EOF'
syntax = "proto3";
package product;

service ProductService {
  rpc GetProducts(Empty) returns (ProductList);
}

message Empty {}
message Product { int32 id = 1; string name = 2; }
message ProductList { repeated Product products = 1; }
EOF

# 3. Обновить shared_proto/src/lib.rs
# 4. Обновить shared_proto/build.rs
# 5. Реализовать сервис на 13002
# 6. Скомпилировать и запустить

💡 Советы

1. Используйте Swagger UI для тестирования - очень удобно
2. Читайте логи - там видны все подключения и ошибки
3. Proto files - это контракт между сервисами, храните их в shared_proto
4. Порты - не забудьте обновить PORT_ALLOCATION.md при добавлении нового сервиса
5. Логирование - используйте tracing::info!() вместо println!()

❓ Часто задаваемые вопросы

Q: Какие требования для запуска?
A: Rust 1.70+ и Cargo. Всё остальное установится автоматически.

Q: Почему 13000-14000 для микросервисов?
A: Это стандартный диапазон для внутреннего использования, 8000+ зарезервирован для REST.

Q: Как добавить свой микросервис?
A: Читайте MICROSERVICE_GUIDE.md - там всё подробно описано.

Q: Как изменить порты?
A: Отредактируйте src/main.rs в каждом компоненте и обновите PORT_ALLOCATION.md.

📞 Поддержка

Если что-то не работает:

1. Проверьте что все терминалы открыты
2. Посмотрите логи (особенно при RUST_LOG=debug)
3. Убедитесь что порты свободны (lsof -i)
4. Читайте документацию в ARCHITECTURE.md

---

Готово к использованию! 🎉

Откройте Swagger UI в браузере и начните тестировать API:

http://localhost:8000/swagger-ui