quoter/docs/development.md

Разработка

Настройка среды разработки

Требования

• Rust: 1.70 или выше
• Redis: 6.0 или выше (локально или Docker)
• Git: для работы с репозиторием
• IDE: VS Code, IntelliJ IDEA или другой редактор с поддержкой Rust

Установка Rust

# Установка Rust через rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Перезагрузка shell
source ~/.bashrc

# Проверка установки
rustc --version
cargo --version

Клонирование репозитория

git clone https://github.com/your-org/quoter.git
cd quoter

Установка зависимостей

# Сборка проекта
cargo build

# Установка дополнительных инструментов
cargo install cargo-watch  # для автоматической пересборки
cargo install cargo-audit  # для проверки безопасности
cargo install cargo-tarpaulin  # для покрытия кода тестами

Структура проекта

quoter/
├── src/
│   ├── main.rs              # Точка входа приложения
│   ├── app_state.rs         # Состояние приложения и подключения
│   ├── auth.rs              # Аутентификация и авторизация
│   ├── core.rs              # Интеграция с API ядра
│   ├── lookup.rs            # Поиск и определение MIME-типов
│   ├── overlay.rs           # Генерация оверлеев для изображений
│   ├── s3_utils.rs          # Утилиты для работы с S3
│   ├── thumbnail.rs         # Создание миниатюр
│   └── handlers/            # HTTP обработчики
│       ├── mod.rs           # Модуль обработчиков
│       ├── upload.rs        # Загрузка файлов
│       ├── proxy.rs         # Получение файлов
│       ├── quota.rs         # Управление квотами
│       └── serve_file.rs    # Обслуживание файлов
├── docs/                    # Документация
├── tests/                   # Интеграционные тесты
├── Cargo.toml              # Зависимости и конфигурация
├── Cargo.lock              # Фиксированные версии зависимостей
├── Dockerfile              # Docker образ
└── README.md               # Основная документация

Локальная разработка

Настройка переменных окружения

Создайте файл .env в корне проекта:

# Redis (локально или Docker)
REDIS_URL=redis://localhost:6379

# Core API (замените на ваш endpoint)
CORE_URL=https://api.example.com/graphql

# Storj S3 (тестовые ключи)
STORJ_ACCESS_KEY=your-test-key
STORJ_SECRET_KEY=your-test-secret
STORJ_BUCKET_NAME=test-bucket

# AWS S3 (тестовые ключи)
AWS_ACCESS_KEY=your-test-aws-key
AWS_SECRET_KEY=your-test-aws-secret

# Server
PORT=8080
RUST_LOG=debug

Запуск Redis

Локально

# Ubuntu/Debian
sudo apt-get install redis-server
sudo systemctl start redis-server

# macOS
brew install redis
brew services start redis

# Проверка
redis-cli ping

Docker

docker run -d \
  --name redis-dev \
  -p 6379:6379 \
  redis:7-alpine

Запуск приложения

# Обычный запуск
cargo run

# С автоматической пересборкой
cargo watch -x run

# В режиме отладки
RUST_LOG=debug cargo run

# С профилированием
cargo run --release

Проверка работоспособности

# Проверка сервера
curl http://localhost:8080/

# Проверка загрузки файла (требует токен)
curl -X POST http://localhost:8080/ \
  -H "Authorization: Bearer your-token" \
  -F "file=@test-image.jpg"

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

Unit тесты

# Запуск всех тестов
cargo test

# Запуск тестов с выводом
cargo test -- --nocapture

# Запуск конкретного теста
cargo test test_upload_file

# Запуск тестов в параллельном режиме
cargo test -- --test-threads=4

Интеграционные тесты

Создайте файл tests/integration_test.rs:

use actix_web::{test, web, App};
use quoter::app_state::AppState;

#[actix_web::test]
async fn test_upload_endpoint() {
    let app_state = AppState::new().await;
    let app = test::init_service(
        App::new()
            .app_data(web::Data::new(app_state))
            .route("/", web::post().to(upload_handler))
    ).await;

    let req = test::TestRequest::post()
        .uri("/")
        .insert_header(("Authorization", "Bearer test-token"))
        .set_form(("file", "test-data"))
        .to_request();

    let resp = test::call_service(&app, req).await;
    assert!(resp.status().is_success());
}

Тестирование производительности

# Бенчмарки (если настроены)
cargo bench

# Профилирование с flamegraph
cargo install flamegraph
cargo flamegraph --bin quoter

Отладка

Логирование

use log::{debug, info, warn, error};

// В коде
debug!("Processing file: {}", filename);
info!("File uploaded successfully");
warn!("User quota is getting low: {} bytes", quota);
error!("Failed to upload file: {}", e);

Отладка с GDB

# Компиляция с отладочной информацией
cargo build

# Запуск с GDB
gdb target/debug/quoter

# В GDB
(gdb) break main
(gdb) run
(gdb) continue

Отладка с LLDB (macOS)

lldb target/debug/quoter
(lldb) breakpoint set --name main
(lldb) run

Проверка кода

Clippy

# Проверка стиля кода
cargo clippy

# Проверка с дополнительными предупреждениями
cargo clippy -- -D warnings

# Автоматическое исправление
cargo clippy --fix

Форматирование

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

# Проверка форматирования
cargo fmt -- --check

Проверка безопасности

# Аудит зависимостей
cargo audit

# Проверка уязвимостей
cargo audit --deny warnings

Покрытие кода

Tarpaulin

# Установка
cargo install cargo-tarpaulin

# Запуск
cargo tarpaulin

# С HTML отчетом
cargo tarpaulin --out Html

grcov

# Установка
cargo install grcov

# Настройка переменных
export CARGO_INCREMENTAL=0
export RUSTFLAGS="-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests"
export RUSTDOCFLAGS="-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests"

# Запуск тестов
cargo test

# Генерация отчета
grcov . -s . --binary-path ./target/debug/ -t html --branch --ignore-not-existing -o ./coverage/

Git workflow

Создание feature branch

# Создание новой ветки
git checkout -b feature/new-feature

# Внесение изменений
# ...

# Коммит изменений
git add .
git commit -m "feat: add new feature"

# Push в репозиторий
git push origin feature/new-feature

Commit conventions

Используйте Conventional Commits:

• feat: - новая функциональность
• fix: - исправление багов
• docs: - изменения в документации
• style: - форматирование кода
• refactor: - рефакторинг кода
• test: - добавление тестов
• chore: - обновление зависимостей, конфигурации

Pull Request

1. Создайте Pull Request в GitHub/GitLab
2. Добавьте описание изменений
3. Укажите связанные issues
4. Дождитесь code review
5. Исправьте замечания если есть
6. Получите approval и merge

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

Cargo

# Обновление зависимостей
cargo update

# Очистка сборки
cargo clean

# Проверка зависимостей
cargo tree

# Документация
cargo doc --open

# Проверка типов без компиляции
cargo check

Отладка

# Просмотр логов в реальном времени
tail -f logs/quoter.log

# Мониторинг ресурсов
htop
iotop

# Сетевые соединения
netstat -tulpn | grep 8080

Docker

# Сборка для разработки
docker build -t quoter:dev .

# Запуск с volume для hot reload
docker run -v $(pwd):/app -p 8080:8080 quoter:dev

# Просмотр логов контейнера
docker logs -f quoter-container

Рекомендации

Производительность

1. Используйте cargo build --release для production
2. Настройте профилирование для критических участков
3. Мониторьте использование памяти и CPU
4. Оптимизируйте размер изображений

Безопасность

1. Регулярно обновляйте зависимости
2. Используйте cargo audit для проверки уязвимостей
3. Не храните секреты в коде
4. Валидируйте все входные данные

Качество кода

1. Пишите тесты для новой функциональности
2. Используйте cargo clippy для проверки стиля
3. Документируйте публичные API
4. Следуйте принципам SOLID