XKCD Search

Веб-приложение для поиска комиксов XKCD по текстовой фразе. Проект состоит из набора Go-микросервисов: они загружают данные из XKCD, нормализуют текст, сохраняют индексируемые данные в Postgres и отдают поиск через HTTP API и HTML-интерфейс.

Архитектура

Основной код находится в search-services/.

• frontend - веб-интерфейс на Go templates. Отдает главную страницу, ленту результатов, discover-ленту и страницу администратора.
• api - публичный HTTP API. Принимает REST-запросы, проверяет авторизацию для админских операций и проксирует вызовы во внутренние gRPC-сервисы.
• words - gRPC-сервис нормализации текста: приводит слова к нижнему регистру, удаляет стоп-слова и применяет stemming.
• update - gRPC-сервис обновления базы. Загружает комиксы из XKCD, нормализует title/alt/transcript через words, сохраняет их в Postgres и публикует события в NATS.
• search - gRPC-сервис поиска. Читает данные из Postgres, ранжирует совпадения и поддерживает in-memory индекс для быстрого поиска.
• postgres - хранит таблицу comics с URL и нормализованными словами из title, alt и transcript.
• nats - передает события xkcd.db.updated и xkcd.db.dropped от update к search, чтобы поисковый индекс обновлялся или очищался.
• victoriametrics и grafana - инфраструктура для сбора и просмотра метрик.

Внешний пользователь обычно работает с frontend. Поток поиска выглядит так:

browser -> frontend -> api -> search -> postgres / in-memory index
                         |
                         -> words

Поток обновления базы:

admin/frontend -> api -> update -> XKCD
                         |
                         -> words -> postgres -> NATS -> search index

Возможности

• поиск комиксов по фразе через /api/search;
• быстрый поиск по in-memory индексу через /api/isearch;
• получение информации о конкретном комиксе через /api/comics/{id};
• веб-лента результатов /feed?phrase=...;
• discover-лента случайных комиксов /feed/discover;
• админ-панель /admin с логином, статистикой, статусом обновления, запуском update и очисткой базы;
• health-check /api/ping и метрики /metrics;
• unit- и интеграционные тесты.

Запуск

Для запуска нужен Docker или Podman.

make up

После старта доступны:

• frontend: http://localhost:28090
• HTTP API: http://localhost:28080
• pgAdmin: http://localhost:18888
• Grafana: http://localhost:3000

Админские учетные данные по умолчанию задаются в compose.yaml: admin / password (это облегчение сделано для облегчения проверки с помощью теста, во время разработки данного проекта)

Тесты и разработка

make unit       # unit-тесты сервисов
make test       # полный запуск кластера и интеграционные тесты
make lint       # линтеры
make proto      # генерация protobuf/gRPC-кода
make clean      # остановить кластер и удалить volumes

Дополнительные интеграционные тесты лежат в tests/, примеры работы с NATS - в examples/.