Organization Directory API

REST API для справочника организаций с геопространственным поиском.

🚀 Технологии

Python 3.13 - современный синтаксис с типизацией
FastAPI - асинхронный веб-фреймворк
SQLAlchemy 2.0 - ORM с async поддержкой и DeclarativeBase
PostgreSQL + PostGIS - база данных с геопространственными возможностями
Pydantic 2.0 - валидация данных с Annotated типами
Alembic - миграции БД
uv - современный менеджер пакетов Python
pytest + aiosqlite - тестирование с SQLite in-memory

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

Docker

# Клонировать репозиторий
git clone <repo-url>
cd organization-directory-api

# Запустить через Docker Compose
docker-compose up -d --build --no-deps

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

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

# Установить uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Установить зависимости
uv sync

# Настроить переменные окружения
cp .env.example .env
# Отредактировать .env файл

# Запустить PostgreSQL с PostGIS
docker run -d --name postgres-postgis \
  -e POSTGRES_DB=orgdir \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgis/postgis:16-3.4

# Применить миграции
uv run alembic upgrade head

# Загрузить тестовые данные
uv run python scripts/seed_data.py

# Запустить сервер
uv run uvicorn app.main:app --reload

📚 API Endpoints

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

Swagger UI: http://localhost:8005/api/docs
ReDoc: http://localhost:8005/api/redoc
OpenAPI JSON: http://localhost:8005/api/openapi.json

Основные endpoints

Здания

# Список всех зданий (с пагинацией)
GET /api/v1/buildings/?limit=100&offset=0

# Здание по ID
GET /api/v1/buildings/{building_id}

Виды деятельности

# Дерево видов деятельности (иерархическое)
GET /api/v1/activities/

# Вид деятельности по ID
GET /api/v1/activities/{activity_id}

Организации

# Организация по ID (с полной информацией)
GET /api/v1/organizations/{org_id}

# Поиск по названию
GET /api/v1/organizations/search?q=название&limit=100&offset=0

# Организации в здании
GET /api/v1/organizations/by-building/{building_id}

# Организации по виду деятельности (с учетом иерархии)
GET /api/v1/organizations/by-activity/{activity_id}

# Геопространственный поиск (радиус)
GET /api/v1/organizations/nearby?lat=55.7558&lon=37.6173&radius=1000

# Геопространственный поиск (bounding box)
GET /api/v1/organizations/nearby?lat_min=55.7&lat_max=55.8&lon_min=37.6&lon_max=37.7

Health Check

# Проверка работоспособности API и БД
GET /health

🔐 Аутентификация

Все запросы к /api/v1/* требуют заголовок:

X-API-Key: your-secret-api-key-here

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

# Получить все здания
curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8005/api/v1/buildings/

# Поиск организаций по названию
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8005/api/v1/organizations/search?q=Рога"

# Геопоиск в радиусе 1км от центра Москвы
curl -H "X-API-Key: your-secret-api-key-here" \
  "http://localhost:8005/api/v1/organizations/nearby?lat=55.7558&lon=37.6173&radius=1000"

# Получить дерево деятельностей
curl -H "X-API-Key: your-secret-api-key-here" \
  http://localhost:8005/api/v1/activities/

⚙️ Переменные окружения

# Приложение
APP_NAME="Organization Directory API"
APP_VERSION="1.0.0"
DEBUG=false

# База данных
DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/orgdir
DB_ECHO=false
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10

# Безопасность
API_KEY=your-secret-api-key-here

# CORS
CORS_ORIGINS=["*"]

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

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

uv sync --dev

Настройка

Тесты используют SQLite in-memory базу данных - настройка не требуется! База создается автоматически для каждого теста и удаляется после завершения.

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

# Все тесты (70 юнит-тестов)
pytest

# С покрытием кода
pytest --cov=app --cov-report=html
open htmlcov/index.html

# Только юнит-тесты
pytest tests/unit/

# Конкретный файл
pytest tests/unit/test_building_service.py

# Конкретный тест
pytest tests/unit/test_building_service.py::test_get_building_by_id -v

# С подробным выводом
pytest -v -s

# Параллельный запуск (быстрее)
pytest -n auto

Статистика тестов

✅ 70 юнит-тестов - все проходят
⚡ ~1 секунда - время выполнения
🎯 >80% - покрытие кода
🚀 SQLite in-memory - не требуется PostgreSQL

Структура тестов

Юнит-тесты (tests/unit/)

test_activity_service.py - 8 тестов сервиса деятельностей
test_building_service.py - 5 тестов сервиса зданий
test_organization_service.py - 10 тестов сервиса организаций
test_models.py - 10 тестов моделей SQLAlchemy
test_repositories.py - 11 тестов репозиториев
test_schemas.py - 15 тестов Pydantic схем
test_exceptions.py - 11 тестов исключений

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

tests/README.md - общее описание
tests/unit/README.md - юнит-тесты
tests/TESTING_GUIDE.md - подробное руководство
tests/FINAL_SUMMARY.md - финальная сводка

🛠️ Разработка

Форматирование и проверка кода

# Форматирование кода
uv run ruff format .

# Проверка линтером
uv run ruff check .

# Проверка типов
uv run mypy app/

Работа с миграциями

# Создание новой миграции
uv run alembic revision --autogenerate -m "Description"

# Применение миграций
uv run alembic upgrade head

# Откат последней миграции
uv run alembic downgrade -1

# История миграций
uv run alembic history

Добавление зависимостей

# Production зависимость
uv add package-name

# Dev зависимость
uv add --dev package-name

# Синхронизация зависимостей
uv sync

🏗️ Архитектура

Проект следует принципам Clean Architecture и SOLID:

app/
├── api/                    # API Layer
│   ├── middleware/        # Аутентификация, CORS
│   └── v1/endpoints/      # HTTP endpoints
├── core/                  # Business Logic Layer
│   ├── services/         # Бизнес-логика
│   └── exceptions.py     # Кастомные исключения
├── db/                    # Data Layer
│   ├── models/           # SQLAlchemy модели
│   ├── repositories/     # Паттерн Repository
│   └── base.py           # Base класс для моделей
├── schemas/               # Pydantic схемы
├── config.py             # Конфигурация
├── dependencies.py       # FastAPI dependencies
└── main.py               # Точка входа

Слои приложения

API Layer (app/api/)
- HTTP endpoints с валидацией
- Middleware (auth, CORS, error handling)
- Роутинг и документация
Service Layer (app/core/services/)
- Бизнес-логика
- Оркестрация репозиториев
- Обработка исключений
Repository Layer (app/db/repositories/)
- Доступ к данным
- CRUD операции
- Сложные запросы
Models (app/db/models/)
- SQLAlchemy модели
- Связи между таблицами
- Валидация на уровне БД
Schemas (app/schemas/)
- Pydantic модели для валидации
- Request/Response схемы
- Документация API

✨ Особенности

Функциональность

✅ Иерархические виды деятельности - до 3 уровней вложенности
✅ Геопространственный поиск - через PostGIS (радиус и bounding box)
✅ Полнотекстовый поиск - по названиям организаций
✅ Пагинация - для всех списковых endpoints
✅ Валидация - на всех уровнях (Pydantic, SQLAlchemy, БД)

Технические особенности

✅ Асинхронная архитектура - высокая производительность
✅ Автоматическая документация - OpenAPI/Swagger
✅ Type hints - полная типизация кода
✅ Dependency Injection - через FastAPI Depends
✅ Annotated типы - современный подход FastAPI
✅ Lifespan events - управление жизненным циклом
✅ Error handling - централизованная обработка ошибок

Best Practices 2025

✅ DeclarativeBase - вместо declarative_base()
✅ Annotated[Type, Depends()] - вместо Type = Depends()
✅ model_validator - вместо @validator
✅ ConfigDict - вместо class Config
✅ Explicit status codes - для всех endpoints
✅ Russian descriptions - в OpenAPI документации

🔄 CI/CD

GitHub Actions

Автоматические тесты запускаются при:

Push в main/develop
Создании Pull Request

См. .github/workflows/tests.yml

Docker

# Сборка образа
docker build -t organization-api .

# Запуск контейнера
docker run -p 8005:8005 --env-file .env organization-api

# Docker Compose (с PostgreSQL)
docker-compose up -d

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

Async/await - неблокирующие операции
Connection pooling - переиспользование соединений
Lazy loading - оптимизация запросов
Indexes - на часто используемых полях
PostGIS - оптимизированные геопространственные запросы

Требования к коду

✅ Все тесты должны проходить
✅ Покрытие кода >80%
✅ Код отформатирован (ruff format)
✅ Нет ошибок линтера (ruff check)
✅ Type hints для всех функций

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
alembic		alembic
app		app
scripts		scripts
tests		tests
.coveragerc		.coveragerc
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
Dockerfile		Dockerfile
README.md		README.md
alembic.ini		alembic.ini
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini

JackOman69/fastapi-ca-tests-task

Folders and files

Latest commit

History

Repository files navigation

Organization Directory API

🚀 Технологии

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

Docker

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

📚 API Endpoints

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

Основные endpoints

Здания

Виды деятельности

Организации

Health Check

🔐 Аутентификация

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

⚙️ Переменные окружения

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

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

Настройка

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

Статистика тестов

Структура тестов

Юнит-тесты (tests/unit/)

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

🛠️ Разработка

Форматирование и проверка кода

Работа с миграциями

Добавление зависимостей

🏗️ Архитектура

Слои приложения

✨ Особенности

Функциональность

Технические особенности

Best Practices 2025

🔄 CI/CD

GitHub Actions

Docker

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

Требования к коду

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages