Revisão de API Protobuf e gRPC

Revise .proto e as alterações gRPC relacionadas como contratos de longa duração. Distinga o que o formato de transmissão permite do que clientes gerados, usuários JSON, dados armazenados e implantações de versão mista podem tolerar com segurança.

Comece com o Envelope de Compatibilidade

Antes de decidir se uma alteração é segura, determine:

• o esquema antigo e o novo, não apenas o arquivo final
• se os payloads usam protobuf binário, ProtoJSON, formato de texto ou mais de um encoding
• se as mensagens persistem em bancos de dados, filas, logs, caches ou eventos
• se existem clientes fora do repositório ou que são lançados independentemente
• a sintaxe ou edição do protobuf e as linguagens/versões de runtime geradas
• se a transcodificação HTTP/JSON, reflexão, configuração de serviço ou registradores de esquema expõem o contrato
• a ordem de implantação, janela de rollback e duração da operação de versão mista

Se o contexto estiver faltando, declare a suposição e diminua a confiança. Não chame uma alteração de retrocompatível apenas a partir do novo esquema.

Fluxo de Revisão

1. Inventário de Alterações de Contrato

Compare as definições antigas e novas por símbolo totalmente qualificado. Registre:

• campos de mensagem: número, nome, tipo, cardinalidade, presença, oneof, padrões e opções relevantes
• enums: nome do valor, número, aliases, reservas e valor zero
• serviços: pacote, serviço, método, tipos de requisição e resposta, e modo de streaming
• entradas de API geradas: opções de pacote, nomes de classes externas, namespaces e opções personalizadas

Ignore alterações apenas de formatação após confirmar que elas não alteram descritores ou APIs geradas.

2. Avalie Quatro Dimensões de Compatibilidade

Avalie cada símbolo afetado independentemente:

1. Transmissão binária — leitores antigos e novos podem analisar bytes antigos e novos sem corrupção ou perda?
2. Formatos nomeados — consumidores ProtoJSON, formato de texto, transcodificados REST ou baseados em nome ainda funcionam?
3. API de origem e gerada — clientes regenerados compilarão e preservarão a presença, enum e comportamento do acessador?
4. Comportamento e operações — códigos de status, segurança de retentativa, prazos, autorização, streaming e limites de recursos preservam o contrato RPC?

Leia as regras de compatibilidade do protobuf para alterações de campo, enum, presença, oneof e serialização. Leia a revisão de contrato gRPC quando serviços, métodos ou comportamento de runtime mudarem.

3. Rastreie Cenários de Versão Mista

Para cada alteração não trivial, raciocine através destes caminhos:

• escritor antigo -> leitor novo
• escritor novo -> leitor antigo
• leitor antigo modifica e reserializa uma mensagem nova
• rollback após escritores novos terem emitido valores novos
• dados antigos persistidos lidos após a migração

Para alterações condicionalmente compatíveis, identifique a restrição exata do escritor e o ponto em que ela pode ser relaxada. Um rollout seguro comumente requer a implantação de leitores antes de escritores e a retenção do campo ou método antigo até que o rollback não seja mais necessário.

4. Revise Evidências do Repositório

Use as ferramentas do próprio repositório quando disponíveis:

• compile descritores com o protoc do projeto, Buf, Gradle, Maven, Bazel ou tarefa específica da linguagem
• execute verificações de quebra de alteração ou lint configuradas
• inspecione diffs de código gerado apenas quando eles forem commitados por convenção do repositório
• pesquise sites de chamada para switches de enum exaustivos, suposições de presença, nomes de campos JSON, caminhos de método, tratamento de status e configuração de retentativa
• procure por fixtures de compatibilidade ou linhas de base de descritor antes de propor um novo mecanismo

Não afirme que uma verificação passou a menos que você a tenha executado. Se uma ferramenta ou linha de base necessária estiver indisponível, nomeie o risco não verificado.

5. Produza uma Revisão Acionável

Comece com um veredito:

• Compatível — seguro dentro do envelope de compatibilidade declarado
• Dependente de Rollout — analisável, mas seguro apenas com sequenciamento explícito ou restrições de valor
• Quebra — causa incompatibilidade de transmissão, formato nomeado, origem ou comportamento
• Contexto Insuficiente — o esquema antigo, encoding, consumidores ou modelo de implantação são desconhecidos

Em seguida, forneça apenas descobertas baseadas em evidências. Para cada descoberta, inclua:

[severity] Short title
Location: file and symbol or changed lines
Dimension: binary | JSON/text | source | behavior/operations
Change: old contract -> new contract
Impact: concrete failing mixed-version scenario
Remediation: smallest safe schema change or staged migration