Presença de campo no Protocol Buffers: como distinguir definir zero de deixar um campo inalterado

O que é

A documentação do Protocol Buffers sobre presença de campo distingue presença implícita e presença explícita. Na presença implícita, os campos escalares com valor padrão não carregam o mesmo estado explícito de "definido", e, segundo o comportamento de merge documentado, esses valores padrão são ignorados. A presença explícita consegue representar um campo que foi definido de propósito com o valor padrão. Isso importa quando uma mensagem serve também como requisição de atualização parcial. Protocol Buffers field presence

Por que importa

Um agente pode interpretar zero como "sem atualização" e, com isso, impedir sem querer que um cliente zere um contador ou desative uma configuração. Outra implementação pode sobrescrever um valor existente com o padrão apenas porque o campo foi omitido. Defina a intenção da atualização separadamente do valor escalar em si.

Como aplicar

• Para cada campo de atualização, escreva o significado de três casos: ausente, presente com valor não padrão e presente com o valor padrão. Inclua explicitamente a semântica de limpar (clear) ou redefinir (reset).
• Escolha uma representação de esquema que expresse esses estados, como presença explícita onde houver suporte ou uma máscara de atualização documentada. Não presuma que o getter gerado, sozinho, revele se um valor foi informado.
• Acompanhe a requisição por todos os intermediários e operações de merge. Verifique se um participante mais antigo ou uma conversão de serialização não descarta informação de presença exigida pelo contrato de atualização.
• Proponha fixtures que partam de um valor armazenado não padrão: omitir o campo, definir outro valor não padrão e definir explicitamente o valor padrão. Verifique resultados distintos onde o contrato os exigir.
• Repita as fixtures pelo transporte público real e pela API gerada da linguagem. Documente a sintaxe ou edition e as versões de runtime envolvidas nesse caminho.

Armadilhas

A compatibilidade no nível do wire não garante que a intenção de atualização da aplicação seja preservada. Campos repetidos (repeated), mapas e campos de mensagem têm comportamento de presença próprio e não devem herdar mecanicamente as regras dos escalares. Uma máscara de atualização também precisa ser validada contra o esquema real da requisição. Este artigo propõe um contrato de atualização parcial e um plano de verificação; não afirma ter executado nenhum teste de interoperabilidade entre versões mistas.