API
OpenAPI: сделай контракт несущим
Читать про contract drift — не то же самое, что построить пайплайн, который делает его невозможным. Возьми небольшой API, сделай его OpenAPI spec энфорснутым источником истины, затем попробуй смёржить breaking change и посмотри, как сборка тебя останавливает — с доказательством на каждом шаге.
Преврати модель юнита в работающий пайплайн: OpenAPI 3.1 spec, который генерирует типизированный клиент, валидирует запросы на краю и роняет CI на diff с breaking change — так что контракт не может дрейфовать или сломаться молча.
Возьми небольшой HTTP API (свой или сервис заказов на 3 эндпоинта) и сделай его OpenAPI 3.1 spec энфорснутым источником истины: сгенерируй типизированный клиент, валидируй запросы на краю и гейти breaking changes в CI — затем докажи, что breaking change блокируется до merge.
- Лог CI до/после: ломающий PR падает с oasdiff, называющим конкретное правило breaking (например api-required-request-property-added), а совместимый PR проходит.
- Сгенерированный клиент компилируется с точными типами — без any/unknown для полей, которые spec определяет — доказывая, что схемы достаточно тугие для честного codegen.
- Битый запрос к валидируемому эндпоинту возвращает 400 с именем нарушающего поля, зафиксированный как реальный ответ, а не описанный.
- Абзац-описание: выбор spec-first vs code-first и почему, и какие слои enforcement (codegen, валидация на краю, diff-gate) защищают от какого сбоя.
- Добавь mock-сервер, сгенерированный из примеров spec, и покажи, как потребитель интегрируется с ним до того, как появится серверный хендлер.
- Расширь gate oasdiff, чтобы постить сводку изменённых эндпоинтов как комментарий к PR, так что ревьюеры видят дельту контракта инлайн.
- Мигрируй nullability одной схемы с 3.0 на 3.1 (nullable: true в type-массив) и покажи, что diff классифицирует это корректно; подтверди, что генератор поддерживает 3.1.
- Добавь contract-тесты, гоняющие сгенерированный клиент против реального сервера в CI, ловя drift, который статический diff spec не может (например хендлер, игнорирующий задокументированное поле).
Это пайплайн, который ты строишь для любого API, потребляемого больше чем одной командой: тугой OpenAPI 3.1 spec как источник истины, сгенерированный клиент, убивающий баги с ручной сборкой запроса, валидация на краю, точно отклоняющая битый ввод, и diff на breaking changes в CI, роняющий PR до того, как сломается клиент. Сделав это однажды на сервисе из трёх эндпоинтов, ты делаешь production-версию — где пятничный деплой никогда не доходит до мобильных клиентов, которые ты не можешь форс-обновить — паттерном, которым уже владеешь.