Que peut-on faire avec les annotations des contrats de microservices?

Dans le dernier article, nous avons expliqué comment et pourquoi nous, chez Ancronis, faisons des annotations pour les microservices, et nous avons promis de partager notre pratique consistant à utiliser un seul format d'API pour l'ensemble de la plateforme Acronis Cyber. Aujourd'hui, nous parlerons de notre expérience des vérifications d'annotations statiques - alias la première étape sur la voie de l'introduction d'annotations dans une entreprise.



Supposons donc que vous ayez déjà des annotations pour toutes ou la plupart des API. Une question raisonnable que nos collègues nous ont également posée: "Que faire de ces objets magiques?"

En fait, il existe deux types de contrôles qui peuvent être effectués directement par annotation. Les vérifications statiques vont directement aux textes des annotations Swagger ou RAML. Ils n'ont besoin de rien d'autre et peuvent à juste titre être considérés comme le premier avantage de l'utilisation de contrats de microservices formalisés.

Les contrôles dynamiques ne peuvent être démarrés que si vous disposez d'un service opérationnel. Ils sont un peu plus compliqués, car ils vous permettent d'approfondir et de vérifier la validité de l'annotation, de tester la stabilité du service et de faire beaucoup plus. Mais c'est le sujet du prochain article, et aujourd'hui nous nous concentrerons sur la statique.

Vive la directive API!

Afin de ne pas confondre vous-même ou les autres, il convient de mentionner tout de suite que des contrôles d'annotations statiques sont créés pour contrôler la conformité des annotations API (et, espérons-le, les API elles-mêmes) avec les exigences de l'entreprise. Il peut s'agir soit uniquement des pratiques adoptées par l'entreprise, soit d'une API Guideline à part entière, qui formalise les règles de préparation de l'API pour vos services.



Lorsque nous parlons du monde coloré des microservices, c'est très important, car chaque équipe peut avoir son propre cadre, son propre langage de programmation, une pile unique ou certaines bibliothèques spéciales. Sous l'influence des pratiques spécifiques au microservice, la présentation de l'API pour un observateur externe évolue. Cela crée une variété inutile. Pour une interaction efficace des éléments d'un écosystème (ou plate-forme), il est nécessaire «d'aligner» l'API autant que possible.

Voici un exemple: le code 404 est renvoyé à l'API d'un composant uniquement si la ressource n'existe pas. Et l'autre équipe lie cette erreur à la logique d'application et l'API renvoie 404 lorsque l'utilisateur souhaite acheter un produit qui s'est terminé dans l'entrepôt. Atygaev a décrit très clairement ces problèmes ici . Cette incohérence dans la compréhension du code 404 ralentira le développement et entraînera des erreurs, ce qui signifie des appels inutiles à l'assistance ou des heures supplémentaires de débogage, mais en tout cas, des problèmes mesurés en termes monétaires.

Les spécificités de syntaxe et de dénomination adoptées par l'entreprise sont complétées par divers aspects spécifiques à REST lui-même. Le développeur doit répondre à des questions telles que:

• POST sera-t-il idempotent ou non?
• Quels codes d'erreur utilisons-nous et que signifient-ils?
• Puis-je ajouter une logique métier aux codes d'erreur?

Imaginez maintenant que chaque équipe doit individuellement réfléchir à ces réponses.

Le format de la requête de recherche peut également être complètement différent. Par exemple, il existe une douzaine de façons de créer un exemple dans lequel seuls les utilisateurs qui ont MacBookPro et des attaques de virus fréquentes seront répertoriés. Lorsque vous travaillez sur un grand projet composé de dizaines de microservices, il est nécessaire que la syntaxe de la requête de recherche soit commune à toutes les versions et produits de l'entreprise. Et si une personne a l'habitude de se référer à l'un des produits / services de votre développement, elle s'attend à trouver la même structure de demande et de réponse dans une autre. Sinon, l'étonnement (et le chagrin) ne seront pas évités.

De nombreuses entreprises, en particulier des géants, tels que Microsoft , PayPal , Google , ont leurs propres directives et elles sont très bien pensées. Mais l'utilisation des directives des autres n'est pas toujours possible, car elles sont largement liées aux spécificités de l'entreprise. De plus, la pensée de chacun a une structure différente, et les règles peuvent différer simplement parce qu'il est plus pratique pour les gens de travailler de cette façon et non autrement.

La compréhension qu'Acronis a besoin de sa propre directive API n'est pas venue immédiatement, mais avec le nombre croissant de développeurs, de microservices et en fait de clients externes et d'intégrations. À un moment donné, l'équipe d'architectes a dû établir des règles uniformes pour déclarer l'API, en tenant compte à la fois de l'expérience des géants informatiques mentionnés ci-dessus et des pratiques de facto déjà établies dans les équipes de développement.

L'un des problèmes de cette implémentation tardive de l'API Guideline est que les API publiées existantes ne répondent pas aux exigences, ce qui entraîne à son tour des coûts supplémentaires pour la refonte des interfaces et le maintien de la compatibilité descendante. Par conséquent, si votre modèle d'entreprise implique une intégration et une publication futures de l'API, vous devez penser à des règles uniformes le plus tôt possible.



Bien sûr, l'adoption des API Guideline n'a pas automatiquement rendu toutes les API constitutives. Chaque API devait être analysée, chaque devlid devait comprendre les nouvelles exigences. Par conséquent, nous avons automatisé les vérifications RAML par rapport à l'API Guideline que nous avons développée.
Analyse statique

Vous devez d'abord décider ce que nous analyserons statiquement. Tous les points de l'API Guideline ne peuvent pas être formalisés, vous devez donc d'abord mettre en évidence un ensemble de règles qui peuvent être facilement comprises à partir de l'annotation API.

Dans la première version, nous avons identifié les règles suivantes:

1. Vérifiez les descriptions des API. Comme nous l'avons dit dans notre article précédent, vous pouvez créer une belle documentation basée sur l'annotation API. Cela signifie que chaque ressource, paramètre de requête et réponse doit avoir une description qui fournira toutes les informations nécessaires à tout utilisateur de notre API. Cela semblerait insignifiant, mais comme il est facile de montrer aux développeurs que leur annotation n'est pas riche en descriptions!
2. Vérification de la présence et de l'exactitude des exemples. Les langages d'annotation d'API vous permettent également de décrire des exemples. Par exemple, en réponse, nous pouvons ajouter un exemple de véritable réponse de service, quelque chose de la vie réelle. L'utilisation d'exemples indique comment le point de terminaison doit être utilisé et fonctionne, et nous vérifions les exemples par l'analyse statique des annotations.
3. Validation des codes de réponse HTTP. La norme HTTP définit un grand nombre de codes, mais ils peuvent être interprétés de différentes manières. Notre ligne directrice formalise l'utilisation des codes. Nous limitons également l'applicabilité de différents codes selon la méthode HTTP. Par exemple, le code 201, selon la spécification HTTP, est renvoyé lorsqu'une ressource est créée. Par conséquent, le GET renvoyant 201 sera un réveil (soit le code est utilisé de manière incorrecte, soit GET crée la ressource). Par conséquent, notre API Guideline interdit une telle utilisation. De plus, les architectes ont fixé des ensembles de codes pour chaque méthode, et maintenant nous les vérifions en mode statique au niveau des annotations.
4. Vérification des méthodes HTTP. Tout le monde sait que le protocole HTTP dispose d'un ensemble de méthodes standard (GET, POST, PUT, etc.), et permet également d'utiliser des méthodes personnalisées. Notre API Guideline décrit les méthodes autorisées qui sont autorisées mais indésirables (OPTIONS), ainsi que complètement interdites (ne peuvent être utilisées qu'avec la bénédiction des architectes). Interdit: la méthode HEAD standard, ainsi que toutes les méthodes personnalisées. Tout cela est également facile à vérifier dans les annotations des contrats.
5. Vérification des droits d'accès. Nous espérons qu'en 2019, la nécessité d'un support d'autorisation ne nécessitera pas d'explications supplémentaires. Une bonne documentation doit inclure des informations sur les rôles pris en charge par l'API et les méthodes d'API disponibles pour chaque rôle. En plus de documenter des informations sur le modèle de rôle, enregistrées au niveau de l'annotation, vous permet de faire des choses beaucoup plus intéressantes en dynamique, cependant, nous en parlerons dans le prochain article.
6. Validation de la dénomination. Soulage les maux de tête liés à l'utilisation de différentes approches pour nommer les entités. En général, il y a deux «camps» - partisans de CamelCase et snake_case.Camelcase - lorsque chaque mot commence par une majuscule et snake_case - lorsque les mots sont séparés par des traits de soulignement et que tout est écrit en petites lettres. Dans différentes langues, il est d'usage de donner des noms de différentes manières. Par exemple, snake_case est accepté en Python et CamelCase est adopté en Go ou Java. Nous avons rendu notre propre choix universel pour tous les projets et fixé dans la directive API. Par conséquent, à travers des annotations, nous vérifions statiquement les noms des ressources et des paramètres;
7. Validation des en-têtes personnalisés. Ceci est un autre exemple de vérification de dénomination, mais il est lié spécifiquement aux têtes. Chez Acronis, il est habituel d'utiliser le format du formulaire X-Custom-Header-Name (malgré le fait que ce format soit déconseillé). Et nous contrôlons sa conformité au niveau des annotations.
8. Vérifiez la prise en charge HTTPS. Tout service moderne devrait prendre en charge HTTPS, et certains pensent que travailler avec HTTP de nos jours est généralement une mauvaise nouvelle. Par conséquent, l'annotation RAML ou Swagger doit être indiquée. que le microservice prend en charge HTTPS sans HTTP.
9. Vérifiez la structure de l'URI. À l'époque préhistorique, c'est-à-dire avant la publication de l'API Guideline, l'URI de la demande était différent dans les différents services: quelque part / api / 2, quelque part / api / nom_service / v2, etc. Maintenant, dans notre guide, une structure d'URI standard est définie pour toutes nos API. Le manuel décrit à quoi ils doivent ressembler afin de ne pas créer de confusion.
10. Vérification de la compatibilité des nouvelles versions. Un autre facteur que tout auteur d'API doit garder à l'esprit est la compatibilité descendante. Il est important de vérifier si le code construit sur la base de l'ancienne API peut fonctionner avec la nouvelle version. Sur la base de ce changement, on peut diviser en deux catégories: rompre la compatibilité descendante et compatible. Tout le monde sait que les changements de rupture sont inacceptables, et si vous voulez "améliorer" considérablement quelque chose, le développeur devrait publier une nouvelle version de l'API. Mais tout le monde peut se tromper, donc notre autre objectif au stade des vérifications statiques est d'ignorer uniquement les modifications compatibles et de jurer sur les incompatibles. Il est supposé que l'annotation, comme le code, est stockée dans le référentiel et, par conséquent, elle a l'historique complet des modifications. Par conséquent, nous pouvons vérifier notre compatibilité HTTP REST. Par exemple, l'ajout de la compatibilité (méthode, paramètre, code de réponse) ne viole pas et la suppression peut très bien entraîner une perte de compatibilité. Et cela peut déjà être vérifié au niveau de l'annotation.

Quand il n'y a pas de descriptions

Quand il y a des descriptions

Conclusions

Une analyse statique des annotations est nécessaire afin de vérifier (non, pas la qualité de service), mais la qualité de l'API. Cette étape vous permet d'aligner les interfaces du programme les unes avec les autres afin que les gens travaillent dans un environnement clair et compréhensible où tout est assez prévisible.

Bien sûr, il n'est nécessaire de traiter ce formalisme que dans des entreprises suffisamment grandes, lorsque la vérification «manuelle» de toutes les correspondances est très longue, coûteuse et peu fiable. Une petite startup n'en a tout simplement pas besoin. Du moins pour le moment. Mais si dans votre avenir il est prévu de devenir une licorne, comme Akronis, alors les contrôles statiques et l'API Guideline vous aideront.