🪴 BLOG IT

Требования. Микросервис Каталог

6 min read

Как документировать микросервис

Обзор

Микросервис категорий продуктов предназначен для управления иерархическими категориями продуктов для нескольких сайтов электронной коммерции, специализирующихся на оборудовании для отопления и вентиляции. Он поддерживает операции такие как добавление, обновление, удаление и извлечение категорий. Дополнительно, он предоставляет хлебные крошки для навигации, поддерживает вложенные структуры категорий и включает SEO-оптимизацию.

Презентация. Каталог электронной коммерции

Основные функции

  1. Управление категориями

    • Добавление новой категории для конкретного сайта.
    • Обновление существующей категории для конкретного сайта.
    • Удаление категории (с каскадным удалением дочерних категорий) для конкретного сайта.

  2. Иерархическая структура

    • Категории могут быть организованы в иерархию с максимальным уровнем вложенности до 5 уровней для каждого сайта.
    • Каждая категория имеет следующие атрибуты:
      • id: Уникальный идентификатор (UUID).
      • name: Название категории.
      • slug: Удобная для URL версия названия категории (должна быть уникальной на сайте).
      • parent_id: UUID родительской категории (или NULL для категорий верхнего уровня).
      • site_id: UUID сайта, к которому принадлежит категория.
      • seo_title: (Необязательно) Заголовок для SEO целей.
      • seo_description: (Необязательно) Описание для SEO целей.
      • seo_keywords: (Необязательно) Ключевые слова для SEO целей.

  3. Поддержка нескольких сайтов

    • Микросервис может управлять категориями продуктов для нескольких сайтов электронной коммерции.
    • Сайты хранятся в отдельной таблице sites с следующими атрибутами:
      • id: Уникальный идентификатор (UUID).
      • name: Название сайта (например, “HVAC Store”).
      • description: (Необязательно) Краткое описание сайта.
      • created_at: Время создания сайта.
      • updated_at: Время последнего обновления сайта.

  4. Хлебные крошки на основе slugs

    • Хлебные крошки представлены как slugs, разделенные знаком / (например, heating/boilers/gas-boilers).
    • Хлебные крошки генерируются динамически на основе иерархии для указанного сайта.
    • Если slugs повторяются в рамках конкретного сайта, нужно добавить родительский slug, используя ’-’ в качестве разделителя.

  5. Извлечение вложенных категорий

    • Извлечение всех вложенных категорий, начиная с конкретной category_id для указанного site_id.
    • Вложенная структура включает дочерние категории каждой категории рекурсивно.

  6. Извлечение категорий верхнего уровня

    • Извлечение всех категорий верхнего уровня (категорий, где parent_id равно NULL) для указанного site_id.

  7. Управление SEO информацией

    • Извлечение SEO информации для конкретной категории.
    • Обновление SEO информации для конкретной категории.

  8. Управление сайтами

    • Добавление, обновление, удаление и извлечение информации о сайтах электронной коммерции.
    • Поддержка связей между сайтами и их категориями.

  9. Загрузка данных из НСИ

    1. Чтение топиков кафка dcfgd dsfsdfds
    2. Размещение данных в стейджинговых таблицах
    3. Мердж в боевые таблицы из стейджинговых

API Эндпоинты

  1. Управление сайтами

    • Создание сайта

      • Метод: POST /sites/

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

        {
    "name": "СайтРу",
    "description": "Сайт, специализирующийся на оборудовании для отопления, вентиляции и кондиционирования воздуха."
}

      • Ответ:

        {
    "id": "a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129",
    "name": "СайтРу",
    "description": "Сайт, специализирующийся на оборудовании для отопления, вентиляции и кондиционирования воздуха.",
    "created_at": "2025-01-23T12:00:00Z",
    "updated_at": "2025-01-23T12:00:00Z"
}

    • Извлечение всех сайтов

      • Метод: GET /sites/

      • Ответ:

        [
    {
        "id": "a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129",
        "name": "HVAC Store",
        "description": "Сайт, специализирующийся на оборудовании для отопления, вентиляции и кондиционирования воздуха.",
        "created_at": "2025-01-23T12:00:00Z",
        "updated_at": "2025-01-23T12:00:00Z"
    }
]

    • Извлечение сайта по ID

      • Метод: GET /sites/{id}

      • Ответ:

        {
    "id": "a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129",
    "name": "СайтРу",
    "description": "Сайт, специализирующийся на оборудовании для отопления, вентиляции и кондиционирования воздуха.",
    "created_at": "2025-01-23T12:00:00Z",
    "updated_at": "2025-01-23T12:00:00Z"
}

    • Обновление сайта

      • Метод: PUT /sites/{id}

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

        {
    "name": "Обновленный СайтРу",
    "description": "Обновленное описание для сайта русклимат."
}

      • Ответ:

        {
    "id": "a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129",
    "name": "Обновленный СайтРу",
    "description": "Обновленное описание для сайта HVAC.",
    "created_at": "2025-01-23T12:00:00Z",
    "updated_at": "2025-01-23T12:30:00Z"
}

    • Удаление сайта

      • Метод: DELETE /sites/{id}

      • Ответ:

        {
    "message": "Сайт успешно удален."
}

  2. Управление категориями

    • Добавление категории

      • Метод: POST /categories/

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

        {
    "name": "Котлы",
    "slug": "boilers",
    "parent_id": null,
    "site_id": "a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129",
    "seo_title": "Купить высококачественные котлы",
    "seo_description": "лучшие котлы для ваших нужд в отоплении.",
    "seo_keywords": "котлы, отопительное оборудование"
}

      • Ответ:

        {
    "id": "b12c6d78-5e4f-3b9e-8f7c-45d7e2f3c678",
    "name": "Котлы",
    "slug": "boilers",
    "parent_id": null,
    "site_id": "a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129",
    "seo_title": "Купить высококачественные котлы",
    "seo_description": "лучшие котлы для ваших нужд в отоплении.",
    "seo_keywords": "котлы, отопительное оборудование",
    "created_at": "2025-01-23T12:00:00Z",
    "updated_at": "2025-01-23T12:00:00Z"
}

    • Обновление категории

      • Метод: PUT /categories/{id}

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

        {
    "name": "Обновленные котлы",
    "slug": "updated-boilers",
    "parent_id": null,
    "site_id": "a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129",
    "seo_title": "Обновленный SEO-заголовок котлов",
    "seo_description": "Обновленное описание котлов.",
    "seo_keywords": "котлы, обновлено"
}

      • Ответ:

        {
    "id": "b12c6d78-5e4f-3b9e-8f7c-45d7e2f3c678",
    "name": "Обновленные котлы",
    "slug": "updated-boilers",
    "parent_id": null,
    "site_id": "a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129",
    "seo_title": "Обновленный SEO-заголовок котлов",
    "seo_description": "Обновленное описание котлов.",
    "seo_keywords": "котлы, обновлено",
    "created_at": "2025-01-23T12:00:00Z",
    "updated_at": "2025-01-23T12:30:00Z"
}

    • Удаление категории

      • Метод: DELETE /categories/{id}

      • Параметр запроса: site_id

      • Пример:

        DELETE /categories/b12c6d78-5e4f-3b9e-8f7c-45d7e2f3c678?site_id=a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129

      • Ответ:

        {
    "message": "Категория успешно удалена."
}

    • Извлечение вложенных категорий

      • Метод: GET /categories/{id}/nested

      • Параметр запроса: site_id

      • Пример:

        GET /categories/b12c6d78-5e4f-3b9e-8f7c-45d7e2f3c678/nested?site_id=a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129

      • Ответ:

        {
    "id": "b12c6d78-5e4f-3b9e-8f7c-45d7e2f3c678",
    "name": "Boilers",
    "slug": "boilers",
    "seo_title": "Buy High-Quality Boilers",
    "seo_description": "Find the best boilers for your heating needs.",
    "seo_keywords": "boilers, heating equipment, HVAC",
    "children": [
        {
            "id": "d34f6a89-7b4e-5c9e-8a7d-67e2d5c8a123",
            "name": "Gas Boilers",
            "slug": "gas-boilers",
            "seo_title": "Buy Gas Boilers",
            "seo_description": "Efficient gas boilers for home and commercial use.",
            "seo_keywords": "gas boilers, heating equipment, HVAC",
            "children": []
        }
    ]
}

    • Извлечение хлебных крошек

      • Метод: GET /categories/{id}/breadcrumbs

      • Параметр запроса: site_id

      • Пример:

        GET /categories/b12c6d78-5e4f-3b9e-8f7c-45d7e2f3c678/breadcrumbs?site_id=a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129

      • Ответ:

        {
    "breadcrumbs": "heating/boilers/gas-boilers"
}

    • Извлечение категорий верхнего уровня

      • Метод: GET /categories/top-level

      • Параметр запроса: site_id

      • Пример:

        GET /categories/top-level?site_id=a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129

      • Ответ:

        [
    {
        "id": "e56f7d23-2a4b-5c9e-8f7d-12e3a4c7e456",
        "name": "Heating",
        "slug": "heating",
        "parent_id": null,
        "seo_title": "Shop Heating Equipment",
        "seo_description": "Explore top-quality heating equipment.",
        "seo_keywords": "heating, boilers, HVAC"
    },
    {
        "id": "f67g8d34-3b5c-6d9e-8g7d-23f4b5d8e567",
        "name": "Ventilation",
        "slug": "ventilation",
        "parent_id": null,
        "seo_title": "Shop Ventilation Systems",
        "seo_description": "Discover advanced ventilation systems.",
        "seo_keywords": "ventilation, HVAC, air quality"
    }
]

    • Извлечение SEO информации

      • Метод: GET /categories/{id}/seo

      • Параметр запроса: site_id

      • Пример:

        GET /categories/b12c6d78-5e4f-3b9e-8f7c-45d7e2f3c678/seo?site_id=a23b5c34-1d6f-4b8e-9f5a-25e7c3d5e129

      • Ответ:

        {
    "seo_title": "Buy High-Quality Boilers",
    "seo_description": "Find the best boilers for your heating needs.",
    "seo_keywords": "boilers, heating equipment, HVAC"
}

    • Обновление SEO информации

      • Метод: PUT /categories/{id}/seo

      • Параметр запроса: site_id

      • Пример:

        {
    "seo_title": "Updated Boiler SEO Title",
    "seo_description": "Updated description for boilers.",
    "seo_keywords": "updated, boilers, HVAC"
}

      • Ответ:

        {
    "seo_title": "Updated Boiler SEO Title",
    "seo_description": "Updated description for boilers.",
    "seo_keywords": "updated, boilers, HVAC"
}

    • Обновление slug

      • Метод: PUT /categories/{id}/slug

      • Параметр запроса: site_id

      • Пример:

        {
    "slug": "boilers",
}

      • Ответ:

        {
    "slug": "boilers"
}

Схема базы данных

CREATE TABLE categories (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    slug VARCHAR(255) NOT NULL,
    parent_id INT REFERENCES categories(id) ON DELETE CASCADE,
    site_id INT NOT NULL,
    seo_title VARCHAR(255),
    seo_description TEXT,
    seo_keywords TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE (slug, site_id)
);
 
CREATE TABLE sites (
    id UUID PRIMARY KEY, -- Уникальный идентификатор для сайта
    name VARCHAR(255) NOT NULL, -- Название сайта
    description TEXT, -- Необязательно описание сайта
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -- Время создания сайта
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP -- Время последнего обновления
);
 
CREATE TABLE staging_sites (
    id UUID,
    name TEXT,
    description TEXT,
    staging_created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
CREATE TABLE staging_categories (
    id UUID,
    name TEXT,
    slug TEXT,
    parent_id UUID,
    site_id UUID,
    seo_title VARCHAR(255),
    seo_description TEXT,
    seo_keywords TEXT,
    staging_created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
);

Проектные соображения

  1. Уникальность Slug

    • Slugs должны быть уникальными на одном сайте, чтобы гарантировать правильную работу хлебных крошек и URL.

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

    • Добавить индексы в базе данных на parent_id, slug и site_id для более быстрого поиска.
    • Кэшировать часто запрашиваемые эндпоинты (например, категории верхнего уровня) для повышения производительности.

  3. Обработка ошибок

    • Возвращать ошибку 404, если категория с таким id не существует на указанном сайте.
    • Валидировать входные данные, чтобы они соответствовали схеме.

  4. Масштабируемость

    • Сервис должен эффективно обрабатывать большие иерархии с помощью оптимизации рекурсивных запросов.

Будущие улучшения

  1. Добавить поддержку сортировки категорий по приоритету внутри каждого сайта.
  2. Добавить журнал аудита для изменений категорий на сайте.
  3. Проверка состояния (healthcheck).
  4. Пакетная загрузка(batch load).

Graph View

Backlinks