API
OpenAPI: тест с выбором ответа
Суть Тест с выбором на синтез по всему юниту OpenAPI — spec-first vs code-first, contract drift, gate на breaking changes, codegen, валидация и сдвиг схем в 3.1.
Высота — путь к senior
НольJuniorMiddleSenior
Ты на senior-высоте — в орбитеШесть вопросов поперёк всего юнита. Каждый — это решение по реальному API: не определение для заучивания, а выбор, где живёт истина и как пайплайн держит её честной.
Цель
Убедись, что связываешь spec-first vs code-first, contract drift, gate на breaking changes, codegen и валидацию на краю в одну историю про enforcement — тот синтез, к которому вёл урок.
Викторина
Completed
У команды есть написанный вручную OpenAPI spec, отрендеренный в красивый docs-портал. Коллега говорит: 'мы защищены от breaking changes.' Чего на самом деле не хватает?
Heads-up Клиенты интегрируются неделями, а не в день твоего деплоя. Опубликованный spec описывает изменение, но не мешает инженеру добавить required-поле и сломать каждого существующего клиента в production.
Heads-up $ref снижает дублирование внутри spec; он никак не обнаруживает несовместимые изменения между версиями spec. Для этого нужен diff на breaking changes.
Heads-up То, как spec рождается, ничего не гейтит. Spec-first так же нуждается в gate oasdiff; иначе проверенное-но-несовместимое изменение мёржится столь же легко.
Викторина
Completed
Твои написанные вручную docs помечают поле как optional, но работающий сервер теперь отклоняет запросы без него. Как это называется и что это предотвращает?
Heads-up Сервер может быть прав; дефект в том, что контракт и код не согласуются. Подгонка сервера под устаревшие docs прячет настоящую проблему — ничто не держит spec и код в синхронизации.
Heads-up Запрос без теперь-required поля падает одинаково на каждом ретрае. Drift — это сбой процесса, а не транзиентный сбой.
Heads-up Новая версия не примиряет spec, который уже лжёт про текущую версию. Сначала нужно, чтобы spec отслеживал сервер; версионирование управляет намеренными изменениями, а не случайным drift.
Викторина
Completed
Публичный API потребляют мобильные приложения, которые ты не можешь форс-обновить, и три внешних партнёра. Какая стратегия enforcement подходит?
Heads-up Code-first docs описывают текущий код, но никогда не сравнивают сегодняшний контракт со вчерашним. Новое required-поле честно задокументируется и всё равно сломает каждого старого клиента. Code-first нормален, но ему нужен тот же diff-gate сверху.
Heads-up Ручной review регулярно пропускает breaking changes — сужение типа или добавление required-поля выглядит безобидно в дифе на 400 строк. oasdiff существует ровно потому, что 'кто-нибудь заметит' не переживает пятничный деплой.
Heads-up Changelog — это вики-страница под другим именем: дрейфует, пишется постфактум и ничего не enforce-ит. Сломавшиеся клиенты сломались бы так же с changelog, который никто не перечитал.
Викторина
Completed
Ты генерируешь TypeScript-клиент из spec, и результат полон any и слабо типизированных объектов. В чём первопричина?
Heads-up Любой соответствующий генератор выдаёт слабый вывод из слабой схемы; это честно, а не баг. Фикс выше по течению — в контракте, а не в инструменте.
Heads-up TypeScript прекрасно выражает эти формы, когда схема тугая. Вывод с any отражает недоспецифицированный контракт, а не предел языка.
Heads-up Качество типов отслеживает тугость схемы, а не направление, в котором spec сгенерирован. Неряшливый code-first spec генерирует столь же неряшливый клиент.
Викторина
Completed
Ты апгрейдишь spec с OpenAPI 3.0 до 3.1. Какое изменение реально и почему оно важно?
Heads-up $ref не изменился и остаётся способом переиспользовать компоненты. Изменения схем в 3.1 про nullability и выравнивание с JSON Schema, а не про ссылки.
Heads-up 3.1 меняет язык схем, а не рантайм. Тебе всё равно нужен validator-middleware на краю, чтобы enforce-ить запросы по spec.
Heads-up Переписывание nullability — конкретное синтаксическое изменение: удалённый 'null' из type-массива даже регистрируется в дифе как изменение типа, а не nullable.
Викторина
Completed
Какое изменение контракта запроса/ответа обратно совместимо и безопасно для выкатки без мажорного бампа версии?
Heads-up Каждый существующий клиент, который его не шлёт, теперь отклоняется. Добавление required-поля — классический breaking change, ровно тот случай, который должен ловить diff-gate.
Heads-up Клиент может читать это поле; его удаление молча ломает потребителей. Удаление полей ответа — breaking.
Heads-up Сужение типа отклоняет ранее валидные значения. Ужесточение существующего поля — breaking, хотя и выглядит как безобидное уточнение.
Итог
Сквозная линия юнита — одна история про enforcement: spec становится контрактом, только когда CI делает его несущим. Spec-first vs code-first решает, где живёт истина и проверяется ли контракт до кода, но ни один не уходит от gate — валидируй запросы на краю, диффь каждый PR через oasdiff, чтобы breaking changes (новое required-поле, удалённое поле ответа, суженный тип) роняли сборку, и скармливай тугие схемы генератору, чтобы codegen давал сильные типы. OpenAPI 3.1 переводит схемы на JSON Schema 2020-12, заменяя nullable на type-массивы. Без enforcement spec дрейфует в фикцию и ломает клиентов.