Contrats et compatibilité
Un contrat décrit la structure promise par une opération d'API. Echo réunit sa méthode, son chemin, son document et ses versions publiées. Un mock peut générer des données à partir du contrat et une application peut se lier à une version pour déclarer sa dépendance. Publier un contrat ne déploie ni ne teste une API en cours d'exécution.
Créer et publier
Ouvrez Contrats dans Maestro, créez le contrat et ouvrez Publier une version. Collez un document de contrat Echo et vérifiez-le avant de publier. Ce champ attend le JSON d'un document Echo, pas une réponse d'exemple ni un JSON Schema non converti. La conversion des schémas est disponible dans l'éditeur de routes de mocks.
Les versions publiées sont des instantanés numérotés. La liaison d'une application enregistre la version convenue. Le diff web montre les chemins modifiés, les raisons et des verdicts distincts pour les consommateurs et les fournisseurs. Réutiliser un contenu déjà publié peut renvoyer une ancienne version existante au lieu d'en créer une autre.
Lire dans le bon sens
La liaison Consumes indique que l'application appelle l'opération. Provides indique qu'elle la fournit. La comparaison distingue les changements de requête et de réponse et évalue chaque côté.
| Changement | Consommateur | Fournisseur |
|---|---|---|
| Ajouter un champ facultatif à la requête | Sûr | Sûr |
| Ajouter un champ obligatoire à la requête | Incompatible | Incompatible |
| Ajouter un champ obligatoire à la réponse | Sûr | Incompatible |
| Supprimer un champ de réponse ou changer son type | Incompatible | Incompatible |
| Ajouter un champ facultatif à la réponse | Conditionnel | Sûr |
Ce sont les verdicts du classificateur actuel. Un champ facultatif supplémentaire dans la réponse est conditionnel, car JsonUnmappedMemberHandling.Disallow refuse les champs inconnus. Lisez la condition et sa raison dans le diff. Safe signifie qu'aucune incompatibilité n'a été détectée de ce côté ; Warning demande une vérification ; Breaking signale une incompatibilité ; ConditionalBreaking dépend de la condition indiquée. Un verdict inconnu ne vaut pas approbation.
Vérifier avant d'accepter
Un fournisseur peut publier avec EchoContractPublicationClient, dans Gapfy.Echo.Contracts. Créez d'abord le contrat et la liaison Provides, puis utilisez une clé avec PublishOwnedContracts. Le client publie une version d'un contrat appartenant à l'application ; il ne crée pas de contrat et n'en prend pas la propriété.
La publication est terminée avant le retour des résultats de compatibilité. Un verdict incompatible ne l'annule pas. Vérifiez les différences avant de modifier un consommateur ou d'accepter une nouvelle référence.
Gapfy.Echo.Testing compare les contrats consommés à des instantanés vérifiés dans votre dépôt. Il peut faire échouer la CI lorsqu'un changement casse ce consommateur. Il ne teste pas l'API en cours d'exécution et ne valide pas les contrats fournis par votre application.
Étapes suivantes
Reliez votre application avec applications et clés, ou utilisez le document pour servir des mocks distants.