Лабораторная работа 8: Декомпозиция в микросервисы и контракты сервисов (код аналогично пробуем например тут https://openapi-generator-ui.fugary.com/ или тут https://jdegre.github.io/editor/ , в радиобоксе выставить OpenAPI JSON/YAML Content
или поискать другие песочницы через ИИ или поисковики. Код программы на java или любом другом языке микросервисов сгенерированный разобрать и рассказать, также рассказать как порезали на микросервисы апи методы и почему)
Дисциплина: Проектирование архитектуры информационных систем
Продолжительность: 2 пары (3 акад. часа)
Форма проведения: индивидуальная работа + защита (5–7 минут)
Основной артефакт: комплект OpenAPI контрактов всех микросервисов + контракт точки входа (Gateway/BFF) + модели статусов + таблица взаимодействий
Цель
Закрыть реальную «архитекторскую» боль: микросервисы без контрактов превращаются в хаос. Студент учится нарезать систему (на базе ЛР3–ЛР4) и формализовать:
- входы/выходы каждого сервиса,
- обязательные поля и варианты,
- статусные модели ключевых агрегатов,
- коды ответов/ошибок,
- версионирование и обратную совместимость контрактов.
OpenAPI в этом контексте — индустриальный стандарт контрактов HTTP API.
Исходные данные
Артефакты ЛР3–ЛР4:
- микросервисная (или альтернативная) архитектура,
- границы сервисов и их БД,
- сравнения и ADR — как вход для обоснований.
Инструменты
Текстовый редактор для OpenAPI; (опционально) Swagger UI/Editor для проверки.
Структура работы
Часть A: Уточнение сервисного разбиения и точек входа
- Зафиксировать минимум 3 микросервиса (для маленькой темы) или 4–6 (для типовой).
- Зафиксировать точку входа для клиентов:
- API Gateway или BFF (если в вашей архитектуре он был),
- либо прямой доступ клиента к сервисам (разрешено, но нужно обосновать риски).
Часть B: Контракт каждого микросервиса
Для каждого сервиса сделать минимальный OpenAPI файл, который содержит:
servers,tags,paths(минимум 5 операций на сервис),components/schemas(минимум 3–5 DTO/моделей).
Для каждой операции обязательно указать:
- метод и URL,
- обязательность полей (required),
- варианты ошибок и коды ответов (минимум: 200/201/204/400/401/403/404/409/500),
- краткое назначение на доменном языке.
В пояснении (не кодом) отметить семантику методов: операции чтения должны быть safe, операции обновления/удаления — идемпотентные по intended effect; это важно для ретраев и клиентского поведения.
Часть C: Статусные модели (state model) как часть контракта
Выбрать 1–2 ключевых агрегата (пример: Заказ, Бронь, Заявка, Платеж, Тикет) и сделать:
- диаграмму состояний (можно UML State),
- перечисление допустимых статусов в OpenAPI (
enum), - какие операции переводят объект между статусами,
- какие ответы и ошибки возможны при недопустимом переходе (например, 409 Conflict).
Часть D: Межсервисные взаимодействия и «контракт вызовов»
Составить таблицу взаимодействий (минимум 6 связей):
- кто вызывает (consumer),
- кого вызывает (provider),
- что именно вызывает: endpoint или событие,
- минимальный payload (ключевые поля),
- синхронно/асинхронно,
- требования к безопасности (технический аккаунт, роль, scopes).
Если используете события — кратко описать, почему (слабая связанность, масштабирование обработки). Если остаётесь на REST — объяснить, почему для вашей темы это достаточно.
Часть E: Версионирование и обратная совместимость
Добавить правила эволюции контрактов:
- как будете вводить
/v2, - что можно менять «безболезненно» (additive changes — добавление необязательных полей),
- как объявляете deprecated,
- сколько времени поддерживаете старую версию.
В качестве ориентира допустимо опираться на общие API-guidelines практики крупных платформ (например, рекомендации по управлению API и эволюции), но главное — чтобы правила были едиными и применимыми к вашей системе.
Результаты
- Пакет OpenAPI файлов: по одному на сервис + файл для Gateway/BFF (если есть).
- Таблица «контракты взаимодействий».
- 1–2 диаграммы статусов (state machine) и их отражение в контрактах.
- Короткое описание правил версионирования и обратной совместимости.
Контрольные вопросы
- Почему при микросервисах «контракт важнее кода» и как OpenAPI в этом помогает?
- Почему безопасность API — это не только JWT, но и корректные проверки прав на объекты?
- Что такое обратная совместимость API и как ее обеспечивают при развитии микросервисов?
- Как статусная модель помогает предотвратить некорректные бизнес-переходы?
Критерии оценивания
Полнота набора сервисов и контрактов (30%), корректность моделей/операций/обязательных полей (20%), качество статусных моделей и ошибок переходов (20%), связность межсервисных контрактов (15%), версионирование и обратная совместимость (15%).