← Все статьи

Шаблон описания сервиса: ответственность, данные и зависимости

· 9 мин чтения

Шаблон паспорта сервиса: границы ответственности, данные, контракты и зависимости. Заполненный пример для учебного сервиса инвентаря с таблицей зависимостей и проверками.

Новый разработчик спрашивает: «А этот сервис отвечает за расчет налогов?» Аудитор уточняет: «Где хранятся чувствительные данные и кто к ним имеет доступ?» Архитектор интересуется: «Какие внешние системы зависят от этого сервиса?» Ответы часто приходится собирать из кода, чатов и памяти участников. Паспорт сервиса — компактный документ, фиксирующий базовые факты о месте сервиса в системе. Он не заменяет детальную спецификацию, но дает быстрый ориентир для новых членов команды, аудиторов и смежных разработчиков.

Зачем нужен паспорт сервиса

Паспорт сервиса отвечает на вопросы «кто я» и «с кем я взаимодействую», но не «как именно я делаю свою работу». Его главная ценность — в явном определении границ. В распределенных системах границы между сервисами часто размыты: один сервис считает скидку, другой применяет ее, третий логирует факт применения. Без документа, который четко разделяет эти зоны, возникают дублирование функций, гонки за данными и конфликты при изменении требований.

Документ полезен в трех ситуациях: при онбординге нового разработчика, при планировании изменения в смежном сервисе (нужно знать, кого затронет) и при аудите (нужно быстро показать, где хранятся чувствительные данные). Паспорт пишется один раз и обновляется при каждом значимом изменении архитектуры.

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

Шаблон состоит из шести основных блоков. Каждый блок содержит только те сведения, которые помогают понять место сервиса в системе, но не погружаются во внутреннюю реализацию.

  1. Общая информация — название, назначение, владелец, статус.
  2. Границы ответственности — что сервис делает и чего он точно не делает.
  3. Данные — основные сущности, хранение, политика жизненного цикла.
  4. Интерфейсы — публичные API, события, форматы данных.
  5. Зависимости — внешние сервисы, базы, очереди, на которые опирается данный сервис.
  6. Ограничения и SLA — ключевые нефункциональные требования.

Такая структура позволяет держать документ на одной-двух страницах. Если блок требует более десяти строк текста, вероятно, часть информации должна уйти в детализированную спецификацию или ADR.

Границы ответственности: что делать и чего не делать

Это самый критичный раздел. Здесь перечисляются две группы пунктов: функции, за которые сервис несет полную ответственность, и функции, которые он сознательно исключает. Исключения важнее включений, потому что именно они предотвращают «расползание» ответственности.

Формулировки должны быть однозначными. Вместо «управляет заказами» лучше писать «создает, изменяет и завершает заказы в состоянии 'Активен'; не обрабатывает возвраты после завершения заказа». Второй пункт — прямой запрет, который снимает двусмысленность.

В учебных примерах часто возникает соблазн добавить сюда детали реализации («использует алгоритм XYZ»). Это ошибка: паспорт описывает поведение, а не механизм. Алгоритмы и технологии фиксируются в ADR или технических спецификациях.

Данные: сущности и хранение

В этом разделе указываются основные сущности, которые сервис создает и управляет. Для каждой сущности фиксируются: имя, тип хранилища, ключевые атрибуты и политика удаления.

Важно различать «владелец данных» и «читатель данных». Сервис является владельцем данных, если он единственный, кто может создавать, изменять или удалять записи. Другие сервисы могут читать эти данные только через API владельца, а не напрямую из базы. Это правило изоляции должно быть явно указано в паспорте.

Для учебных целей достаточно перечислить три-четыре ключевые сущности. Детальная схема с колонками и индексами не входит в паспорт — она живет в DDL-скриптах или ER-диаграммах.

Интерфейсы: контракты, а не реализации

Здесь описываются публичные точки входа: REST API, gRPC, опубликование событий. Для каждого интерфейса указывается: метод, путь/тема, формат запроса и ответа, уровень совместимости.

Ключевой принцип: паспорт ссылается на контракт (OpenAPI, AsyncAPI, protobuf), а не копирует его. Контракты живут в отдельных файлах, а в паспорте указывается их расположение и краткое описание назначения. Это сохраняет документ компактным и избегает расхождений между описанием и реальным контрактом.

Для событий важно указать гарантию доставки (at-least-once, at-most-once) и требование идемпотентности на стороне потребителя. Эти параметры влияют на архитектуру потребителей и должны быть известны заранее.

Зависимости: кто нам нужен

Этот раздел перечисляет все внешние ресурсы, без которых сервис не сможет выполнять свои функции. Зависимости делятся на жесткие (сервис падает без них) и мягкие (сервис работает в ограниченном режиме). Для каждой зависимости указывается: название, тип, роль и ожидаемое время отклика.

Явное указание жестких зависимостей помогает при проектировании отказоустойчивости: если зависимость недоступна, сервис должен либо вернуть ошибку, либо работать в деградированном режиме. Этот выбор фиксируется в ADR, но в паспорте указывается сам факт зависимости.

Заполненный пример: сервис инвентаря

Ниже приведен заполненный паспорт для учебного сервиса управления складским запасом. Все названия и значения являются условными и используются исключительно для демонстрации структуры документа.

# Паспорт сервиса: Inventory Service

## Общая информация
- Название: inventory-service
- Назначение: Управление остатками товаров на складах
- Владелец: Команда логистики
- Статус: Активен
- Версия: 1.2.0

## Границы ответственности
### Делает:
- Ведет учет количества единиц товара на каждом складе
- Обрабатывает операции приход/отход с проверкой достаточности остатка
- Предоставляет API для чтения текущих остатков
- Публикует событие "InventoryChanged" при изменении остатка

### Не делает:
- Не рассчитывает цены товаров (ответственность pricing-service)
- Не управляет физическим движением товара (ответственность wms-service)
- Не хранит историю операций старше 90 дней (архивирует в data-lake)
- Не обеспечивает резервирование товара для конкретных заказов

## Данные
| Сущность | Хранилище | Владелец | Политика удаления |
|-----------|-----------|----------|-------------------|
| ItemStock | PostgreSQL | Да | Soft delete, архив через 90 дней |
| Warehouse | PostgreSQL | Да | Не удаляется, только деактивация |
| StockTransaction | PostgreSQL | Да | Hard delete через 90 дней |

## Интерфейсы
### REST API (v1)
- GET /api/v1/stock/{itemId} — Получить остатки по товару
- POST /api/v1/transactions — Создать операцию приход/отход
- Контракт: openapi/inventory-v1.yaml

### Events
- Тема: inventory.changed.v1
- Формат: Avro
- Гарантия: At-least-once
- Требование: Потребители должны быть идемпотентными
- Контракт: asyncapi/inventory-events.json

## Зависимости
| Зависимость | Тип | Роль | Жесткость |
|-------------|-----|------|-----------|
| product-service | HTTP | Получение метаданных товара | Мягкая (кэш 5 мин) |
| warehouse-db | PostgreSQL | Основное хранилище | Жесткая |
| kafka-broker | Queue | Публикация событий | Мягкая (outbox pattern) |

## Ограничения и SLA
- Доступность: 99.9% (кроме плановых окон) 
- Время отклика P95: < 200 мс для чтения, < 500 мс для записи
- Максимальный размер батча операций: 1000 записей

Обратите внимание на раздел «Не делает»: четыре пункта прямо запрещают функции, которые могли бы быть ошибочно приписаны этому сервису. Раздел «Данные» использует таблицу для компактного представления. В «Интерфейсах» указаны ссылки на контракты, а не сами контракты. В «Зависимостях» отмечена жесткость: база данных — жесткая зависимость, а Kafka — мягкая благодаря outbox pattern.

Таблица зависимостей: как читать

Таблица зависимостей — ключевой элемент паспорта, позволяющий быстро оценить влияние отказа внешнего ресурса. Ниже представлена расширенная версия таблицы из примера с пояснением каждого столбца.

ЗависимостьТипРольЖесткостьСтратегия отказаSLA времени
product-serviceHTTPПолучение метаданных товараМягкаяКэш на 5 минут, fallback на последние известные данные< 100 мс
warehouse-dbPostgreSQLОсновное хранилище данныхЖесткаяFail-fast: возврат ошибки 503, retry до 3 раз< 50 мс
kafka-brokerQueueПубликация событийМягкаяTransactional Outbox: события записываются в БД, публикуются позже< 2 сек (asynch)
auth-servicegRPCАутентификация пользователейЖесткаяFail-fast: без токена доступ запрещен< 200 мс
metrics-collectorUDPСбор метрик мониторингаМягкаяDrop on failure: метрики теряются, сервис продолжает работуНе критично

Столбец «Жесткость» определяет, может ли сервис функционировать без данного ресурса. Жесткая зависимость означает, что без нее сервис не может выполнить основную функцию. Мягкая зависимость означает, что сервис может работать в ограниченном режиме. Столбец «Стратегия отказа» описывает, что происходит при недоступности ресурса: fail-fast (немедленный отказ), fallback (резервный режим), drop (игнорирование). Эти стратегии должны быть согласованы с архитектурой и зафиксированы в ADR.

Проверка полноты паспорта

После заполнения паспорта выполните следующие проверки, чтобы убедиться, что документ действительно полезен:

  • Проверка границ: Возьмите любую функцию смежного сервиса и спросите: «Кому она принадлежит?» Ответ должен однозначно следовать из раздела «Границы ответственности» обоих сервисов.
  • Проверка данных: Для каждой сущности подтвердите, что только один сервис указан как владелец. Если два сервиса заявляют владение одними данными — это красный флаг архитектурного конфликта.
  • Проверка зависимостей: Убедитесь, что каждая жесткая зависимость имеет стратегию обработки отказа (fail-fast, circuit breaker, fallback). Эта стратегия должна быть упомянута в ADR, но сама зависимость — в паспорте.
  • Проверка актуальности: Сравните версию паспорта с версией контрактов OpenAPI/AsyncAPI. Если версии не совпадают — паспорт устарел.

Типичные ошибки при создании паспорта

  • Слишком много деталей: Паспорт превращается в полную спецификацию с описанием алгоритмов, кода и конфигурации. Такой документ никто не читает целиком.
  • Размытые границы: Формулировки вроде «помогает в управлении заказами» не дают ответа на вопрос «кто принимает финальное решение о статусе заказа?»
  • Отсутствие негативных ограничений: Если раздел «Не делает» пуст, значит, границы не определены. Всегда есть функции, которые сервис сознательно не берет на себя.
  • Дублирование контрактов: Копирование схемы JSON или списка эндпоинтов в паспорт приводит к расхождениям при изменении API. Используйте только ссылки.
  • Игнорирование зависимостей: Перечень зависимостей неполный, и при инциденте выясняется, что сервис зависит от внутреннего инструмента мониторинга, который не был упомянут.

Как поддерживать актуальность

Паспорт — живой документ. Он должен обновляться при каждом изменении, которое затрагивает один из шести блоков. Практика такая: при создании пул-реквеста, который добавляет новый эндпоинт, изменяет схему данных или подключает новый внешний сервис, автор обязан обновить соответствующий раздел паспорта в том же PR. Ревьюер проверяет не только код, но и консистентность паспорта.

Раз в квартал проводится ревизия: сравниваются паспорта всех сервисов, проверяются пересечения в зонах ответственности и наличие циклических зависимостей. Результаты ревизии фиксируются в ADR, если требуются архитектурные корректировки.

Итог

Паспорт сервиса — это компактный, структурированный документ, который фиксирует границы ответственности, данные, интерфейсы, зависимости и ограничения. Он не заменяет детальную документацию, но служит первым источником информации для любого человека, работающего с системой. Правильно заполненный паспорт сокращает время на поиск ответов, предотвращает конфликты между командами и упрощает аудит.

Паспорт удобно вести в редакторе Markdown, сохраняя его в корне репозитория сервиса. Структура и стиль соответствуют практике Docs as Code, описанной в статье «Docs as Code». При необходимости расширить описание архитектурных решений, используйте ADR, ссылаясь на них из паспорта.