От валидации к контрактам: перешел с Zod на SafeShape
Почему SafeShape? Потому что мне нужна проверка совместимости API между релизами вместе с валидацией данных.
Сервер сделал поле name необязательным. Новый ответ проходит новую схему, но старый клиент всё ещё вызывает name.toUpperCase(). Проверки ответа по новой схеме здесь недостаточно — нужно сравнить гарантии двух версий.
Для моих задач SafeShape предоставляет готовые инструменты для этого процесса:
- Проверка изменений в CI. Сохраняю снимок контракта и сравниваю с новой версией. Ужесточение запросов, ослабление гарантий ответа и изменения маршрутов или статусов попадают в отчёт.
- Описание API и проверяемый клиент. Объявляю endpoint, схемы запроса и ответов. Из этого описания получаю OpenAPI 3.1 и fetch-клиент с проверкой данных до отправки и после получения.
- MCP в версии 3.5.1. Coding-агент может изучать зарегистрированные контракты, проверять JSON и сравнивать схемы. Для собственных MCP-инструментов проверяются аргументы до исполнения и результат до успешного ответа.
Zod тоже поддерживает вывод типов, преобразования и экспорт JSON Schema. Преимущество SafeShape для меня — готовый процесс работы с контрактами: снимки, направленная совместимость, API-клиент и MCP поставляются вместе.
При использовании Zod такой процесс нужно собирать из дополнительных инструментов и кода приложения.
Проверка совместимости не доказывает сохранение бизнес-логики. Но она помогает обнаружить изменения данных, которые способны сломать клиента, ещё до релиза.
