Новый разработчик спрашивает: «А этот сервис отвечает за расчет налогов?» Аудитор уточняет: «Где хранятся чувствительные данные и кто к ним имеет доступ?» Архитектор интересуется: «Какие внешние системы зависят от этого сервиса?» Ответы часто приходится собирать из кода, чатов и памяти участников. Паспорт сервиса — компактный документ, фиксирующий базовые факты о месте сервиса в системе. Он не заменяет детальную спецификацию, но дает быстрый ориентир для новых членов команды, аудиторов и смежных разработчиков.
Зачем нужен паспорт сервиса
Паспорт сервиса отвечает на вопросы «кто я» и «с кем я взаимодействую», но не «как именно я делаю свою работу». Его главная ценность — в явном определении границ. В распределенных системах границы между сервисами часто размыты: один сервис считает скидку, другой применяет ее, третий логирует факт применения. Без документа, который четко разделяет эти зоны, возникают дублирование функций, гонки за данными и конфликты при изменении требований.
Документ полезен в трех ситуациях: при онбординге нового разработчика, при планировании изменения в смежном сервисе (нужно знать, кого затронет) и при аудите (нужно быстро показать, где хранятся чувствительные данные). Паспорт пишется один раз и обновляется при каждом значимом изменении архитектуры.
Структура паспорта
Шаблон состоит из шести основных блоков. Каждый блок содержит только те сведения, которые помогают понять место сервиса в системе, но не погружаются во внутреннюю реализацию.
- Общая информация — название, назначение, владелец, статус.
- Границы ответственности — что сервис делает и чего он точно не делает.
- Данные — основные сущности, хранение, политика жизненного цикла.
- Интерфейсы — публичные API, события, форматы данных.
- Зависимости — внешние сервисы, базы, очереди, на которые опирается данный сервис.
- Ограничения и 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-service | HTTP | Получение метаданных товара | Мягкая | Кэш на 5 минут, fallback на последние известные данные | < 100 мс |
| warehouse-db | PostgreSQL | Основное хранилище данных | Жесткая | Fail-fast: возврат ошибки 503, retry до 3 раз | < 50 мс |
| kafka-broker | Queue | Публикация событий | Мягкая | Transactional Outbox: события записываются в БД, публикуются позже | < 2 сек (asynch) |
| auth-service | gRPC | Аутентификация пользователей | Жесткая | Fail-fast: без токена доступ запрещен | < 200 мс |
| metrics-collector | UDP | Сбор метрик мониторинга | Мягкая | 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, ссылаясь на них из паспорта.
