Compatibilité inverse

Qu'est-ce que la rétrocompatibilité

Compatibilité inverse (compatibilité backward) : Propriété du système pour recevoir et traiter correctement les anciens clients/consommateurs lorsque le système est mis à jour. Plus simple : vous publiez une nouvelle version du service/événement, et les intégrations existantes continuent de fonctionner sans changement.

La clé est de ne pas briser les arrangements. Toute évolution est par l'ajout, pas par la refonte de ce qui a déjà été publié.

Principes de base

1. Additive-first

Les nouveaux champs/méthodes/événements sont ajoutés en option. Rien n'est supprimé ou ne change le sens.

2. Contrat minimum de garantie (MGC)

Définissez un noyau - un ensemble de champs/opérations sans lesquels le script perd son sens. Le noyau est stable. Tout le reste est des extensions.

3. Tolerant reader

Les clients ignorent les champs inconnus et traitent correctement les nouvelles valeurs enum (fallback).

4. Stratégie de version

Les modifications brisantes ne passent que par la ligne principale ('/v2 ',' payments '. v2`, `event. v2`). Les mineurs sont additifs.

5. Observabilité - partie du contrat

Les logs/trails et les métriques montrent la version du client, le format, les drapeaux capability. Cela permet de gérer la migration.

Sécurité vs changements dangereux

Généralement sans danger (BC-OK)

Ajoute des champs facultatifs (JSON/Avro/Protobuf 'optional '/' nullable').
Ajoutez de nouveaux endpoints/méthodes/événements.
Extension enum avec des valeurs supplémentaires (avec tolérant reader).
Atténuation de la validation (augmentation des maxima, ajout de formats alternatifs).
Ajouter des titres/métadonnées qui n'affectent pas le sens.

Dangereux (Breaking)

Supprimer/renommer les champs, modifier le type ou l'obligation des champs existants.
Changer la sémantique des statuts/codes d'erreur.
Réutilisation des étiquettes protobuf sous d'autres champs.
Changer la clé de lot de l'événement (brise l'ordre de l'agrégat).
Le durcissement du SLA/Timout, ce qui fait que les anciens clients commencent à tomber.

Par style d'interaction

REST/HTTP + JSON

Additivité : les nouveaux champs sont 'optional', le serveur ne les exige pas des anciens clients.
Versions : major - en transit ('/v2 ') ou médiatipe ; minor par les extensions et '? include = '/' ? fields ='.
Erreurs : format unique ; ne pas changer les codes/sémantique sans majeur.
ETag/If-Match : pour des mises à jour sécurisées sans course.
Idempotence : 'Idempotency-Key' pour POST - les anciens clients ne « doublent » pas l'effet sur les retraits.

gRPC / Protobuf

Les balises sont inchangées. Les balises supprimées ne sont pas réutilisées.
Les nouveaux champs sont « optional »/« repeated » ; les valeurs par défaut sont traitées correctement par l'ancien code.
Streaming : ne pas changer l'ordre/l'obligation des messages au sein du mineur.
Les erreurs sont un ensemble stable d'états ; nouvelle sémantique → nouvelle méthode/service ('.v2').

Event-driven (Kafka/NATS/Pulsar) + Avro/JSON/Proto

Nom : 'domain. action. v{major}`.
Core vs Enriched : le noyau est stable ; les enrichissements sont des types/thèmes distincts ('.enriched').
Mode de compatibilité des schémas : plus souvent BACKWARD ; CI bloque les modifications incompatibles.
Lot : clé (par exemple, 'payment _ id') fait partie du contrat ; le changer est un breaking.

GraphQL

Ajout de champs/types - OK ; Supprimer/renommer via '@ deprecated' et la fenêtre de migration.
Ne pas augmenter « nul → non nul » sans majeur.
Contrôler complexity/depth - modifier les limites = modifier le contrat.

Modèles qui aident à préserver la BC

Modèle de pyramide inverse : stabilisez le noyau, étendez-le en option.
Negotiation capability : le client signale les capacités prises en charge (« X-Capabilities »/handshake), le serveur s'adapte.
Dual-run/dual-emit : pendant la durée de la migration, tenez simultanément 'v1' et 'v2'.
Adaptateurs : proxy/gateway traduit les requêtes 'v1↔v2' pour les clients « lourds ».
Expand-and-contract (pour OBD) : d'abord ajouter un nouveau, commencer à écrire/lire, seulement ensuite supprimer l'ancien.

Gouvernance et processus

1. Catalogue des contrats (registre des schémas) : source unique de vérité avec les politiques d'interopérabilité.
2. Linters et chèques diff dans CI/CD : OpenAPI-bou, Buf-breaking, test de compatibilité Avro/JSON Schema.
3. CDC/Contrats Consommateurs-Driven : le fournisseur est testé pour les contrats consommateurs réels.
4. Samples d'or : demandes de référence/réponses/événements pour la régression.
5. Gestion du changement : RFC/ADR sur le breaking, plans sunset, communication.

Deprecate et retrait des anciennes versions

Marquez l'obsolète ('@ deprecated', descriptions, en-têtes 'Deprecation', 'Sunset').
Fenêtre de migration : date annoncée à l'avance, banc d'essai, exemples de code.
Télémétrie d'utilisation : qui d'autre sur « v1 » ? segmentez les métriques/logs par version.
Dual-run à zéro trafic, puis - suppression.

Observabilité et métriques opérationnelles

Pourcentage de demandes/messages par version.
Proportion d'erreurs/de délais chez les anciens clients après la sortie.
Proportion de payload incompatibles (validation par le circuit sur la passerelle/filtres stream).
Lag de la migration des consommateurs (combien d'autres « v1 » écoutent).

Tests de rétrocompatibilité

Schema-diff: fail при remove/rename/type-change.
Tests contractuels : les anciens SDK/clients courent contre la nouvelle implémentation.
E2E-canaris : partie de l'ancien trafic sur la nouvelle version, comparaison p95/p99, codes, retraits.
Replay des événements : les projections sont rassemblées par une nouvelle logique de l'ancienne loge sans divergence.
Fault-injection : retards/réponses partielles - les anciens clients ne tombent pas.

Exemples

REST (additif)

json
{ "id": "p1", "status": "authorized" }

json
{ "id": "p1", "status": "authorized", "risk_score": 0. 12 }

Les anciens clients, en ignorant 'risk _ score', continuent de fonctionner.

Protobuf (balises)

proto message Payment {
string id = 1;
string status = 2;
optional double risk_score = 3 ;//new field, safe
}
//Tags 1 and 2 cannot be changed/deleted without v2

Événements (noyau + enrichissement)

`payment. authorized. v1 'est le noyau (minimum de faits).
`payment. enriched. v1 '- détails ; les consommateurs du noyau ne dépendent pas de l'enrichissement.

Anti-modèles

Swagger-wash : mis à jour le schéma, mais le service se comporte de manière ancienne (ou inversement).
Tranches cachées : ont changé le sens du champ/statut sans version.
L'utilisation excessive des étiquettes protobuf : la corruption « silencieuse » des données.
Clients durs : tombent sur des champs/enum inconnus ; pas de lecteur tolérant.
Mega-endpoint : un tout-en-un - tout changement devient une rupture potentielle.

Chèque avant la sortie

• Les modifications sont additives ; le noyau (MGC) n'est pas touché.
• Les chèques linters/diff sont passés ; Il n'y a pas de drapeaux breaking.
• Les SDK clients ont été mis à jour (ou ne sont pas requis pour l'extension additive).
• Inclus dans le lecteur tolérant chez les clients ; enum-fallback vérifié.
• Les métriques/logs contiennent la version et les drapeaux capability.
• Pour une tranche potentielle, il y a '/v2 ', dual-run et sunset plan.
• Documentation/exemples mis à jour, il y a des kits golden.

FAQ

Backward vs forward - quelle est la différence ?
Backward - Les nouveaux serveurs fonctionnent avec les anciens clients. Forward - les nouveaux clients fonctionnent correctement avec les anciens serveurs (grâce à un lecteur tolérant et à des défauts soignés). Le cercle complet est entièrement compatible.

Dois-je toujours faire '/v2 'pour les grands changements ?
Oui, si les invariants/types/clés/sémantique sont cassés. Sinon, gardez la ligne et évoluez de manière additive.

Qu'en est-il de l'enum ?
Ajoutez de nouvelles valeurs sans changer le sens des anciennes. Les clients doivent avoir un fallback à une valeur inconnue.

Et s'ils étaient déjà cassés ?
Retour arrière, adaptateur hot-fix, sortie 'v2' avec double exécution, communication et hyde de migration.

Résultat

La rétrocompatibilité est une discipline de l'évolution : stabilisez le noyau, étendez-le de manière additive, introduisez un lecteur tolérant, automatisez les vérifications et conduisez un déprécat éclairé. De cette façon, vous serez en mesure de développer rapidement la plate-forme sans laisser les clients sous les décombres des changements « non visibles ».