🔗 URL-Shortener

Высокопроизводительный сервис для сокращения ссылок на FastAPI с современным веб-интерфейсом

✨ О проекте

URL-Shortener — это полностью контейнеризированный сервис для создания коротких ссылок, написанный на современном стеке технологий. Проект создан с упором на производительность, масштабируемость и удобство использования.

Основные возможности:

• 🚀 Мгновенные редиректы благодаря кэшированию в Redis.
• 📊 Детальная статистика по каждой ссылке (количество переходов, дата создания).
• 🎨 Современный веб-интерфейс с анимированным фоном, поддержкой темной темы и адаптивным дизайном.
• ⚙️ Гибкие настройки — возможность задать свой вариант ссылки (custom slug) или выбрать её длину.
• 🐳 Docker-first подход — весь стек поднимается одной командой.

🛠 Стек технологий

Компонент	Технология
Язык (Backend)	Python 3.12.10
Веб-фреймворк (Backend)	FastAPI 0.124.0
ORM	SQLAlchemy 2.0.44
База данных	PostgreSQL 14
Кэш	Redis 7.1.0
Фронтенд	HTML5, CSS3, JavaScript (Vanilla)
Контейнеризация	Docker + Docker Compose
Тестирование	Pytest

🚀 Быстрый старт

Предварительные требования

• Установленные Docker и Docker Compose

Установка и запуск

1. Клонируйте репозиторий

   git clone https://github.com/kite-house/URL-Shortener.git
   cd URL-Shortener
   

2. Настройте переменные окружения Скопируйте файл с примером конфигурации и отредактируйте его под себя:

   cp .env.example .env

   Минимально необходимые настройки:

   # ==================================================
   # ⚙️ REQUIRED ENVIRONMENT VARIABLES
   # ==================================================
   
   # 🚀 Application Mode
   MODE="DEV"  # DEV, TEST, or PROD
   BACKEND_PORT = "8000"
   BACKEND_HOST = "0.0.0.0"
   FRONTED_PORT = "80"
   
   
   # ==================================================
   # 🗄️ Database (PostgreSQL)
   # ==================================================
   DB_USER = "postgres"
   DB_PASS = "postgres"
   DB_HOST = "backend_db"
   DB_PORT = "5432"
   DB_NAME = "postgres_db"
   
   # ==================================================
   # ⚡ Redis (Cache)
   # ==================================================
   REDIS_HOST = "cache"
   REDIS_PORT = "6379" 

3. Запустите все сервисы

   docker compose up -d --build

4. Проверьте работу
   • Веб-интерфейс: http://localhost:8000
   • Документация API (Swagger): http://localhost:8000/docs

📖 Использование

🌐 Веб-интерфейс

Главная страница сервиса предлагает интуитивно понятный интерфейс для работы со ссылками.

Функция	Описание
Сокращение ссылки	Вставьте длинную ссылку в поле ввода и нажмите кнопку "Сократить"
Свой вариант ссылки	Введите желаемую часть короткой ссылки (например, my-link)
Длина ссылки	Выберите длину генерируемой ссылки с помощью слайдера (от 3 до 10 символов)
Копирование	Скопируйте полученную короткую ссылку одним кликом
Темная тема	Переключайтесь между светлой и темной темой интерфейса

🔗 Создание короткой ссылки через API

Эндпоинт: POST /api/shorten

Параметры запроса:

url (обязательный) — исходный длинный URL

custom_slug (опционально) — желаемая кастомная часть

length (опционально) — желаемая длина генерируемой части

Примеры запросов (cURL):

# Без дополнительных параметров
curl -X POST "http://localhost:8000/api/shorten" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/very/long/url"}'

# С кастомным slug
curl -X POST "http://localhost:8000/api/shorten?custom_slug=my-page" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/very/long/url"}'

# С указанием длины
curl -X POST "http://localhost:8000/api/shorten?length=5" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/very/long/url"}'

Пример ответа:

{
  "status_code": 200,
  "cached": true,
  "message": "Ссылка успешно создана!",
  "content": {
    "slug": "my-page",
    "short_url": "http://localhost:8000/api/my-page",
    "long_url": "https://example.com/very/long/url"
  }
}

🚦 Переход по короткой ссылке

Просто откройте в браузере: http://localhost:8000/api/ваш_slug

Вы будете автоматически перенаправлены на исходный URL.

📊 Получение статистики

Эндпоинт: GET /api/info/{slug}

curl http://localhost:8000/api/info/my-page

Пример ответа:

{
  "status_code": 200,
  "content": {
    "success": true,
    "message": "Успешно найден!",
    "data": {
      "slug": "my-page",
      "short_url": "http://localhost:8000/api/my-page",
      "long_url": "https://example.com",
      "count_clicks": 13,
      "date_created": "10.03.2026"
    }
  }
}

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

Запуск тестов внутри Docker-контейнера:

```bash
docker compose exec backend pytest -v
```

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

URL-Shortener/
├── .env.example                    # Пример конфигурации
├── docker-compose.yml              # Оркестрация всех сервисов
├── README.md                       # Документация
├── backend/                        # FastAPI приложение
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── pytest.ini                  # Конфигурация pytest
│   └── src/                        # Исходный код бэкенда
│       ├── api/                     # Эндпоинты API
│       │   ├── configuration.py
│       │   ├── dependencies.py
│       │   └── shortener.py
│       ├── core/                    # Ядро приложения
│       │   ├── config.py
│       │   ├── exceptions.py
│       │   └── redis.py
│       ├── db/                       # Работа с базой данных
│       │   ├── crud.py
│       │   ├── db.py
│       │   └── models.py
│       ├── schemas/                   # Pydantic схемы
│       ├── tests/                      # Тесты
│       │   ├── __init__.py
│       │   ├── test_data.py
│       │   ├── fixtures/                # Фикстуры для тестов
│       │   │   ├── client_fixtures.py
│       │   │   ├── db_fixtures.py
│       │   │   └── redis_fixtures.py
│       │   ├── integration/              # Интеграционные тесты
│       │   │   └── test_api.py
│       │   └── unit/                      # Модульные тесты
│       │       └── test_slug_generator.py
│       └── utils/                         # Вспомогательные модули
│           ├── helpers.py
│           └── conflict.py
└── frontend/                               # Статические файлы веб-интерфейса
    ├── assets/                              # Ресурсы (изображения, шрифты)
    ├── css/
    │   └── style.css                        # Стили с анимациями и темами
    ├── js/
    │   ├── api.js                           # Модуль для работы с API
    │   └── ui.js                            # Модуль для управления интерфейсом
    ├── Dockerfile
    └── index.html                           # Главная страница

🎨 Особенности интерфейса

• Анимированный градиентный фон с плавающими сферами

• Плавные анимации при наведении и взаимодействии

• Адаптивный дизайн для мобильных устройств

• Валидация форм в реальном времени с подсказками

• Уведомления (toast-сообщения) об успехе или ошибке

• Горячие клавиши — закрытие результата по Escape

🤝 Вклад в проект

Будем рады вашим идеям и улучшениям! Чтобы внести вклад:

1. Форкните репозиторий

2. Создайте ветку для фичи (git checkout -b feature/amazing-feature)

3. Закоммитьте изменения (git commit -m '✨ Add some amazing feature')

4. Запушьте ветку (git push origin feature/amazing-feature)

5. Откройте Pull Request

📄 Лицензия

Проект распространяется под лицензией MIT. Подробности в файле LICENSE.

📬 Контакты

Автор: kite-house

GitHub: @kite-house

⭐ Если проект оказался полезным, не забудьте поставить звезду!

_{Сделано с ❤️ для сообщества}