Как забытая версия контракта уронила прод и почему мы собрали Dependency Validator
Продакшн иногда падает не из‑за сложной архитектуры или редкого race condition, а из‑за вещи, которую легко упустить в спешке. У нас так и случилось: во время хотфикса разработчик обновил библиотеку с контрактами только в одном из двух сервисов. Во втором сервисе в зависимостях осталась предыдущая версия пакета. До слияния всё выглядело "здорово": сборка проходила, тесты были зелёными. Но после деплоя второй сервис начал отвечать 500 - на сервере не оказалось нового поля в структуре запроса, которое уже ожидали клиенты. Пришлось срочно откатываться, и даунтайм получился вполне ощутимым.
Первой реакцией было желание закрыть дыру процессом: добавить пункт в предрелизный чек‑лист или в очередной раз напомнить команде следить за версиями. Но хотфиксы тем и опасны, что делаются в условиях дефицита времени: чек‑лист не заполняют, а напоминания живут максимум пару недель. Поэтому логичнее оказалось переложить ответственность на CI: пусть рутина выполняется автоматически и одинаково строго каждый раз. Так и родился Dependency Validator - небольшой инструмент, который контролирует актуальность критичных пакетов.
Почему именно контракты - зона риска
Во многих микросервисных системах контракты живут отдельно: модели запросов/ответов, gRPC-прото, схемы событий, сгенерированные клиенты. Подключаются они как обычная зависимость - отдельным пакетом или модулем. Когда контракты релизятся, сервисы должны подтянуть обновление. Проблема в том, что никто не гарантирует соответствие "версии в репозитории контрактов" и "версии в конкретном сервисе". И если отставание иногда допустимо, то для внутренних библиотек, которые меняются синхронно с API, это прямой путь к ошибкам в рантайме.
Важно, что мы не пытались построить очередной универсальный бот для обновлений и не собирались заменять Dependabot. Цель была другой: взять несколько ключевых репозиториев (контракты + пара внутренних библиотек) и сделать так, чтобы на пути к продакшну сервис не мог "случайно забыть" обновление.
Требования: строго там, где нужно, и мягко в черновиках
Я сформулировал несколько принципов, которые должны были сделать инструмент полезным, а не раздражающим:
- список проверяемых репозиториев задаётся конфигурацией;
- должны поддерживаться закрытые репозитории (без этого в корпоративной среде инструмент бесполезен);
- проверка должна работать с проектами на разных языках;
- перед вливанием в master устаревшая зависимость обязана блокировать пайплайн;
- во всех остальных merge request'ах проверка лишь сообщает о несоответствии и не ломает работу.
Последний пункт критичен. Если сделать стоп‑кран на каждом черновом MR, команда очень быстро начнёт воспринимать проверку как шум. Логика получилась простой: чем ближе изменения к продакшну, тем строже политика.
Почему "спарсим зависимости сами" - плохая идея
Первая версия выглядела очевидно: найти файл зависимостей и распарсить его. В планах были go.mod, package.json, requirements.txt, pyproject.toml, Cargo.toml, packages.config, *.csproj, Gemfile... Но уже через пару итераций стало ясно: я пытаюсь написать универсальный менеджер пакетов - причём заведомо неполноценный.
В одном языке версии задаются точно, в другом диапазонами; где-то истина в lock‑файле, где-то версия окончательно определяется только после резолва; есть транзитивные зависимости, замены модулей, условия по платформам и окружению. Каждый новый язык означал бы ещё один парсер, ещё десяток исключений и бесконечные edge case'ы. Для нормального управления зависимостями такой путь не масштабируется.
SBOM как единый формат для разных языков
Выход нашёлся там, где уже давно думают про безопасность цепочки поставок: SBOM (Software Bill of Materials). Это машиночитаемое описание состава приложения - какие компоненты попали в сборку, какие у них версии и как они связаны. То есть SBOM сразу решает главную боль: даёт единый "язык" для проектов на Go, Python, Node.js, .NET и других экосистем, не заставляя валидатор понимать нюансы каждого менеджера пакетов.
Дальше задача превращается в понятный анализ зависимостей: берём SBOM, находим в нём интересующие нас пакеты, сверяем их версии с последними релизами целевых репозиториев и выдаём результат в нужном режиме - предупреждение или блокировка.
В результате Dependency Validator стал работать как целевой сканер зависимостей, заточенный не под всё дерево пакетов, а под небольшой список "особо опасных" внутренних библиотек - тех самых, которые могут внезапно уронить прод несовместимостью контрактов.
Кстати, сам подход и сценарии, из которых выросла эта утилита, хорошо иллюстрирует практика проверки зависимостей в CI перед релизом - когда автоматизация закрывает человеческий фактор именно там, где цена ошибки максимальна.
Закрытые репозитории и доступы: без этого инструмент не взлетит
Отдельная инженерная часть - работа с приватными репозиториями. В реальном контуре контракты и внутренние библиотеки редко лежат в публичном доступе, а значит, валидатор должен уметь аутентифицироваться: токены, права только на чтение, ограничение по scope, аккуратная работа с секретами в CI. В противном случае проверка либо будет падать, либо потребует "широких" прав, которые небезопасны.
Здесь Dependency Validator хорошо ложится в набор DevSecOps инструменты: он не только про удобство разработки, но и про снижение операционных рисков - меньше аварий, меньше ручных действий в критический момент, понятнее контроль изменений.
Как сделать блокирующую проверку только перед master
Практика показала, что правильнее разделять режимы. Для feature-веток и ранних MR достаточно комментария в логах и подсказки: "контракты отстают, перед мержем обнови". А вот для веток, которые реально ведут в релиз (например, при слиянии в master/main), проверка должна быть строгой: нашёл отставание - пайплайн красный.
Так проверка зависимостей перестаёт быть "полицейским на каждом шагу" и становится предохранителем на финальном рубеже.
Что валидатор принципиально не делает
Важно очертить границы ответственности. Dependency Validator не пытается:
- обновлять пакеты автоматически;
- решать конфликты версий и собирать проект "как получится";
- заменять системы мониторинга уязвимостей или полноценные SCA-решения;
- контролировать вообще все зависимости - только те, что команда пометила как критичные.
Именно поэтому он остаётся простым и надёжным: меньше магии, меньше неожиданных побочных эффектов.
Что получилось в итоге - и почему это реально снижает риск
На выходе мы получили инструмент, который сравнивает фактические версии критичных библиотек (через SBOM) с актуальными релизами и включает нужную строгость в зависимости от контекста. Он закрывает ту самую дыру, из‑за которой мы однажды ловили 500 в проде: "в одном сервисе обновили, в другом забыли".
Хороший ориентир для внедрения - рассматривать валидатор как часть дисциплины управления зависимостями критичных внутренних пакетов: не пытаться охватить всё, а выбрать действительно опасные точки и сделать контроль неизбежным.
Несколько практических дополнений (то, что стоит предусмотреть заранее)
Во‑первых, полезно договориться о правилах релиза контрактов: семантическое версионирование, заметные release notes и явная политика совместимости. Тогда валидатор не просто "ругается", а становится частью понятного процесса.
Во‑вторых, имеет смысл добавить исключения: иногда сервис сознательно остаётся на предыдущей версии контрактов (например, миграция идёт поэтапно). Для таких случаев лучше предусмотреть явный allowlist/override в конфиге с ограничением по времени, чтобы "временное" не превратилось в "навсегда".
В‑третьих, метрики тоже важны. Если собирать статистику - сколько раз валидатор остановил слияние, какие пакеты чаще всего забывают обновлять, сколько времени проходит между релизом контрактов и их подтягиванием сервисами - можно улучшать процесс точечно, а не "в целом по больнице".
В‑четвёртых, SBOM стоит генерировать одинаково во всех сервисах (единый инструмент/шаблон CI). Тогда результаты сравнения будут стабильными, а анализ зависимостей - воспроизводимым и понятным при расследованиях.
И наконец, хороший следующий шаг - аккуратно расширять список проверяемых репозиториев, но только после того, как команда привыкнет к сигналам и не будет воспринимать их как шум. Тогда Dependency Validator останется полезным предохранителем, а не ещё одной формальностью в пайплайне.