Dans le monde dynamique des microservices, tout peut changer : n'importe quel composant peut être réécrit dans un langage différent, en utilisant des frameworks et une architecture différents. Seuls les contrats doivent rester inchangés afin que le microservice puisse interagir de l'extérieur de manière permanente, quelles que soient les métamorphoses internes. Et aujourd'hui, nous parlerons de notre problème de choix d'un format pour décrire les contrats et partagerons les artefacts que nous avons trouvés.
Post préparé и
Microservices. Lors du développement d’Acronis Cyber Cloud, nous avons réalisé que nous ne pouvions pas y échapper. Et concevoir un microservice est impossible sans formaliser le contrat, qui représente l’interface du microservice.
Mais lorsqu'un produit contient plusieurs composants et que le développement de contrats devient une activité régulière, vous ne pouvez pas vous empêcher de commencer à penser à l'optimisation des processus. Il devient évident que l'interface (contrat) et l'implémentation (microservice) doivent correspondre, que les différents composants doivent faire les mêmes choses de la même manière, et que sans une prise de décision centralisée de toutes ces décisions, chaque équipe sera obligée de passez du temps encore et encore pour les obtenir.
Diagramme des microservices Amazon de Werner Vogelis, directeur technique d'Amazon
Quel est le dilemme ? De facto, il existe deux manières d'interagir avec les microservices : HTTP Rest et gRPC de Google. Ne voulant pas nous laisser entraîner par la pile technologique de Google, nous avons choisi HTTP Rest. Les annotations des contrats HTTP REST sont le plus souvent décrites dans l'un des deux formats suivants : RAML et OAS, anciennement connus sous le nom de Swagger. Par conséquent, chaque équipe de développement est confrontée à la nécessité de choisir l'un des standards. Mais il s’avère que faire ce choix peut s’avérer très difficile.
Pourquoi les annotations sont-elles nécessaires ?
L'annotation est nécessaire pour qu'un utilisateur externe puisse facilement comprendre ce qui peut être fait avec votre service via son interface HTTP. Autrement dit, au niveau de base, l'annotation doit contenir au moins une liste des ressources disponibles, leurs méthodes HTTP, les corps des requêtes, une liste de paramètres, une indication des en-têtes requis et pris en charge, ainsi que des codes de retour et des formats de réponse. Un élément extrêmement important de l'annotation du contrat est leur description verbale (« que se passera-t-il si vous ajoutez ce paramètre de requête à la demande ? », « Dans quel cas le code 400 sera-t-il renvoyé ? »)
Cependant, lorsqu’il s’agit de développer un grand nombre de microservices, vous souhaitez extraire une valeur supplémentaire des annotations écrites. Par exemple, sur la base de RAML/Swagger, vous pouvez générer du code client et serveur dans un grand nombre de langages de programmation. Vous pouvez également recevoir automatiquement la documentation du microservice et la télécharger sur votre portail de développeur :).
Exemple de description de contrat structurée
La pratique consistant à tester des microservices sur la base de descriptions de contrats est moins courante. Si vous avez écrit à la fois une annotation et un composant, vous pouvez alors créer un autotest qui vérifie l'adéquation du service avec différents types de données d'entrée. Le service renvoie-t-il un code de réponse qui n'est pas décrit dans l'annotation ? Sera-t-il capable de traiter correctement des données manifestement incorrectes ?
De plus, une mise en œuvre de haute qualité non seulement des contrats eux-mêmes, mais également des outils de visualisation des annotations permet de simplifier le travail avec le microservice. Autrement dit, si l'architecte a décrit le contrat de manière qualitative, sur cette base, les concepteurs et les développeurs mettront en œuvre le service dans d'autres produits sans coûts de temps supplémentaires.
Pour activer des outils supplémentaires, RAML et OAS ont la possibilité d'ajouter des métadonnées non prévues par la norme ().
En général, les possibilités de créativité dans l'utilisation des contrats pour les microservices sont énormes... du moins en théorie.
Comparaison d'un hérisson avec un serpent
Actuellement, le domaine de développement prioritaire chez Acronis est le développement de la cyber-plateforme Acronis. Acronis Cyber Platform, c'est de nouveaux points d'intégration de services tiers avec Acronis Cyber Cloud et la partie agent. Même si nous étions satisfaits de nos API internes décrites dans RAML, la nécessité de publier l'API a de nouveau soulevé la question du choix : quelle norme d'annotation est la meilleure à utiliser pour notre travail ?
Au départ, il semblait y avoir deux solutions : les développements les plus courants étaient RAML et Swagger (ou OAS). Mais en fait, il s'est avéré qu'il n'y avait au moins pas 2 alternatives, mais 3 ou plus.
D'une part, il y a RAML, un langage puissant et efficace. Il implémente bien la hiérarchie et l'héritage, ce format est donc plus adapté aux grandes entreprises qui ont besoin de beaucoup de descriptions - c'est-à-dire non pas un produit, mais de nombreux microservices qui ont des parties communes de contrats - des schémas d'authentification, les mêmes types de données, des corps d'erreur. .
Mais le développeur de RAML, Mulesoft, a rejoint le consortium Open API, qui développe . RAML a donc suspendu son développement. Pour imaginer le format de l'événement, imaginez que les mainteneurs des principaux composants Linux partent travailler chez Microsoft. Cette situation crée les conditions préalables à l'utilisation de Swagger, qui se développe de manière dynamique et dans la dernière version - la troisième - rattrape pratiquement RAML en termes de flexibilité et de fonctionnalité.
Sinon pour une chose mais...
Il s'avère que tous les utilitaires open source n'ont pas été mis à jour vers OAS 3.0. Pour les microservices en Go, le plus critique sera le manque d'adaptation pour la dernière version de la norme. Cependant, la différence entre Swagger 2 et Swagger 3 est . Par exemple, dans la troisième version, les développeurs :
- description améliorée des schémas d'authentification
- Prise en charge du schéma JSON
- mise à niveau de la possibilité d'ajouter des exemples
La situation est amusante : lors du choix d'un standard, vous devez considérer RAML, Swagger 2 et Swagger 3 comme des alternatives distinctes. Cependant, seul Swagger 2 prend en charge les outils OpenSource. RAML est très flexible... et complexe, et Swagger 3 est mal pris en charge par la communauté, vous devrez donc utiliser des outils propriétaires ou des solutions commerciales, qui ont tendance à être assez coûteuses.
De plus, s'il existe de nombreuses fonctionnalités intéressantes dans Swagger, comme un portail prêt à l'emploi , sur lequel vous pouvez télécharger une annotation et obtenir sa visualisation avec une description détaillée, des liens et des connexions, alors pour le RAML plus fondamental et moins convivial, une telle opportunité n'existe pas. Oui, vous pouvez rechercher quelque chose parmi les projets sur GitHub, y trouver un analogue et le déployer vous-même. Cependant, dans tous les cas, quelqu'un devra entretenir le portail, ce qui n'est pas si pratique pour une utilisation de base ou pour les besoins de test. De plus, le swagger est plus «sans principes» ou plus libéral - il peut être généré à partir de commentaires dans le code, ce qui, bien sûr, va à l'encontre du premier principe de l'API et n'est pris en charge par aucun des utilitaires RAML.
À un moment donné, nous avons commencé à travailler avec RAML comme langage plus flexible et, par conséquent, nous avons dû faire beaucoup de choses nous-mêmes. Par exemple, l'un des projets utilise l'utilitaire dans les tests unitaires, qui ne prennent en charge que RAML 0.8. Nous avons donc dû ajouter des béquilles pour que l'utilitaire puisse « manger » RAML version 1.0.
Faut-il choisir ?
Après avoir travaillé à compléter l'écosystème de solutions pour RAML, nous sommes arrivés à la conclusion que nous devons convertir RAML en Swagger 2 et y effectuer toute l'automatisation, la vérification, les tests et l'optimisation ultérieure. C'est un bon moyen de tirer parti à la fois de la flexibilité de RAML et de la prise en charge des outils communautaires de Swagger.
Pour résoudre ce problème, il existe deux outils OpenSource qui devraient permettre la conversion des contrats :
- est un utilitaire actuellement non pris en charge. En travaillant avec lui, nous avons découvert qu'il rencontrait un certain nombre de problèmes avec les RAML complexes qui sont « réparties » sur un grand nombre de fichiers. Ce programme est écrit en JavaScript et effectue une traversée récursive d'un arbre syntaxique. En raison du typage dynamique, il devient difficile de comprendre ce code, nous avons donc décidé de ne pas perdre de temps à écrire des correctifs pour un utilitaire en voie de disparition.
- - un outil de la même entreprise qui prétend être prêt à convertir tout et n'importe quoi, et dans n'importe quelle direction. À ce jour, la prise en charge de RAML 0.8, RAML 1.0 et Swagger 2.0 a été annoncée. Cependant, au moment de nos recherches, l'utilitaire était encore humide et inutilisable. Les développeurs créent une sorte de , leur permettant d'ajouter rapidement de nouvelles normes à l'avenir. Mais jusqu’à présent, cela ne fonctionne tout simplement pas.
Et ce ne sont pas toutes les difficultés que nous avons rencontrées. L'une des étapes de notre pipeline consiste à vérifier que le RAML du référentiel est correct par rapport à la spécification. Nous avons essayé plusieurs utilitaires. Étonnamment, ils ont tous injurié nos annotations à différents endroits et avec des gros mots complètement différents. Et pas toujours au point :).
En fin de compte, nous avons opté pour un projet désormais obsolète, qui présente également un certain nombre de problèmes (parfois il plante à l'improviste, a des problèmes lors du travail avec des expressions régulières). Ainsi, nous n'avons pas trouvé de moyen de résoudre les problèmes de validation et de conversion en nous basant sur des outils gratuits, et avons décidé d'utiliser un utilitaire commercial. À l’avenir, à mesure que les outils OpenSource gagneront en maturité, ce problème pourrait devenir plus facile à résoudre. Entre-temps, les coûts de main d'œuvre et de temps pour la « finition » nous semblaient plus importants que le coût d'une prestation commerciale.
Conclusion
Après tout cela, nous avons souhaité partager notre expérience et constater qu'avant de choisir un outil de description des contrats, il faut définir clairement ce que l'on en attend et quel budget on est prêt à investir. Si l'on oublie l'OpenSource, il existe déjà un grand nombre de services et de produits qui vous aideront à vérifier, convertir et valider. Mais ils sont chers, et parfois très chers. Pour une grande entreprise, ces coûts sont tolérables, mais pour une startup, ils peuvent devenir un fardeau important.
Déterminez l’ensemble d’outils que vous utiliserez plus tard. Par exemple, si vous avez juste besoin d'afficher un contrat, il sera plus facile d'utiliser Swagger 2, qui possède une belle API, car dans RAML, vous devrez créer et maintenir le service vous-même.
Plus vous avez de tâches, plus le besoin en outils sera large, et ils sont différents selon les plateformes, et il est préférable de se familiariser immédiatement avec les versions disponibles afin de faire un choix qui minimise vos coûts à l'avenir.
Mais il convient de reconnaître que tous les écosystèmes qui existent aujourd’hui sont imparfaits. Par conséquent, s'il y a des fans dans l'entreprise qui aiment travailler dans RAML parce que « cela permet d'exprimer ses pensées avec plus de flexibilité » ou, au contraire, préfèrent Swagger parce que « c'est plus clair », il est préférable de les laisser travailler. dans ce qu'ils sont Ils y sont habitués et le veulent, car les outils de n'importe quel format nécessitent une modification avec un fichier.
Quant à notre expérience, dans les articles suivants, nous parlerons des contrôles statiques et dynamiques que nous effectuons sur la base de notre architecture RAML-Swagger, ainsi que de la documentation que nous générons à partir des contrats et de la manière dont tout cela fonctionne.
Seuls les utilisateurs enregistrés peuvent participer à l'enquête. s'il te plait.
Quel langage utilisez-vous pour annoter les contrats de microservices ?
-
RAML 0.8
-
RAML 1.0
-
fanfaron 2
-
OAS3 (alias)
-
Plan
-
Autre
-
N'utilise pas
100 utilisateurs ont voté. 24 utilisateurs se sont abstenus.
Source: habr.com