Интерфейсы и интеграционные взаимодействия

После контекста системы (03.01.02 Моделирование контекста системы (Context Diagram)) и декомпозиции (03.01.03 Декомпозиция системы на подсистемы и модули) аналитик фиксирует, как части обмениваются данными и управляющими воздействиями — между собой и с внешним миром. Эта заметка закрывает вопрос: что описать на границе интерфейса и на каком уровне детализации, не уходя в выбор протоколов и инфраструктуры (это — 03.05.01 Виды интеграции (точка-точка, ESB, API-led) и смежные статьи блока 03.05).

1. Суть темы

Интерфейс (Interface) — граница, через которую две системы, подсистемы или модуля обмениваются информацией или управляющими воздействиями. Интерфейс определяет что и когда передаётся, скрывая внутреннюю реализацию.

Интеграция (Integration) — установление и поддержание таких обменов между независимо разработанными частями.

В отличие от разработчика или архитектора, системный аналитик отвечает за смысловую корректность интерфейса: какие бизнес-данные передаются, при каких событиях, с какими ожидаемыми результатами, ограничениями и ответственностью сторон. Технический протокол (REST, Kafka, SFTP) — следствие требований, а не отправная точка анализа.

Внутренние и внешние интерфейсы

Критерий для аналитика один: есть ли формальный контракт между независимыми зонами ответственности. Внутренний интерфейс после декомпозиции прорабатывается теми же шагами (сценарий → логический контракт → примеры → согласование → SRS), но владелец контракта — product owner или tech lead смежного модуля, а не внешний партнёр. Глубина формализации зависит от числа команд и релизной независимости модулей — см. 03.01.03 Декомпозиция системы на подсистемы и модули. Версионирование и обратная совместимость важны и внутри монолита, если модули развиваются разными командами.

Связка «экран → backend-контракт»: пользовательский интерфейс описывается в 02.02.04 Прототипирование и UI-UX-исследования и 10.01.09 Шаблон описания экранной формы и логики на FE, а аналитик дополнительно фиксирует, какой API- или event-контракт обслуживает каждый экран.

2. Ключевые понятия

2.1. Классификация для моделирования

По типу сторон

Ось механизмов обмена — для каждого интерфейса зафиксируйте инициатор (consumer), поставщик (provider), триггер (событие домена — см. 03.04.01 BPMN 2.0 - введение и основы, команда пользователя, расписание) и строку из таблицы ниже:

По архитектурному стилю интеграции (топология ландшафта) аналитик на этапе SA достаточно понимает ось «точка-точка → шина/ESB → API-led → событийная архитектура» и фиксирует выбранный стиль в архитектурном решении (10.01.13 Шаблон архитектурного решения (ADR)). Развёрнутое сравнение — в 03.05.01 Виды интеграции (точка-точка, ESB, API-led); service mesh и оркестрация контейнеров — в 03.06.01 Архитектурные паттерны распределённых систем.

2.2. Три уровня спецификации

1. Бизнес-уровень: зачем обмен, какие данные, бизнес-правила. Артефакты: потоки на 03.01.02 Моделирование контекста системы (Context Diagram), краткое описание в Vision&Scope (04.01 Форматы документов (Vision&Scope, BRD, SRS, FRD)).
2. Логический уровень: структуры сообщений, коды ошибок как бизнес-смысл, последовательность вызовов. Артефакты: 03.03.02 Логическая и физическая модель данных, 03.02.03 Диаграмма последовательности (Sequence Diagram), примеры payload.
3. Физический уровень: протокол, endpoints, HTTP-коды, сериализация, таймауты, аутентификация. Артефакты: 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf), шаблоны 10.01.04 Шаблон спецификации REST API, 10.01.06 Шаблон спецификации Producer (Kafka, RabbitMQ), 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ).

Системный аналитик детально ведёт бизнес- и логический уровни; физический — совместно с разработчиками и архитектором. Пути URL и HTTP status codes в примерах ниже — черновик физического уровня для передачи в OpenAPI, а не обязательная часть логической спецификации.

2.3. Минимальный чеклист логического контракта

Перед передачей в разработку проверьте, что контракт содержит:

• Операции (имена, направление вызова, инициатор).
• Схемы запроса и ответа (типы, обязательность, справочники).
• Модель ошибок (коды, тексты, повторяемость операции).
• Идемпотентность — для мутирующих операций: ключ или business id (REST — в теле/заголовке; messaging — deduplication id consumer'а).
• SLA на уровне требования: допустимая latency, timeout, rate limiting (03.06.03 Rate Limiting — управление пропускной способностью).
• Auth на уровне требования (кто может вызывать, scope ролей) — реализация в 03.05.05 Безопасность API.
• Версионирование — только политика «breaking / non-breaking»; сроки deprecation — 03.05.07 Управление версионированием API и жизненным циклом.

Для событийного интерфейса добавьте: имя события, schema payload, ordering (нужен ли порядок), семантика доставки (at-least-once / exactly-once) и ответственность consumer за обработку дубликатов.

Для файлового обмена: маска имени, расписание, формат, ack/nack, действие при ошибке парсинга, идемпотентность повторной доставки (тот же файл повторно — skip или overwrite по business id).

2.4. Contract-First и API-First

• Contract-First — порядок работ: сначала согласованный контракт между командами, затем параллельная реализация и моки.
• API-First — продуктовая дисциплина: API как первоклассный продукт (документация, версии, DX).

На практике аналитик чаще оперирует Contract-First; API-First задаёт контекст для публичных и partner API. Уровни зрелости REST (Richardson Maturity Model) — ориентир для архитекторов, не цель SA на этом уровне; достаточно логического контракта и error model. Контрактное тестирование (например, Pact) дополняет подход на стороне QA — см. 08.03 Тестирование требований (статическое тестирование).

3. Как применяется в работе аналитика

Методика соответствует BABOK v3, задача 8.1 Analyze Interface Requirements (см. 00.04 Основные стандарты и своды знаний (BABOK, SEBoK, ISO 29148)): от сценария через логический контракт к требованиям и трассировке. ISO/IEC/IEEE 42010 задаёт рамку архитектурного описания: интерфейсы фиксируются в viewpoint, релевантном для stakeholder'ов интеграции (владелец контракта, команда потребителя, безопасность).

3.1. Пошаговая методика

Пример A — внешний интерфейс. С контекстной диаграммы известно: «Интернет-магазин» обменивается с «Платёжным шлюзом» потоками «Запрос на списание» и «Результат платежа».

1. Привязать к бизнес-сценарию: оформление заказа → оплата (03.02.01 Диаграмма прецедентов (Use Case Diagram)).
2. Описать логический контракт (см. чеклист §2.3): событие «Пользователь нажал Оплатить» → PaymentRequest → PaymentConfirmation / PaymentError; НФТ: ответ ≤ 5 с, идемпотентность по orderId, TLS (08.02 Нефункциональные требования (НФТ) — классификация и стандарты).
3. Примеры сообщений — логические структуры и черновик REST (§3.2), по 10.01.04 Шаблон спецификации REST API.
4. Согласовать с владельцем смежной системы: RACI (кто утверждает контракт), тестовая среда, sandbox, mock, MoU с подрядчиком; критерии sign-off — 02.04.02 Критерии приёмки (Acceptance Criteria).
5. Зафиксировать в SRS/FRD и 02.03.04 Трассировка требований (концепция) / 10.01.15 Шаблон матрицы трассировки.

Пример B — внутренний интерфейс. После декомпозиции модуль «Оформление» вызывает модуль «Платежи» внутри подсистемы «Заказы». Шаги 1–5 те же; на шаге 4 владелец — PO или lead команды «Платежи», согласование через внутренний ADR (10.01.13 Шаблон архитектурного решения (ADR)), без MoU с вендором.

Пример C — async. Модуль «Оформление» публикует OrderPlaced; «Склад» и «Аналитика» подписываются асинхронно. Логический контракт: имя события, payload, at-least-once, consumer обрабатывает дубликаты по orderId. Шаги 1–3 и 5 те же; на шаге 4 согласуйте с каждым consumer отдельно: per-consumer SLA, владелец схемы события (schema registry / топик), политику дубликатов и ordering. Физическая спецификация — 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf) и шаблоны Producer/Consumer. Выбор «пример A vs C»: если UX блокируется до ответа — sync; если достаточно eventual consistency — async.

Пример D — экран → API. Экран «Оплата заказа» (10.01.09 Шаблон описания экранной формы и логики на FE): кнопка «Оплатить» → один sync-вызов authorizePayment.

Модель ошибок для UX: INSUFFICIENT_FUNDS → сообщение под формой, кнопка активна; timeout > 5 с → «Повторить»; успех → переход на экран подтверждения. Такой mapping — часть логического контракта UI-слоя, не дублирующая OpenAPI.

3.2. Пример согласованного контракта (логика + черновик REST)

Логический уровень (операция authorizePayment):

Черновик физического уровня (для OpenAPI — не обязателен в SRS аналитика):

POST /api/payment/authorize
{
  "orderId": "ORD-2025-001234",
  "amount": 15420.50,
  "currency": "RUB",
  "description": "Смартфон XYZ",
  "idempotencyKey": "ORD-2025-001234"
}
 
→ 200: PaymentConfirmation
→ 422: PaymentError (INSUFFICIENT_FUNDS)

Аналитик не обязан писать финальный OpenAPI, но обязан дать логическую модель с error path; path и HTTP-коды передаются разработчикам как черновик.

3.3. Моделирование: выбор артефакта

На sequence-диаграмме ниже HTTP-нотация — соглашение для разработчиков; логически это вызов authorizePayment(PaymentRequest).

sequenceDiagram
    participant Customer as Покупатель
    participant Shop as Интернет-магазин
    participant Gateway as Платёжный шлюз

    Customer->>Shop: Нажатие "Оплатить заказ"
    Shop->>Gateway: authorizePayment (PaymentRequest)
    Gateway-->>Gateway: Проверка карты и баланса
    alt Платёж успешен
        Gateway-->>Shop: PaymentConfirmation
        Shop-->>Customer: Заказ оплачен
    else Платёж отклонён
        Gateway-->>Shop: PaymentError
        Shop-->>Customer: Ошибка, повторить
    end

3.4. Связь с процессом анализа

Проработанные интерфейсы:

• дают основу интеграционного тестирования (08.03 Тестирование требований (статическое тестирование));
• разделяют зоны ответственности между командами;
• проходят change control при изменении контракта (02.05.02 Управление изменениями (Change Control Board));
• питают оценку рисков (08.05 Управление рисками на этапе анализа);
• получают критерии приёмки контракта — кто и при каких условиях считает спецификацию согласованной (02.04.02 Критерии приёмки (Acceptance Criteria)).

Единая семантика полей — через 03.03.03 Словарь данных (описание). Хорошо структурированные контракты упрощают генерацию спецификаций и тестов; применение LLM в этом контуре — 11.07 Практические кейсы применения LLM в анализе.

4. Типовые ошибки и ограничения

• Только «солнечный день»: нет error model, timeout, retry — контракт не готов к приёмке. Критерий готовности: для каждой операции описаны успех, известные ошибки и поведение при повторе; sign-off — по 02.04.02 Критерии приёмки (Acceptance Criteria).
• Смешение уровней в спецификации: URL, HTTP-коды и брокер в SRS вместо логических структур и бизнес-кодов ошибок.
• Излишняя детализация чужого слоя: curl-примеры, TCP, выбор брокера — вместо бизнес-контракта и сценариев.
• Копирование legacy без осмысления: перенос структуры SOAP в REST с устаревшими справочниками (10.01.05 Шаблон спецификации SOAP API).
• Семантический разрыв: status = 1 значит разное в разных системах — нужен 03.03.03 Словарь данных (описание).
• Sync там, где нужен async: ожидание мгновенного ответа при интеграции через очередь с задержкой часами.
• Shared DB без плана выхода: фиксируйте владельца данных и целевой контракт (API или события).
• Игнор внутренних границ и UI-контракта: описан только внешний шлюз, хотя декомпозиция выделила модули и экраны с отдельными командами.
• Дублирование протокольного гайда: выбор REST vs gRPC vs GraphQL — в 03.05.02 Синхронные протоколы (REST, gRPC, GraphQL); здесь достаточно оси механизмов и чеклиста контракта.

Связи с другими разделами базы

• 03.01.02 Моделирование контекста системы (Context Diagram) — источник внешних потоков.
• 03.01.03 Декомпозиция системы на подсистемы и модули — внутренние границы и глубина формализации.
• 03.01.01 Понятие архитектуры ИС и её виды (бизнес-, системная, техническая) — место интерфейсов в архитектурном описании.
• 06.03.05 C4-модель — контракты между контейнерами.
• 03.02.01 Диаграмма прецедентов (Use Case Diagram) — привязка интерфейса к сценарию.
• 03.02.03 Диаграмма последовательности (Sequence Diagram) — временная логика обмена.
• 03.03.02 Логическая и физическая модель данных — структуры сообщений.
• 03.03.03 Словарь данных (описание) — единая семантика полей.
• 03.04.01 BPMN 2.0 - введение и основы — триггеры «событие домена».
• 03.04.02 Диаграмма потоков данных (DFD) — потоки на уровне подсистем.
• 03.05.01 Виды интеграции (точка-точка, ESB, API-led) — топология ландшафта.
• 03.05.02 Синхронные протоколы (REST, gRPC, GraphQL) — физический уровень sync API.
• 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf) — форматы контрактов.
• 03.05.04 Асинхронное взаимодействие (очереди, Kafka, Events) — async и messaging.
• 03.05.06 Event-Driven Architecture — событийные паттерны интеграции.
• 03.05.05 Безопасность API — требования к защите интерфейсов.
• 03.05.07 Управление версионированием API и жизненным циклом — политика версий.
• 02.02.04 Прототипирование и UI-UX-исследования — пользовательский слой интерфейса.
• 10.01.09 Шаблон описания экранной формы и логики на FE — экран → API mapping.
• 10.01.04 Шаблон спецификации REST API — артефакт sync-контракта.
• 10.01.13 Шаблон архитектурного решения (ADR) — фиксация решений по интеграции.
• 02.03.04 Трассировка требований (концепция) — связь интерфейса с требованиями и тестами.
• 02.04.02 Критерии приёмки (Acceptance Criteria) — sign-off контракта.
• 08.02 Нефункциональные требования (НФТ) — классификация и стандарты — SLA и ограничения интерфейса.
• 08.03 Тестирование требований (статическое тестирование) — контрактное и интеграционное тестирование.
• 08.05 Управление рисками на этапе анализа — риски на границах интеграции.
• 00.04 Основные стандарты и своды знаний (BABOK, SEBoK, ISO 29148) — BABOK 8.1, ISO 42010.
• 10.02 Разбор кейса "Миграция legacy-системы" — shared DB и поэтапный выход.
• 11.07 Практические кейсы применения LLM в анализе — генерация и проверка контрактов.
• 02.05.02 Управление изменениями (Change Control Board) — изменение согласованного контракта.

Источники и дополнительные материалы

Книги и стандарты

• Gregor Hohpe, Bobby Woolf. Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions. Addison-Wesley, 2003. — https://www.enterpriseintegrationpatterns.com/
• Martin Fowler. Patterns of Enterprise Application Architecture. Addison-Wesley, 2002 (главы по интеграции и messaging). — https://martinfowler.com/books/eaa.html
• IIBA. BABOK Guide v3, разделы 7.6 «Specify and Model Requirements» и 8.1 «Analyze Interface Requirements». — https://www.iiba.org/standards-and-resources/babok/
• INCOSE / SEBoK. «System Architecture» — интерфейсы в архитектурном описании. — https://sebokwiki.org/wiki/System_Architecture
• ISO/IEC/IEEE 42010 — архитектурное описание, viewpoints и интерфейсы как элемент описания.
• OpenAPI Initiative. OpenAPI Specification (актуальная версия). — https://spec.openapis.org/oas/latest.html
• AsyncAPI Initiative. AsyncAPI Specification 3.0.0. — https://www.asyncapi.com/docs/reference/specification/v3.0.0

Статьи и спецификации

• Bill Doerrfeld. «API-First Development: What It Is and Why It Matters». Nordic APIs, 2022. — https://nordicapis.com/api-first-development-what-it-is-and-why-it-matters/
• Leonard Richardson, Martin Fowler. «Richardson Maturity Model» (уровни зрелости REST) — https://martinfowler.com/articles/richardsonMaturityModel.html
• IETF draft. «Idempotency-Key» HTTP header — https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-idempotency-keys-header
• Pact Foundation. Документация по contract testing. — https://docs.pact.io/