Одинаковый proto-файл не гарантирует одинаковый результат сборки: на него влияют генератор, языковой плагин и библиотека runtime. Если после генерации появились отсутствующие методы или несовместимые типы, сначала сохраните точные версии всей связки. Безопасный первый тест — генерация из того же исходника в чистом тестовом окружении, без подмешивания прежних сгенерированных файлов.

Не редактируйте сгенерированный код вручную ради успешной компиляции. Такая правка исчезнет при следующем запуске и скроет реальный контракт сборки. Ожидаемый результат проверки — воспроизводимая генерация и сборка на зафиксированных инструментах. Совместимость сообщений между сервисами проверяется отдельно: успешная компиляция её не доказывает.

Зафиксируйте не один номер версии

КомпонентЧто сохранитьГде возникает расхождение
Исходная схемаРевизию и импортируемые файлыРазные зависимости proto
protocВерсию реально вызванного бинарникаЛокальный PATH и CI
Языковой плагинВерсию и параметрыДругой выходной API
RuntimeФактически разрешённую зависимостьТранзитивное понижение версии

Официальная гарантия Protobuf предупреждает, что новый сгенерированный код не поддерживается старым runtime; детали совместимости различаются по языкам. Проверено 15 октября 2026 года. Поэтому не переносите правила одного языка на другой и не выбирайте любую «почти такую же» версию. Сверяйте конкретную языковую гарантию и зависимости gRPC-плагина.

Чистая сборка отделяет инструмент от остатка прошлой генерации

Условный паспорт генерации:
proto_revision: <исходная схема>
imports_revision: <зависимости>
protoc_version: <реальный генератор>
plugin_version: <языковой плагин>
runtime_version: <разрешённая библиотека>
output_location: <один согласованный каталог>

Проверьте, не компилируются ли две копии одного типа из разных каталогов. Один проект может брать свежие исходники, а другой — старый пакет с теми же именами. Сравните фактические входы компилятора и граф зависимостей. Удалять произвольные рабочие каталоги для эксперимента не требуется: создайте отдельный чистый тестовый выпуск.

Если локально всё проходит, а CI падает, сравните реальные версии, а не только конфигурационный файл. Сборщик мог подтянуть другую транзитивную зависимость или использовать кеш старого плагина. Зафиксированная связка инструментов и зависимостей должна применяться в обоих местах. Отдельно проверьте параметры генерации и пакетные пространства имён.

Не путайте ошибку типов языка с несовместимым изменением wire-схемы. Первую воспроизводят генерацией и компиляцией. Вторую — обменом тестовыми сообщениями между поддерживаемыми версиями клиента и сервера. Исправление одного уровня не освобождает от проверки другого, особенно при совместной работе старых и новых сервисов.

Приёмка сравнивает поддерживаемые комбинации

  • Чистая генерация даёт ожидаемый набор типов.
  • Runtime соответствует документированной гарантии языка.
  • Локальная сборка и CI используют одну связку.
  • Повтор генерации не создаёт дублирующие определения.
  • Поддерживаемые клиент и сервер обмениваются искусственным сообщением.

При откате возвращайте согласованную связку, а не один случайный пакет. Если новый runtime уже используется другим компонентом, оцените его зависимости отдельно. Для первичного разбора подготовьте минимальную искусственную схему, паспорт генерации и первую ошибку компиляции. Рабочие сообщения и полное содержимое закрытых API для поиска несовместимости инструментария обычно не нужны.

Проверенные источники