422 lines
10 KiB
Markdown
422 lines
10 KiB
Markdown
# Разработка
|
||
|
||
## Настройка среды разработки
|
||
|
||
### Требования
|
||
|
||
- **Rust**: 1.70 или выше
|
||
- **Redis**: 6.0 или выше (локально или Docker)
|
||
- **Git**: для работы с репозиторием
|
||
- **IDE**: VS Code, IntelliJ IDEA или другой редактор с поддержкой Rust
|
||
|
||
### Установка Rust
|
||
|
||
```bash
|
||
# Установка Rust через rustup
|
||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||
|
||
# Перезагрузка shell
|
||
source ~/.bashrc
|
||
|
||
# Проверка установки
|
||
rustc --version
|
||
cargo --version
|
||
```
|
||
|
||
### Клонирование репозитория
|
||
|
||
```bash
|
||
git clone https://github.com/your-org/quoter.git
|
||
cd quoter
|
||
```
|
||
|
||
### Установка зависимостей
|
||
|
||
```bash
|
||
# Сборка проекта
|
||
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` в корне проекта:
|
||
|
||
```bash
|
||
# 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
|
||
|
||
#### Локально
|
||
```bash
|
||
# 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
|
||
```bash
|
||
docker run -d \
|
||
--name redis-dev \
|
||
-p 6379:6379 \
|
||
redis:7-alpine
|
||
```
|
||
|
||
### Запуск приложения
|
||
|
||
```bash
|
||
# Обычный запуск
|
||
cargo run
|
||
|
||
# С автоматической пересборкой
|
||
cargo watch -x run
|
||
|
||
# В режиме отладки
|
||
RUST_LOG=debug cargo run
|
||
|
||
# С профилированием
|
||
cargo run --release
|
||
```
|
||
|
||
### Проверка работоспособности
|
||
|
||
```bash
|
||
# Проверка сервера
|
||
curl http://localhost:8080/
|
||
|
||
# Проверка загрузки файла (требует токен)
|
||
curl -X POST http://localhost:8080/ \
|
||
-H "Authorization: Bearer your-token" \
|
||
-F "file=@test-image.jpg"
|
||
```
|
||
|
||
## Тестирование
|
||
|
||
### Unit тесты
|
||
|
||
```bash
|
||
# Запуск всех тестов
|
||
cargo test
|
||
|
||
# Запуск тестов с выводом
|
||
cargo test -- --nocapture
|
||
|
||
# Запуск конкретного теста
|
||
cargo test test_upload_file
|
||
|
||
# Запуск тестов в параллельном режиме
|
||
cargo test -- --test-threads=4
|
||
```
|
||
|
||
### Интеграционные тесты
|
||
|
||
Создайте файл `tests/integration_test.rs`:
|
||
|
||
```rust
|
||
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());
|
||
}
|
||
```
|
||
|
||
### Тестирование производительности
|
||
|
||
```bash
|
||
# Бенчмарки (если настроены)
|
||
cargo bench
|
||
|
||
# Профилирование с flamegraph
|
||
cargo install flamegraph
|
||
cargo flamegraph --bin quoter
|
||
```
|
||
|
||
## Отладка
|
||
|
||
### Логирование
|
||
|
||
```rust
|
||
use log::{debug, info, warn, error};
|
||
|
||
// В коде
|
||
debug!("Processing file: {}", filename);
|
||
info!("File uploaded successfully");
|
||
warn!("Author quota is getting low: {} bytes", quota);
|
||
error!("Failed to upload file: {}", e);
|
||
```
|
||
|
||
### Отладка с GDB
|
||
|
||
```bash
|
||
# Компиляция с отладочной информацией
|
||
cargo build
|
||
|
||
# Запуск с GDB
|
||
gdb target/debug/quoter
|
||
|
||
# В GDB
|
||
(gdb) break main
|
||
(gdb) run
|
||
(gdb) continue
|
||
```
|
||
|
||
### Отладка с LLDB (macOS)
|
||
|
||
```bash
|
||
lldb target/debug/quoter
|
||
(lldb) breakpoint set --name main
|
||
(lldb) run
|
||
```
|
||
|
||
## Проверка кода
|
||
|
||
### Clippy
|
||
|
||
```bash
|
||
# Проверка стиля кода
|
||
cargo clippy
|
||
|
||
# Проверка с дополнительными предупреждениями
|
||
cargo clippy -- -D warnings
|
||
|
||
# Автоматическое исправление
|
||
cargo clippy --fix
|
||
```
|
||
|
||
### Форматирование
|
||
|
||
```bash
|
||
# Форматирование кода
|
||
cargo fmt
|
||
|
||
# Проверка форматирования
|
||
cargo fmt -- --check
|
||
```
|
||
|
||
### Проверка безопасности
|
||
|
||
```bash
|
||
# Аудит зависимостей
|
||
cargo audit
|
||
|
||
# Проверка уязвимостей
|
||
cargo audit --deny warnings
|
||
```
|
||
|
||
## Покрытие кода
|
||
|
||
### Tarpaulin
|
||
|
||
```bash
|
||
# Установка
|
||
cargo install cargo-tarpaulin
|
||
|
||
# Запуск
|
||
cargo tarpaulin
|
||
|
||
# С HTML отчетом
|
||
cargo tarpaulin --out Html
|
||
```
|
||
|
||
### grcov
|
||
|
||
```bash
|
||
# Установка
|
||
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
|
||
|
||
```bash
|
||
# Создание новой ветки
|
||
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](https://www.conventionalcommits.org/):
|
||
|
||
- `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
|
||
|
||
```bash
|
||
# Обновление зависимостей
|
||
cargo update
|
||
|
||
# Очистка сборки
|
||
cargo clean
|
||
|
||
# Проверка зависимостей
|
||
cargo tree
|
||
|
||
# Документация
|
||
cargo doc --open
|
||
|
||
# Проверка типов без компиляции
|
||
cargo check
|
||
```
|
||
|
||
### Отладка
|
||
|
||
```bash
|
||
# Просмотр логов в реальном времени
|
||
tail -f logs/quoter.log
|
||
|
||
# Мониторинг ресурсов
|
||
htop
|
||
iotop
|
||
|
||
# Сетевые соединения
|
||
netstat -tulpn | grep 8080
|
||
```
|
||
|
||
### Docker
|
||
|
||
```bash
|
||
# Сборка для разработки
|
||
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 |