Les attentes du consommateur, y compris l’authentification et la structure des erreurs, sont vérifiées contre le fournisseur réel en CI avant la fusion ; les codes de statut HTTP ne peuvent pas être simulés des deux côtés du contrat.
Statut du package : contexte de référence prêt pour revue humaine. Le contrat et les scénarios de test sont complets, mais aucune affirmation n’est faite qu’une implémentation adoptante les ait validés.
Décision
Les interfaces de service sont régies par des contrats pilotés par le consommateur : le consommateur publie les requêtes qu’il enverra et les réponses qu’il exige, y compris les en-têtes d’authentification et les corps d’erreur. La CI du fournisseur vérifie ces attentes contre le fournisseur en fonctionnement avant qu’un changement incompatible puisse être fusionné. Les tests qui remplacent les codes de statut par des mocks toujours à 200 ne sont pas des tests de contrat.
Portée
- Paires consommateur-fournisseur HTTP ou message, publication de contrat, vérification fournisseur en CI, et classification des changements incompatibles versus additionnels.
- Présence des en-têtes d’authentification/autorisation, forme des objets d’erreur, et payloads de succès.
- Services backend qui évoluent indépendamment.
Hors de ce bloc
- Parcours produit complets de bout en bout et tests de snapshot UI.
- Évolution des schémas d’événements pour les topics asynchrones, qui a ses propres règles de compatibilité.
Contrat
- Chaque contrat consommateur nomme le fournisseur, l’opération, les en-têtes de requête requis, et les codes de statut autorisés incluant au moins un code d’erreur documenté.
- La vérification fournisseur échoue la fusion si un champ requis disparaît, si la signification d’un code de statut change, ou si un code d’erreur est renommé.
- Les schémas d’authentification utilisés en production (par exemple les tokens d’accès bearer) apparaissent dans le contrat comme en-têtes ou claims requis, pas omis uniquement sur le chemin heureux.
- Les réponses d’erreur conservent un
codemachine stable et une classe de statut HTTP convenue dans le contrat. - Les champs de réponse optionnels additionnels sont compatibles ; la suppression ou le changement de type d’un champ consommé est incompatible.
- Les tests de contrat s’exécutent contre le processus fournisseur ou une fixture fournisseur enregistrée qui retourne toujours de vrais codes de statut, jamais un stub qui mappe tous les échecs en 200.
Implémentation
- Publier les contrats depuis les tests consommateur comme artefacts que la pipeline fournisseur récupère lors des changements de handler, sérialiseur ou auth.
- Inclure les opérations non autorisées et non trouvées dans la suite consommateur par défaut.
Gestion des échecs
- Si le fournisseur ne peut pas démarrer, la pipeline échoue plutôt que d’ignorer les contrats.
- Les changements incompatibles incrémentent la version de l’API et migrent les consommateurs ; ils n’affaiblissent pas l’ancien contrat en place.
Vérification
- Supprimer un champ consommé sur une branche et vérifier que la CI fournisseur échoue.
- Rejouer des requêtes non autorisées et attendre le corps 401 ou 403 contracté.
Les exemples à l’apparence exécutable dans ce package sont des fixtures et contrats d’acceptation. Lancez
python tools/validate.py depuis la racine de la collection pour vérifier la structure et les métadonnées du package ; puis
implémentez et exécutez les scénarios dans le dépôt cible.
Hypothèses d’adoption
- Les noms et valeurs numériques dans
example.yamlsont un profil d’adoption, pas des valeurs par défaut universelles. - L’équipe adoptante doit mapper acteurs, classes de données, vocabulaire d’erreur et propriété à son système.
Références
- Les contrats pilotés par le consommateur sont décrits par Fowler à https://martinfowler.com/articles/consumerDrivenContracts.html.
- Les descriptions d’interface HTTP peuvent suivre OpenAPI 3.1 ; ce bloc ne requiert pas un fournisseur de broker spécifique.