API Сервиса Вакансий

Backend на Yii2 для управления вакансиями с REST API

О проекте

Backend-сервис для хранения и управления вакансиями, реализованный на фреймворке Yii2 с REST API интерфейсом.

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

• ✅ Полнотекстовый поиск с FULLTEXT индексами (10-100x быстрее) 🔍
• ✅ Кеширование для повышения производительности (5-10 минут TTL)
• ✅ Получение списка вакансий с пагинацией (10 записей на страницу)
• ✅ Сортировка по зарплате, дате создания и релевантности
• ✅ Получение конкретной вакансии с выборочным отображением полей
• ✅ CRUD операции (создание, обновление, удаление)
• ✅ Rate Limiting (100 запросов в час на IP)
• ✅ HTTPS поддержка (Nginx/Apache + Let's Encrypt)
• ✅ Swagger/OpenAPI документация
• ✅ CI/CD (GitHub Actions + GitLab CI)
• ✅ Поддержка дополнительных полей в формате JSON
• ✅ CORS для интеграции с frontend
• ✅ Многослойная архитектура (Controllers → Services → Repositories)
• ✅ Полное покрытие тестами (unit, functional, API)

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

🐳 Вариант 1: Docker (рекомендуется)

./docker-setup.sh

API будет доступен по адресу: http://localhost:8000/vacancy phpMyAdmin: http://localhost:8080

📘 Подробнее: DOCKER.md

💻 Вариант 2: Локальная установка

# 1. Установка зависимостей
composer install

# 2. Настройка базы данных
./setup_db.sh

# 3. Добавление тестовых данных (опционально)
php seed_data.php

# 4. Запуск встроенного сервера
php yii serve --docroot=web --port=8080

API будет доступен по адресу: http://localhost:8080

📖 Подробная инструкция: QUICKSTART.md

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

• 🏗️ Архитектура - Многослойная архитектура (Controllers/Services/Repositories)
• 🐳 Docker Setup - Запуск в Docker (MySQL/PostgreSQL + phpMyAdmin/pgAdmin)
• 📘 Быстрый старт - Запуск за 5 минут
• 📗 API документация - Подробное описание всех endpoints
• 🔍 Полнотекстовый поиск - Руководство по поиску
• ⚙️ Руководство по настройке - HTTPS, CI/CD, Swagger
• 🔐 HTTPS Setup - Настройка SSL/TLS
• 📙 Информация о проекте - Детали реализации
• 🌐 Swagger UI - Интерактивная документация

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

🔍 Полнотекстовый поиск

# Поиск по ключевым словам
curl "http://localhost:8080/vacancy/search?q=PHP разработчик"

# Поиск с пагинацией и сортировкой
curl "http://localhost:8080/vacancy/search?q=developer&page=2&sort=relevance"

Получение списка вакансий

curl "http://localhost:8080/vacancy?sort=salary&order=desc"

Создание вакансии

curl -X POST http://localhost:8080/vacancy \
  -H "Content-Type: application/json" \
  -d '{
    "title": "PHP Developer",
    "description": "Требуется опытный PHP разработчик",
    "salary": 150000
  }'

Получение конкретной вакансии с выбранными полями

curl "http://localhost:8080/vacancy/1?fields=title,salary"

Обновление и удаление

# Обновление
curl -X PUT http://localhost:8080/vacancy/1 \
  -H "Content-Type: application/json" \
  -d '{"salary": 180000}'

# Удаление
curl -X DELETE http://localhost:8080/vacancy/1

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

Запустите автоматические тесты:

# Все тесты (unit, functional, API)
vendor/bin/codecept run

# Только API тесты
vendor/bin/codecept run api

# Тесты полнотекстового поиска
vendor/bin/codecept run api SearchCest

# Тесты rate limiting
vendor/bin/codecept run api RateLimitingCest

# Скрипт быстрого тестирования API
./test_api.sh http://localhost:8080

Технологии

• Framework: Yii2 (2.0.53)
• PHP: 8.0+
• Database: MySQL 5.7+ / PostgreSQL 9.5+
• API: REST JSON

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

vakansii-back/
├── assets/             # Определения ресурсов
├── commands/           # Консольные команды (контроллеры)
├── config/             # Конфигурация приложения
├── controllers/        # Web-контроллеры
├── mail/               # Шаблоны email-сообщений
├── models/             # Модели данных
├── repositories/       # Репозитории для работы с БД
├── services/           # Бизнес-логика
├── migrations/         # Миграции базы данных
├── runtime/            # Временные файлы и логи
├── tests/              # Тесты (unit, functional, API)
├── vendor/             # Зависимости Composer
├── views/              # Представления для Web
└── web/                # Публичная директория (index.php, assets)

Требования

Минимальные требования для запуска проекта:

• PHP: 8.0 или выше
• База данных: MySQL 5.7+ или PostgreSQL 9.5+
• Composer: для управления зависимостями
• Веб-сервер: Apache/Nginx с mod_rewrite

Установка

Вариант 1: Установка через Composer

Если у вас не установлен Composer, следуйте инструкциям по установке на getcomposer.org.

Установка базового шаблона Yii2:

composer create-project --prefer-dist yiisoft/yii2-app-basic vakansii-back

После установки приложение будет доступно по адресу:

http://localhost/vakansii-back/web/

Вариант 2: Установка из архива

1. Скачайте архив с yiiframework.com
2. Распакуйте в директорию vakansii-back под корнем веб-сервера

Установите ключ валидации cookies в файле config/web.php:

'request' => [
    // !!! вставьте секретный ключ здесь - это требуется для валидации cookies
    'cookieValidationKey' => '<ваш случайный секретный ключ>',
],

Приложение будет доступно по адресу:

http://localhost/vakansii-back/web/

Вариант 3: Установка через Docker

Обновите зависимости:

docker-compose run --rm php composer update --prefer-dist

Запустите установку (создание ключа валидации cookies):

docker-compose run --rm php composer install

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

docker-compose up -d

Приложение будет доступно по адресу:

http://127.0.0.1:8000

Примечания:

• Минимальная версия Docker engine: 17.04 для разработки (см. Performance tuning for volume mounts)
• По умолчанию используется host-volume в домашней директории .docker-composer для кеша composer

Конфигурация

Настройка базы данных

Отредактируйте файл config/db.php с реальными данными подключения:

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=localhost;dbname=vakansii_db',
    'username' => 'root',
    'password' => 'ваш_пароль',
    'charset' => 'utf8mb4',
];

Важно:

• Yii не создаст базу данных автоматически - вы должны создать её вручную перед запуском
• Проверьте и отредактируйте другие файлы в директории config/ для настройки приложения
• Для получения информации о тестах обратитесь к README в директории tests

Расширенное тестирование

Тесты расположены в директории tests. Они разработаны с использованием Codeception PHP Testing Framework.

По умолчанию доступны 3 типа тестов:

• unit - модульные тесты компонентов системы
• functional - функциональные тесты взаимодействия пользователя
• acceptance - приемочные тесты (отключены по умолчанию)

Запуск тестов:

vendor/bin/codecept run

Эта команда выполнит unit и functional тесты. Acceptance тесты отключены по умолчанию, так как требуют дополнительной настройки (тестирование в реальном браузере).

Запуск acceptance тестов

Для выполнения acceptance тестов:

1. Переименуйте tests/acceptance.suite.yml.example в tests/acceptance.suite.yml

2. Замените пакет codeception/base в composer.json на codeception/codeception для установки полнофункциональной версии

3. Обновите зависимости:

   composer update

4. Скачайте и запустите Selenium Server:

   java -jar ~/selenium-server-standalone-x.xx.x.jar

   Для Selenium Server 3.0 с Firefox v48+ или Chrome v53+ необходимо скачать GeckoDriver или ChromeDriver:

   # Для Firefox
   java -jar -Dwebdriver.gecko.driver=~/geckodriver ~/selenium-server-standalone-3.xx.x.jar
   
   # Для Google Chrome
   java -jar -Dwebdriver.chrome.driver=~/chromedriver ~/selenium-server-standalone-3.xx.x.jar

   Альтернатива - использовать готовый Docker контейнер:

   docker run --net=host selenium/standalone-firefox:2.53.0

5. (Опционально) Создайте тестовую БД vakansii_test и примените миграции:

   tests/bin/yii migrate

   Конфигурация БД находится в config/test_db.php.

6. Запустите веб-сервер:

   tests/bin/yii serve

7. Запустите тесты:

   # Все доступные тесты
   vendor/bin/codecept run
   
   # Только acceptance тесты
   vendor/bin/codecept run acceptance
   
   # Только unit и functional тесты
   vendor/bin/codecept run unit,functional

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

По умолчанию покрытие кода отключено в codeception.yml. Раскомментируйте нужные строки для сбора статистики покрытия:

# Покрытие для всех тестов
vendor/bin/codecept run --coverage --coverage-html --coverage-xml

# Покрытие только для unit тестов
vendor/bin/codecept run unit --coverage --coverage-html --coverage-xml

# Покрытие для unit и functional тестов
vendor/bin/codecept run functional,unit --coverage --coverage-html --coverage-xml

Результаты покрытия сохраняются в директорию tests/_output.

Лицензия

MIT