Производительный асинхронный сервис сокращения ссылок (URL Shortener) с современной архитектурой. Проект демонстрирует использование передовых практик разработки на Python: Clean Architecture, Layered Design, Async SQLAlchemy 2.0 и Production-ready Docker Infrastructure.
- Архитектура: Четкое разделение ответственности (Router → Service → Repository → Database).
- High Performance: Полностью асинхронный стек (FastAPI + Psycopg 3).
- Атомарность: Инкремент счетчика переходов (
click_count) выполнен через атомарный SQL-запрос для защиты от Race Conditions. - Фоновые задачи: Обновление статистики вынесено в
BackgroundTasks, чтобы не блокировать редирект пользователя. - Алгоритм: Генерация коротких ссылок с использованием
secrets(криптостойкий рандом) и стратегией Retry при коллизиях. - Инфраструктура:
- Docker Multi-stage build: Оптимизированный образ с использованием
su-execдля безопасности (запуск от non-root пользователя). - Makefile: Единая точка входа для управления проектом.
- Loguru: Централизованная система логирования с перехватом стандартных логов (Uvicorn, Alembic).
- SSOT: Вся конфигурация (Linter, Tests, Alembic) собрана в
pyproject.toml.
- Docker Multi-stage build: Оптимизированный образ с использованием
| Категория | Технологии |
|---|---|
| Core | Python 3.12, FastAPI, Pydantic V2 |
| Database | PostgreSQL, SQLAlchemy 2.0 (Async), Alembic |
| Driver | Psycopg 3 (Binary) |
| DevOps | Docker, Docker Compose, Makefile |
| Quality | Ruff (Linter/Formatter), Mypy (Static Typing) |
| Logging | Loguru |
| Package Mgr | Poetry |
.
├── docker/ # Dockerfiles и скрипт инициализации (entrypoint)
├── migrations/ # Миграции базы данных (Alembic)
├── src/
│ ├── api/
│ │ ├── core/ # Конфигурация, БД, исключения
│ │ ├── models/ # SQLAlchemy модели
│ │ ├── repositories/ # Слой доступа к данным (CRUD)
│ │ ├── routes/ # API эндпоинты
│ │ ├── schemas/ # Pydantic схемы
│ │ ├── services/ # Бизнес-логика
│ │ ├── utils/ # Утилиты (генерация кодов, форматирование URL)
│ │ └── main.py # Точка входа приложения
│ └── core_shared/ # Общие модули (настройка логгера)
├── Makefile # Команды для управления проектом
├── docker-compose.yml # Оркестрация контейнеров
├── docker-compose.test.yml # Изолированный контейнер БД для тестов
├── poetry.lock # Фиксация версий зависимостей
└── pyproject.toml # Единый конфиг проекта
Для запуска вам понадобятся Docker и Docker Compose. Make (рекомендуется).
Клонируйте репозиторий:
git clone https://git@github.com:Nicksok2413/URL_shortener.git
cd URL_shortenerСкопируйте .env.example в .env:
cp .env.example .env
# **Важно:** Используйте надежный пароль `DB_PASSWORD`.
# При необходимости отредактируйте другие переменные в .envИспользуйте make для быстрого старта. Команда поднимет БД, приложение и применит миграции.
make upИли классическим способом:
docker compose up -d --build
docker compose run --rm api-migrate
Если таблицы не создались автоматически или вы добавили новые модели:
make migrateИли классическим способом: docker compose run --rm api-migrate
- После запуска API будет доступно по адресу: http://localhost:8000
- Документация Swagger UI доступна по адресу: http://localhost:8000/docs
Управление проектом через Makefile для удобства разработки:
make install— Установить все зависимости.
make up— Собрать и запустить контейнеры в фоне.make down— Остановить контейнеры.make rebuild— Пересобрать контейнеры.make prune— Остановить контейнеры и УДАЛИТЬ ВСЕ ДАННЫЕ (БД, логи).make logs— Просмотр логов всех сервисов в реальном времени.
make migrate— Применить миграции к БД.make revision m="message"— Создать новую миграцию (автогенерация).
make lint— Проверить код линтером Ruff.make lint-fix— Исправить код линтером Ruff.make format-check— Проверить код форматтером Ruff.make format— Отформатировать код форматтером Ruff.make types— Проверить статическую типизацию mypy.make check— Запустить статический анализ (lint, format-check, types).
Developed by Mikalai Sakalouski with ❤️ and Python.