Сервис построения маршрутов

Сервис для расчета и оптимизации маршрутов с использованием современных технологий и внешних API маршрутизации.

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

Backend

• Go 1.21 - основной язык разработки
• Gin - веб-фреймворк для API
• PostgreSQL + PostGIS - основная база данных для геоданных
• Redis - кэширование популярных маршрутов
• Docker - контейнеризация

Frontend

• React + TypeScript - пользовательский интерфейс
• Яндекс.Карты 3.0 - отображение карт и построение маршрутов
• Axios - HTTP клиент
• React Router - маршрутизация
• React Hook Form - формы
• Tailwind CSS - стилизация

Геопространственные библиотеки

• paulmach/orb - основные геооперации и GeoJSON
• paulmach/go.geo - вычисления расстояний и проекции
• PostGIS - сложные геозапросы в БД

Внешние API для маршрутизации

Рекомендуемые для MVP

• OSRM (Open Source Routing Machine):

  • Быстрый, открытый движок маршрутизации на основе данных OpenStreetMap
  • Поддерживает автомобильные, пешеходные и велосипедные маршруты
  • Может работать локально или через облачные сервисы
  • Бесплатный и подходит для начального этапа

• Valhalla:

  • Открытый мульти-модальный маршрутизатор
  • Расширенные функции (пешеход, авто, вело, общественный транспорт)
  • Гибко настраивается, поддерживает сложные ограничения
  • Бесплатный и более подходящий для комплексных задач

Коммерческие решения

• Google Maps Directions API:

  • Коммерческий сервис с широкими возможностями
  • Актуальные данные и поддержка множества транспортных режимов
  • Требует оплаты, но обеспечивает высокое качество

• Mapbox Directions API:

  • Основан на данных OpenStreetMap
  • Поддерживает все основные типы транспорта
  • Подходит для интеграции с визуализацией на картах Mapbox

Архитектура проекта

coords/
├── cmd/server/          # Точка входа приложения
├── internal/            # Внутренние пакеты
│   ├── handlers/        # HTTP обработчики
│   ├── services/        # Бизнес-логика
│   ├── repository/      # Слой данных
│   ├── models/          # Модели данных
│   └── config/          # Конфигурация
├── pkg/                 # Публичные пакеты
│   ├── types/           # Общие типы
│   └── client/          # HTTP клиенты
├── migrations/          # Миграции БД
├── frontend/            # React приложение
└── docker-compose.yml   # Docker окружение

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

API эндпоинты

• POST /api/routes/calculate - расчет маршрута между точками
• GET /api/routes/:id - получение сохраненного маршрута
• POST /api/routes/optimize - оптимизация маршрута
• POST /api/locations/search - поиск адресов и POI
• GET /api/locations/nearby - ближайшие места

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

• Расчет маршрутов для разных видов транспорта
• Поиск и геокодирование адресов
• Кэширование популярных маршрутов
• Сохранение пользовательских маршрутов
• Оптимизация маршрутов с множественными точками

Преимущества выбранного стека

Go

• Высокая производительность - критично для геоопераций
• Отличная конкурентность - параллельные запросы к внешним API
• Простой деплой - один бинарный файл
• Низкое потребление памяти - важно при масштабировании
• Встроенная поддержка JSON - для API ответов

PostgreSQL + PostGIS

• Лидирующее решение для геопространственных данных
• Эффективное хранение координат, маршрутов и геозон
• Сложные геооперации через расширение PostGIS
• Индексирование геоданных для быстрых запросов

Redis

• Быстрая выдача популярных маршрутов
• Снижение нагрузки на основную БД и сервисы маршрутизации
• Кэширование результатов геокодирования

План разработки

Этап 1: Инфраструктура (1-2 недели)

• Настройка Docker окружения
• Подключение PostgreSQL + PostGIS
• Настройка Redis
• Базовый Go сервер с Gin

Этап 2: Основной функционал (3-4 недели)

• Интеграция с OSRM API
• Базовые эндпоинты маршрутизации
• Простая карта с отображением маршрутов
• Геокодирование адресов

Этап 3: Расширенные функции (5-6 недель)

• Поиск POI и адресов
• Сохранение маршрутов в БД
• Кэширование популярных маршрутов
• Оптимизация маршрутов

Этап 4: Оптимизация (7-8 недель)

• Производительность и масштабирование
• Тестирование API
• Улучшение UI/UX
• Мониторинг и логирование

Масштабирование

При росте нагрузки

• Переход на Valhalla для более сложных маршрутов
• Рассмотрение коммерческих API (Google Maps, Mapbox)
• Горизонтальное масштабирование через микросервисы
• CDN для статических ресурсов карт

Мониторинг

• Метрики производительности API
• Мониторинг использования внешних сервисов
• Логирование ошибок и медленных запросов
• Алерты при превышении лимитов

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

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

• Go 1.23+ - для разработки
• Docker & Docker Compose - для инфраструктуры
• Make - для удобных команд

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

# 1. Клонирование репозитория
git clone <repository-url>
cd coords

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

# 3. Запуск инфраструктуры
docker-compose up -d

# 4. Установка зависимостей и настройка
make setup

# 5. Применение миграций БД
make migrate

# 6. Запуск сервера
make run

Подробные команды

Настройка проекта

# Установка зависимостей Go
go mod download

# Генерация Swagger документации
swag init -g cmd/server/main.go -o api/docs

# Сборка проекта
make build

Работа с Docker

# Запуск всех сервисов
docker-compose up -d

# Просмотр логов
docker-compose logs -f

# Остановка сервисов
docker-compose down

# Пересборка контейнеров
docker-compose up -d --build

# Очистка данных (ОСТОРОЖНО!)
docker-compose down -v

Работа с базой данных

# Применение миграций
make migrate

# Подключение к PostgreSQL
docker-compose exec db psql -U coords_user -d coords_db

# Сброс базы данных
make db-reset

Разработка

# Запуск сервера в режиме разработки
make run

# Запуск с hot reload (если установлен air)
make dev

# Тестирование
make test

# Проверка кода
make lint

Swagger документация

# Генерация документации
make swagger

# Просмотр Swagger UI
# Откройте браузер: http://localhost:8080/swagger/index.html

Доступные Make команды

make help          # Показать все доступные команды
make setup         # Первоначальная настройка проекта
make build         # Сборка бинарного файла
make run           # Запуск сервера
make dev           # Запуск в режиме разработки
make test          # Запуск тестов
make migrate       # Применение миграций БД
make db-reset      # Сброс базы данных
make swagger       # Генерация Swagger документации
make clean         # Очистка временных файлов
make docker-up     # Запуск Docker сервисов
make docker-down   # Остановка Docker сервисов

Запуск фронтенда

# Переход в папку фронтенда
cd frontend

# Установка зависимостей
npm install

# Настройка переменных окружения
cp .env.example .env
# Отредактируйте .env файл, добавив ваш API ключ Яндекс.Карт

# Запуск в режиме разработки
npm start

⚠️ Важно: Добавьте API ключ Яндекс.Карт в файл frontend/.env:

REACT_APP_YANDEX_MAPS_API_KEY=ваш_ключ_здесь

Получить ключ можно на Яндекс.Разработчик

Фронтенд будет доступен по адресу: http://localhost:3000

Проверка работы

После запуска сервера проверьте:

1. Health check: http://localhost:8080/health
2. Swagger UI: http://localhost:8080/swagger/index.html
3. API документация: http://localhost:8080/api-docs.json
4. Frontend: http://localhost:3000

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

• 3000 - React фронтенд
• 8080 - основной API сервер
• 5433 - PostgreSQL (внешний порт)
• 6379 - Redis
• 5001 - OSRM backend

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

Создайте файл .env на основе .env.example:

# Приложение
APP_PORT=8080
APP_ENV=development

# База данных
DB_HOST=localhost
DB_PORT=5433
DB_NAME=coords_db
DB_USER=coords_user
DB_PASSWORD=coords_password

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRE_HOURS=24

# OSRM
OSRM_HOST=localhost
OSRM_PORT=5001

# Nominatim
NOMINATIM_URL=https://nominatim.openstreetmap.org

Устранение проблем

Проблемы с портами

# Проверка занятых портов
lsof -i :8080
lsof -i :5433
lsof -i :6379
lsof -i :5001

# Остановка процессов на портах
sudo lsof -ti:8080 | xargs kill -9

Проблемы с базой данных

# Проверка статуса PostgreSQL
docker-compose exec db pg_isready -U coords_user

# Просмотр логов БД
docker-compose logs db

# Пересоздание БД
docker-compose down -v
docker-compose up -d
make migrate

Проблемы с OSRM

# Проверка статуса OSRM
curl http://localhost:5001/route/v1/driving/37.6173,55.7558;37.6173,55.7558

# Просмотр логов OSRM
docker-compose logs osrm-backend

# Пересоздание OSRM с картой
docker-compose down
docker-compose up -d osrm-backend

Лицензия

MIT License

Ссылки

[1] Habr: Построение маршрутов с OSRM [2] 2GIS: Алгоритмы маршрутизации [3] Leaflet React TypeScript [4] Habr: Геопространственные данные