Одинаковый 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 для поиска несовместимости инструментария обычно не нужны.