Как спроектировать backward compatible gRPC API при изменении схемы?

Проектирование gRPC API с сохранением backward compatibility

• gRPC API описывается с помощью Protocol Buffers (proto)
• Не удаляйте существующие поля — добавляйте новые, назначая им уникальные номера
• для расширения схемы применяйте optional и repeated поля
• не допускайте несовместимой смены типов, например преобразования int в string
• расширяйте API добавлением новых методов либо созданием версий сервисов, например v1 и v2
• не меняйте поведение, на которое рассчитывают старые клиенты, чтобы не нарушить их логику
• проверяйте совместимость с помощью integration tests, запуская клиентов разных версий

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

Подробный ответ

Основной ответ

Проектирование backward compatible gRPC API необходимо для развития сервиса без сбоев у клиентов, работающих со старыми версиями. Основой такого подхода служит аккуратное управление protobuf-схемой и соблюдение правил совместимости при её изменении.

Ключевые моменты

• Не удаляйте и не переиспользуйте номера полей в protobuf-сообщениях. Если поле больше не нужно, вместо удаления его следует пометить как deprecated = true. Это помогает избежать конфликтов при десериализации на стороне старых клиентов.
• Новые поля добавляйте только с уникальными номерами и задавайте значения по умолчанию, чтобы клиенты старых версий могли без ошибок игнорировать незнакомые поля.
• Нельзя менять типы и порядок полей, поскольку это нарушает бинарный формат. Допустимо добавлять новые сервисные методы, но сигнатуры уже существующих менять нельзя.
• При расширении enum-типов не удаляйте имеющиеся значения: добавляйте новые, чтобы исключить их ошибочную интерпретацию.
• При архитектурных изменениях, нарушающих совместимость, используйте versioning API через новые методы или сервисы.
• Соблюдайте правила protobuf: например, не используйте required поля, а применяйте только optional и repeated. Поля required жёстко нарушают backward compatibility.
• Проверяйте backward compatibility с помощью специальных инструментов, например grpc-proto-compatibility-checker, чтобы заранее выявлять нарушения.

Практический контекст

В реальных проектах, включая микросервисные архитектуры на базе gRPC и Protobuf 3+, такой подход помогает разрабатывать сервисы с минимальным временем простоя и даёт клиентам возможность постепенно перейти на новую версию API. Изменения также следует документировать и доводить до сведения команд, чтобы управление версиями оставалось прозрачным.