Revue de l'API Protobuf et gRPC

Examinez les modifications .proto et gRPC connexes comme des contrats durables. Distinguez ce que le format de transmission permet de ce que les clients générés, les utilisateurs JSON, les données persistantes et les déploiements multi-versions peuvent tolérer en toute sécurité.

Commencez par l'Enveloppe de Compatibilité

Avant de décider si une modification est sûre, déterminez :

les anciens et nouveaux schémas, pas seulement le fichier final
si les payloads utilisent le protobuf binaire, ProtoJSON, le format texte ou plusieurs encodages
si les messages persistent dans des bases de données, files d'attente, journaux, caches ou événements
s'il existe des clients en dehors du repository ou qui se déploient indépendamment
la syntaxe ou édition protobuf ainsi que les versions des langages générés et des runtimes
si la transcodage HTTP/JSON, la reflection, la config de service ou les registres de schémas exposent le contrat
l'ordre de déploiement, la fenêtre de rollback et la durée d'opération multi-versions

Si le contexte manque, énoncez l'hypothèse et abaissez la confiance. N'appelez pas une modification rétro-compatible en vous basant uniquement sur le nouveau schéma.

Workflow de Revue

1. Inventorier les Changements de Contrat

Comparez les anciennes et nouvelles définitions par symbole entièrement qualifié. Enregistrez :

champs de message : numéro, nom, type, cardinalité, présence, oneof, valeurs par défaut et options pertinentes
énums : nom de valeur, numéro, alias, réservations et valeur zéro
services : package, service, méthode, types de requête et réponse, et mode streaming
entrées API générées : options de package, noms de classes externes, namespaces et options personnalisées

Ignorez les changements de formatage uniquement après avoir confirmé qu'ils ne modifient pas les descripteurs ou les API générées.

2. Évaluer Quatre Dimensions de Compatibilité

Évaluez chaque symbole affecté indépendamment :

Fil binaire — les anciens et nouveaux lecteurs peuvent-ils analyser à la fois les anciens et nouveaux octets sans corruption ni perte ?
Formats nommés — les consommateurs ProtoJSON, format texte, transcodés REST ou basés sur des noms fonctionnent-ils toujours ?
API source et générée — les clients régénérés se compileront-ils et préserveront-ils la présence, l'enum et le comportement des accesseurs ?
Comportement et opérations — les codes de statut, la sécurité des tentatives, les délais, l'autorisation, le streaming et les limites de ressources préservent-ils le contrat RPC ?

Lisez les règles de compatibilité protobuf pour les changements de champ, enum, présence, oneof et sérialisation. Lisez la revue de contrat gRPC lorsque les services, méthodes ou comportements runtime changent.

3. Tracer les Scénarios Multi-Versions

Pour chaque changement non trivial, raisonnez à travers ces chemins :

ancien writer -> nouveau reader
nouveau writer -> ancien reader
ancien reader modifie et resérialise un nouveau message
rollback après que les nouveaux writers ont émis de nouvelles valeurs
anciennes données persistantes lues après la migration

Pour les changements conditionnellement compatibles, identifiez la contrainte exacte du writer et le point auquel elle peut être assouplie. Un déploiement sûr nécessite généralement de déployer les readers avant les writers et de conserver l'ancien champ ou la vieille méthode jusqu'à ce que le rollback ne soit plus nécessaire.

4. Examiner les Preuves du Repository

Utilisez les outils du repository lorsqu'ils sont disponibles :

compilez les descripteurs avec protoc, Buf, Gradle, Maven, Bazel ou la tâche spécifique au langage du projet
exécutez les vérifications configurées de breaking-change ou lint
inspectez les diffs de code généré seulement s'ils sont committés par convention du repository
recherchez les sites d'appel pour les switches enum exhaustifs, les hypothèses de présence, les noms de champs JSON, les chemins de méthode, la gestion des statuts et la configuration des tentatives
cherchez les fixtures de compatibilité ou les baselines de descriptors avant de proposer un nouveau mécanisme

Ne prétendez pas qu'une vérification a réussi que si vous l'avez exécutée. Si un outil requis ou une baseline est indisponible, nommez le risque non vérifié.

5. Produire une Revue Actionnable

Commencez par un verdict :

Compatible — sûr dans l'enveloppe de compatibilité énoncée
Dépendant du déploiement — analysable, mais sûr seulement avec un séquençage ou des contraintes de valeur explicites
Incompatible — provoque une incompatibilité de fil, format nommé, source ou comportement
Contexte insuffisant — l'ancien schéma, l'encodage, les consommateurs ou le modèle de déploiement sont inconnus

Ensuite, fournissez uniquement des conclusions soutenues par des preuves. Pour chaque conclusion, incluez :

[sévérité] Titre court
Localisation : fichier et symbole ou lignes modifiées
Dimension : binaire | JSON/texte | source | comportement/opérations
Changement : ancien contrat -> nouveau contrat
Impact : scénario multi-version qui échouerait concrètement
Remédiation : plus petit changement de schéma sûr ou migration progressif

Utilisez blocker pour la corruption, les données non analysables, la réutilisation de tags ou une rupture de production inévitable ; high pour la perte probable de données cross-version ou le comportement RPC non sûr ; medium pour les risques limités de compatibilité ou d'opérabilité ; et low pour les problèmes de maintenabilité qui ne rompent pas le contrat. N'enflammez pas les préférences de style en conclusions de compatibilité.

Concluez par :

une matrice de compatibilité compacte pour les symboles modifiés
la séquence de déploiement/rollback si une migration est requise
des tests ciblés qui prouveraient les hypothèses restantes

Principes de Sécurité par Défaut

Ne réutilisez jamais un numéro de champ ou d'enum, même après suppression ; réservez les numéros supprimés et généralement les noms.
Traitez les changements de numéro de champ et le déplacement de champs dans un oneof existant comme incompatibles.
Traitez les changements de type et de cardinalité comme des migrations, même si leurs types de fil binaire sont compatibles.
Souvenez-vous que l'ajout d'un champ ou d'une valeur d'enum peut toujours casser le code généré ou les consommateurs exhaustifs.
Examinez ProtoJSON séparément : les noms et le comportement des champs inconnus rendent son enveloppe de compatibilité plus étroite que le protobuf binaire.
Préservez les champs inconnus à travers les chemins de lecture-modification-écriture lorsque la compatibilité avant en dépend.
Préférez l'évolution additive : ajoutez un nouveau champ ou RPC, migrez les readers et writers, dépréciez l'ancien contrat, puis ne le supprimez qu'après la fermeture de la fenêtre de compatibilité.
Ne recommandez jamais des tentatives pour un RPC changeant d'état sans établir l'idempotence ou un mécanisme de dédupliquage.
Exigez des délais client réalistes et un travail server conscient de l'annulation pour les RPC de production.

Éviter les Faux Positifs

N'exigez pas que chaque service utilise le streaming, les tentatives, les vérifications de santé ou la transcodage HTTP.
Ne signalez pas un nouveau champ optionnel comme incompatible simplement parce que les anciens clients l'ignorent.
N'appelez pas un changement de type compatible en fil sûr sans vérifier les plages de valeurs et l'ordre de déploiement.
N'hypothéquez pas qu'un champ renommé est inoffensif lorsque JSON, le format texte, la reflection ou les API de source générée sont des consommateurs.
N'exigez pas de réservations pour les champs qui n'ont jamais été livrés ; demandez l'historique de release lorsque cette distinction a de l'importance.

protobuf-grpc-api-review