Присутствие полей Protocol Buffers: отличайте установку нуля от сохранения поля без изменений

Что это такое

Заметка Protocol Buffers о присутствии полей различает неявное и явное присутствие. При неявном присутствии скалярные поля со значениями по умолчанию не содержат такого же явного признака установки, а документированное поведение слияния пропускает значения по умолчанию. Явное присутствие может представить поле, намеренно установленное в значение по умолчанию. Это важно, когда сообщение одновременно служит запросом частичного обновления. Protocol Buffers field presence

Почему это важно

Агент может трактовать ноль как «не обновлять» и случайно лишить клиента возможности обнулить счётчик или отключить настройку. Другая реализация может перезаписать существующее значение значением по умолчанию лишь потому, что поле было пропущено. Определяйте намерение обновления отдельно от самого скалярного значения.

Как применять

• Для каждого обновляемого поля запишите смысл отсутствия, присутствия со значением не по умолчанию и присутствия со значением по умолчанию. Явно включите семантику очистки или сброса.
• Выберите представление схемы, выражающее эти состояния, например явное присутствие там, где оно поддерживается, или документированную маску обновления. Не считайте, что один только сгенерированный геттер показывает, было ли передано значение.
• Проследите запрос через каждого посредника и каждую операцию слияния. Проверьте, не отбрасывает ли более старый участник или преобразование сериализации информацию о присутствии, требуемую контрактом обновления.
• Предложите тестовые примеры, начинающиеся с сохранённого значения не по умолчанию: пропустить поле, задать другое значение не по умолчанию и явно задать значение по умолчанию. Проверяйте различающиеся результаты там, где этого требует контракт.
• Повторите тестовые примеры через реально используемый публичный транспортный интерфейс и сгенерированный API языка. Документируйте синтаксис или редакцию и версии сред выполнения, задействованные на этом пути.

Подводные камни

Совместимость на уровне передачи не обеспечивает сохранение намерения обновления приложения. Повторяющиеся поля, отображения и поля сообщений имеют собственное поведение присутствия, и к ним не следует механически применять правила скаляров. Маску обновления также нужно проверять на соответствие фактической схеме запроса. Эта статья предлагает контракт частичного обновления и план проверки; о выполненном тесте взаимодействия разных версий не заявляется.