Enums em Protocol Buffers: trate valores numéricos desconhecidos conforme o comportamento do runtime

O que é

A documentação do Protocol Buffers descreve o comportamento de enums abertos e fechados e aponta diferenças de implementação entre as bibliotecas das várias linguagens. Um valor numérico desconhecido pode ser mantido como valor do campo, no caso de um enum aberto, ou ser tratado por meio do armazenamento de campos desconhecidos, no caso de um enum fechado. Por isso, a sintaxe ou edition escolhida e o runtime utilizado fazem parte da análise de compatibilidade. Protocol Buffers enum behavior

Por que importa

Um agente de codificação pode gerar um switch exaustivo a partir dos valores nomeados atuais e presumir que produtores futuros não conseguirão enviar nada além deles. Defina o que um consumidor mais antigo deve fazer com um valor que não entende: rejeitá-lo, preservá-lo ao retransmitir a mensagem ou seguir um caminho conservador documentado.

Como aplicar

• Registre a sintaxe ou edition do schema, se o enum é aberto ou fechado e as versões concretas do runtime de cada linguagem usadas por cada participante. Consulte o comportamento específico de cada runtime em vez de supor que todas as APIs geradas são idênticas.
• Defina o comportamento da aplicação para um número desconhecido. Mantenha esse caso separado de um valor padrão conhecido ou de um valor não especificado quando os significados forem diferentes.
• Monte uma mensagem de um schema mais novo que contenha um valor de enum recém-adicionado. Decodifique-a com o consumidor mais antigo e inspecione tanto o estado visível para a aplicação quanto o tratamento de campos desconhecidos.
• Se o consumidor encaminha mensagens, codifique-as de novo e decodifique-as outra vez com a implementação mais nova. Verifique se o valor e a ordem relevante sobrevivem ao caminho exigido.
• Adicione testes explícitos para campos enum repeated e para transformações via JSON, quando ocorrerem no sistema real.

Armadilhas

Desconhecido não significa autorizado nem válido para uma operação específica. Preserve a compatibilidade sem atribuir silenciosamente um significado permissivo aos novos valores. A documentação do protobuf lista desvios específicos de cada runtime, de modo que uma explicação genérica não substitui a matriz real de produtores e consumidores. Este artigo propõe verificações de interoperabilidade e não afirma ter executado nenhum teste entre linguagens, nem garante que todos os dados desconhecidos sobrevivam a qualquer transformação.