Микросервис для управления связками "телефон-адрес"

Микросервис для хранения и управления связками "телефон-адрес" с использованием FastAPI и Redis.

Описание

Этот сервис предоставляет REST API для работы с данными о телефонах и адресах, используя Redis в качестве быстрого хранилища данных. Сервис может использоваться для кеширования часто запрашиваемой информации о клиентах.

Особенности

• Автоматическое форматирование телефонов: Номера телефонов автоматически приводятся к единому формату +7 (999) 999 99-99
• Структурированные адреса: Адреса хранятся в структурированном виде с полями: страна, город, улица, дом, корпус, квартира
• Гибкий ввод: Номера телефонов можно передавать в любом формате (например: +79991234567, 89991234567, +7 999 123 45 67)

Технологический стек

• FastAPI - современный веб-фреймворк для создания API
• Redis - быстрое хранилище данных в памяти
• Python 3.13 - язык программирования
• Docker - контейнеризация приложения

Запуск

1. Убедитесь, что у вас установлены Docker, Docker Compose и Make

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

make run

3. Сервис будет доступен по адресу: http://localhost:8000

4. Документация API (Swagger UI): http://localhost:8000/docs

5. Альтернативная документация (ReDoc): http://localhost:8000/redoc

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

Через .env, но локально можно запустить и без него, есть значения по умолчанию

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

.
├── app/                 # Основной пакет приложения
│   ├── __init__.py     # Инициализация пакета
│   ├── config.py       # Конфигурация приложения (настройки Redis)
│   ├── dependencies.py # Dependency injection функции
│   ├── models.py       # Pydantic модели для валидации данных
│   ├── utils.py        # Утилиты (форматирование телефонов)
│   ├── clients/        # Клиенты для внешних сервисов
│   │   ├── __init__.py
│   │   └── redis.py    # Redis клиент
│   └── api/            # API модули с версионированием
│       ├── __init__.py
│       ├── __main__.py # Точка входа для запуска API
│       ├── app.py      # Создание и настройка FastAPI приложения
│       └── v1/         # API версия 1
│           ├── __init__.py
│           └── views/  # Роутеры для API v1
│               ├── __init__.py
│               └── phone_address.py
├── pyproject.toml      # Зависимости проекта
├── Dockerfile          # Образ для контейнеризации приложения
├── docker-compose.yml  # Конфигурация для запуска всех сервисов
├── .dockerignore       # Исключения для Docker
└── README.md           # Документация

API Эндпоинты

1. Получить адрес по номеру телефона

GET /api/v1/phone/{phone}

Получает сохранённый адрес по номеру телефона.

Ответы:

• 200 OK - адрес найден
• 404 Not Found - телефон не найден

Пример запроса:

curl http://localhost:8000/api/v1/phone/+79991234567

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

{
  "phone": "+7 (999) 123 45-67",
  "address": {
    "country": "Россия",
    "city": "Москва",
    "street_name": "ул. Ленина",
    "house": "1",
    "building": "2",
    "apartment": "10"
  }
}

Примечание: Номер телефона можно передавать в любом формате (например: +79991234567, 89991234567, 79991234567, +7 999 123 45 67). Он будет автоматически отформатирован в единый формат +7 (999) 999 99-99.

2. Создать новую связку телефон-адрес

POST /api/v1/phone

Регистрирует новую связку телефон-адрес в системе.

Тело запроса:

{
  "phone": "+79991234567",
  "address": {
    "country": "Россия",
    "city": "Москва",
    "street_name": "ул. Ленина",
    "house": "1",
    "building": "2",
    "apartment": "10"
  }
}

Примечание: Поля building и apartment являются опциональными.

Ответы:

• 201 Created - связка успешно создана
• 409 Conflict - телефон уже существует

Пример запроса:

curl -X POST http://localhost:8000/api/v1/phone \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+79991234567",
    "address": {
      "country": "Россия",
      "city": "Москва",
      "street_name": "ул. Ленина",
      "house": "1",
      "building": "2",
      "apartment": "10"
    }
  }'

3. Обновить адрес для номера телефона

PUT /api/v1/phone/{phone}

Актуализирует адрес клиента.

Тело запроса:

{
  "address": {
    "country": "Россия",
    "city": "Санкт-Петербург",
    "street_name": "Невский проспект",
    "house": "28",
    "building": null,
    "apartment": null
  }
}

Ответы:

• 200 OK - адрес успешно обновлён
• 404 Not Found - телефон не найден

Пример запроса:

curl -X PUT http://localhost:8000/api/v1/phone/+79991234567 \
  -H "Content-Type: application/json" \
  -d '{
    "address": {
      "country": "Россия",
      "city": "Санкт-Петербург",
      "street_name": "Невский проспект",
      "house": "28"
    }
  }'

4. Удалить связку телефон-адрес

DELETE /api/v1/phone/{phone}

Удаляет устаревшие или ошибочные данные из системы.

Ответы:

• 204 No Content - запись успешно удалена
• 404 Not Found - телефон не найден

Пример запроса:

curl -X DELETE http://localhost:8000/api/v1/phone/+79991234567