🙏Собрал развернутое саммари сессии митапа
🔌 pinout: спроектировали валидатор OpenAPI-контрактов и попутно прокачали свои скиллы разработки
На этой сессии проектировали инструмент, который на pre-merge стадии в CI проверяет, что потребитель REST-сервиса совместим с
прод-контрактом поставщика — сравнением их OpenAPI-спек. Без генерации клиентских либ, без подъёма заглушек: чистая функция
«спека vs спека».
🔗 Экосистема: https://github.com/codemonstersteam/pinout
🔗 Сам валидатор: https://github.com/codemonstersteam/pinout-openapi
Что зацепило больше всего
📐 Системные use case по Коберну.
Оказалось, что fully-dressed use case (акторы, предусловия, основной сценарий, extensions =
режимы отказа, гарантии/exit) — это не «бумажка для галочки», а рабочая спецификация. Структура use case изоморфна Gherkin: Main
Success → happy-тест, каждый Extension → один сценарий отказа. Формула сошлась сама собой: N сценариев = 1 + число extensions.
🗺 C4 как уровни дизайна. Разложили проект по уровням C4 на Mermaid (рендерится прямо в GitHub):
• C1 (контекст экосистемы) — в концепт-репо
• C2 + C3 (контейнер + дерево модулей) — в компоненте
• C4 = тот самый системный use case «как работает программа»
📄 Живой пример: https://github.com/codemonstersteam/pinout-openapi/blob/main/docs/design/contract-validate/c4.md
Главный инсайт — это всё прошивается в систему
Получилась сквозная трассировка:
use case (Cockburn)
→ вертикальный слайс
→ компонентный тест
→ узлы графа контрактов.
1 слайс = 1 внешний вход = 1 use case.
Ничего не выдумывается из кода — каждый компонентный тест выводится из соответствующего extension use case, с двусторонней сверкой (нет extension без теста и нет теста без extension).
Как мы доработали скиллы разработки
По следам сессии внесли правки прямо в процедуры скиллов (не в «когда-нибудь потом»):
✅ documentation — обязательные C4-диаграммы по уровням, системный use case как C4-уровень, таблица сбоев в README, gate:
документация только по скиллу (никакой свободной прозы мимо процедур)
✅ program-design — C4 по уровням, модель ошибок (коды → exit, «деградация видна, не маскируется под успех»), трассировка
UC→слайс→тест, conformance-gate (STOP перед хендоффом)
✅ component-tests — режимы отказа берутся из extensions use case
✅ роль plan-reviewer — асимметричная проверка соответствия дизайна скиллу
Плюс зашили несколько жёстких правил в скилл проектирования:
• Один внешний вход = один Request. Все параметры (включая флаги CLI) собираются в единый Request; флаг — это поле Request, а не
отдельный аргумент или «прокинутый сбоку» io.Writer. Внешний ввод парсится только в адаптере.
• Развилки по флагам — это юниты, а не компонентные тесты. Выбор «куда писать» (--out) и «в каком формате» (--format)
оформляется чистой функцией (resolveDestination, renderReport) и покрывается юнит-тестами. В компонентные сценарии идёт только
режим отказа записи — иначе матрица stdout/файл × json/md раздувает число сценариев.
• Запрет «тестового» второго метода I/O (WriteTo(io.Writer) рядом с боевым Write) — решение выносится в логику, лишний шов не
заводится.
Вывод сессии: use case по Коберну + C4 + вертикальные слайсы — это один связный конвейер, а не три отдельные практики. Когда они
сшиты, дизайн перестаёт расходиться с тестами и кодом by design.
#codemonstersvlog #разработка #архитектура #C4 #UseCase #OpenAPI
🔌 pinout: спроектировали валидатор OpenAPI-контрактов и попутно прокачали свои скиллы разработки
На этой сессии проектировали инструмент, который на pre-merge стадии в CI проверяет, что потребитель REST-сервиса совместим с
прод-контрактом поставщика — сравнением их OpenAPI-спек. Без генерации клиентских либ, без подъёма заглушек: чистая функция
«спека vs спека».
🔗 Экосистема: https://github.com/codemonstersteam/pinout
🔗 Сам валидатор: https://github.com/codemonstersteam/pinout-openapi
Что зацепило больше всего
📐 Системные use case по Коберну.
Оказалось, что fully-dressed use case (акторы, предусловия, основной сценарий, extensions =
режимы отказа, гарантии/exit) — это не «бумажка для галочки», а рабочая спецификация. Структура use case изоморфна Gherkin: Main
Success → happy-тест, каждый Extension → один сценарий отказа. Формула сошлась сама собой: N сценариев = 1 + число extensions.
🗺 C4 как уровни дизайна. Разложили проект по уровням C4 на Mermaid (рендерится прямо в GitHub):
• C1 (контекст экосистемы) — в концепт-репо
• C2 + C3 (контейнер + дерево модулей) — в компоненте
• C4 = тот самый системный use case «как работает программа»
📄 Живой пример: https://github.com/codemonstersteam/pinout-openapi/blob/main/docs/design/contract-validate/c4.md
Главный инсайт — это всё прошивается в систему
Получилась сквозная трассировка:
use case (Cockburn)
→ вертикальный слайс
→ компонентный тест
→ узлы графа контрактов.
1 слайс = 1 внешний вход = 1 use case.
Ничего не выдумывается из кода — каждый компонентный тест выводится из соответствующего extension use case, с двусторонней сверкой (нет extension без теста и нет теста без extension).
Как мы доработали скиллы разработки
По следам сессии внесли правки прямо в процедуры скиллов (не в «когда-нибудь потом»):
✅ documentation — обязательные C4-диаграммы по уровням, системный use case как C4-уровень, таблица сбоев в README, gate:
документация только по скиллу (никакой свободной прозы мимо процедур)
✅ program-design — C4 по уровням, модель ошибок (коды → exit, «деградация видна, не маскируется под успех»), трассировка
UC→слайс→тест, conformance-gate (STOP перед хендоффом)
✅ component-tests — режимы отказа берутся из extensions use case
✅ роль plan-reviewer — асимметричная проверка соответствия дизайна скиллу
Плюс зашили несколько жёстких правил в скилл проектирования:
• Один внешний вход = один Request. Все параметры (включая флаги CLI) собираются в единый Request; флаг — это поле Request, а не
отдельный аргумент или «прокинутый сбоку» io.Writer. Внешний ввод парсится только в адаптере.
• Развилки по флагам — это юниты, а не компонентные тесты. Выбор «куда писать» (--out) и «в каком формате» (--format)
оформляется чистой функцией (resolveDestination, renderReport) и покрывается юнит-тестами. В компонентные сценарии идёт только
режим отказа записи — иначе матрица stdout/файл × json/md раздувает число сценариев.
• Запрет «тестового» второго метода I/O (WriteTo(io.Writer) рядом с боевым Write) — решение выносится в логику, лишний шов не
заводится.
Вывод сессии: use case по Коберну + C4 + вертикальные слайсы — это один связный конвейер, а не три отдельные практики. Когда они
сшиты, дизайн перестаёт расходиться с тестами и кодом by design.
#codemonstersvlog #разработка #архитектура #C4 #UseCase #OpenAPI