En el món dinàmic dels microserveis, qualsevol cosa pot canviar: qualsevol component es pot reescriure en un llenguatge diferent, utilitzant diferents marcs i arquitectura. Només els contractes haurien de romandre sense canvis perquè es pugui interactuar amb el microservei des de l'exterior de manera permanent, independentment de les metamorfosis internes. I avui parlarem del nostre problema d'escollir un format per descriure els contractes i compartir els artefactes que hem trobat.
Post preparat и
Microserveis. En desenvolupar Acronis Cyber Cloud, ens vam adonar que no podíem escapar d'ells. I dissenyar un microservei és impossible sense formalitzar el contracte, que representa la interfície del microservei.
Però quan un producte conté més d'un component i el desenvolupament del contracte es converteix en una activitat habitual, no podeu evitar començar a pensar en l'optimització de processos. Es fa evident que la interfície (contracte) i la implementació (microservei) han de coincidir, que diferents components han de fer les mateixes coses de la mateixa manera, i que sense una presa de decisions centralitzada de totes aquestes decisions, cada equip es veurà obligat a passar temps una i altra vegada per aconseguir-los.
Diagrama de microserveis d'Amazon Werner Vogelis, CTO d'Amazon
Quin és el dilema? De fet, hi ha dues maneres d'interactuar amb els microserveis: HTTP Rest i gRPC de Google. No volent quedar atrapats en la pila tecnològica de Google, vam triar HTTP Rest. Les anotacions de contracte HTTP REST es descriuen més sovint en un dels dos formats: RAML i OAS, abans coneguts com Swagger. Per tant, cada equip de desenvolupament s'enfronta a la necessitat de triar un dels estàndards. Però resulta que fer aquesta elecció pot ser molt difícil.
Per què són necessàries les anotacions?
L'anotació és necessària perquè un usuari extern pugui esbrinar fàcilment què es pot fer amb el vostre servei mitjançant la seva interfície HTTP. És a dir, a nivell bàsic, l'anotació ha de contenir almenys una llista de recursos disponibles, els seus mètodes HTTP, cossos de sol·licitud, una llista de paràmetres, una indicació de les capçaleres requerides i admeses, així com codis de retorn i formats de resposta. Un element extremadament important de l'anotació del contracte és la seva descripció verbal ("què passarà si afegiu aquest paràmetre de consulta a la sol·licitud?", "En quin cas es retornarà el codi 400?")
Tanmateix, quan es tracta de desenvolupar un gran nombre de microserveis, voleu extreure valor addicional de les anotacions escrites. Per exemple, basat en RAML/Swagger, podeu generar codi de client i de servidor en un gran nombre de llenguatges de programació. També podeu rebre automàticament la documentació del microservei i penjar-la al vostre portal de desenvolupadors :).
Exemple de descripció de contracte estructurat
Menys habitual és la pràctica de provar microserveis basats en descripcions de contractes. Si heu escrit tant una anotació com un component, podeu crear una prova automàtica que comprove l'adequació del servei amb diversos tipus de dades d'entrada. El servei retorna un codi de resposta que no es descriu a l'anotació? Serà capaç de processar correctament dades evidentment incorrectes?
A més, la implementació d'alta qualitat no només dels mateixos contractes, sinó també de les eines de visualització d'anotacions permet simplificar el treball amb el microservei. És a dir, si l'arquitecte descriu qualitativament el contracte, basant-se en ell, els dissenyadors i desenvolupadors implementaran el servei en altres productes sense costos addicionals de temps.
Per habilitar eines addicionals, tant RAML com OAS tenen la possibilitat d'afegir metadades no previstes per l'estàndard ().
En general, el marge de creativitat en l'ús de contractes per a microserveis és enorme... almenys en teoria.
Comparació d'un eriçó amb una serp
Actualment, l'àrea de desenvolupament prioritària d'Acronis és el desenvolupament de la Plataforma Cibernètica Acronis. Acronis Cyber Platform són nous punts d'integració de serveis de tercers amb Acronis Cyber Cloud i la part d'agent. Tot i que estàvem satisfets amb les nostres API internes descrites a RAML, la necessitat de publicar l'API va tornar a plantejar la qüestió de l'elecció: quin estàndard d'anotació és millor utilitzar per al nostre treball?
Inicialment, semblava que hi havia dues solucions: els desenvolupaments més habituals eren RAML i Swagger (o OAS). Però, de fet, va resultar que almenys no hi ha 2 alternatives, sinó 3 o més.
D'una banda hi ha RAML, un llenguatge potent i eficient. Implementa bé la jerarquia i l'herència, de manera que aquest format és més adequat per a grans empreses que necessiten moltes descripcions, és a dir, no un producte, sinó molts microserveis que tenen parts comunes dels contractes: esquemes d'autenticació, els mateixos tipus de dades, cossos d'error. .
Però el desenvolupador de RAML, Mulesoft, s'ha unit al consorci Open API, que s'està desenvolupant . Per tant, RAML va suspendre el seu desenvolupament. Per imaginar el format de l'esdeveniment, imagineu que els mantenedors dels principals components de Linux van marxar a treballar a Microsoft. Aquesta situació crea els requisits previs per utilitzar Swagger, que s'està desenvolupant de manera dinàmica i en l'última, la tercera versió, pràcticament es posa al dia amb RAML en termes de flexibilitat i funcionalitat.
Si no fos per una cosa...
Com a resultat, no totes les utilitats de codi obert s'han actualitzat a OAS 3.0. Per als microserveis a Go, el més crític serà la manca d'adaptació per a la darrera versió de l'estàndard. Tanmateix, la diferència entre Swagger 2 i Swagger 3 és . Per exemple, a la tercera versió els desenvolupadors:
- descripció millorada dels esquemes d'autenticació
- Suport a l'esquema JSON
- ha millorat la capacitat d'afegir exemples
La situació és divertida: quan escolliu un estàndard, heu de considerar RAML, Swagger 2 i Swagger 3 com a alternatives separades. Tanmateix, només Swagger 2 té un bon suport per a les eines OpenSource. RAML és molt flexible... i complex, i Swagger 3 té poc suport per la comunitat, de manera que haureu d'utilitzar eines propietàries o solucions comercials, que solen ser bastant cares.
A més, si hi ha moltes funcions agradables a Swagger, com ara un portal ja fet , sobre la qual podeu pujar una anotació i obtenir-ne la visualització amb una descripció detallada, enllaços i connexions, aleshores per al RAML més fonamental i menys amigable no hi ha aquesta oportunitat. Sí, podeu cercar alguna cosa entre els projectes a GitHub, trobar-hi un analògic i desplegar-lo vosaltres mateixos. No obstant això, en qualsevol cas, algú haurà de mantenir el portal, cosa que no és tan convenient per a l'ús bàsic o necessitats de prova. A més, swagger és més "sense principis" o més liberal: es pot generar a partir de comentaris al codi, que, per descomptat, va en contra del primer principi de l'API i no és compatible amb cap de les utilitats RAML.
En un moment vam començar a treballar amb RAML com un llenguatge més flexible i, com a resultat, vam haver de fer moltes coses nosaltres mateixos. Per exemple, un dels projectes utilitza la utilitat en proves unitàries, que només admet RAML 0.8. Així que vam haver d'afegir crosses perquè la utilitat pogués "menjar" RAML versió 1.0.
Necessites triar?
Després d'haver treballat per completar l'ecosistema de solucions per a RAML, vam arribar a la conclusió que hem de convertir RAML a Swagger 2 i dur-hi tota l'automatització, verificació, prova i optimització posterior. Aquesta és una bona manera d'aprofitar tant la flexibilitat de RAML com el suport d'eines de la comunitat de Swagger.
Per resoldre aquest problema, hi ha dues eines OpenSource que haurien de proporcionar la conversió del contracte:
- és una utilitat actualment no compatible. Mentre treballàvem amb ell, vam descobrir que té una sèrie de problemes amb RAML complexos que estan "escampats" per un gran nombre de fitxers. Aquest programa està escrit en JavaScript i realitza un recorregut recursiu d'un arbre de sintaxi. A causa de l'escriptura dinàmica, es fa difícil entendre aquest codi, així que vam decidir no perdre el temps escrivint pedaços per a una utilitat que s'està acabant.
- - una eina de la mateixa empresa que afirma estar disposada a convertir qualsevol cosa i tot, i en qualsevol direcció. Fins ara, s'ha anunciat suport per a RAML 0.8, RAML 1.0 i Swagger 2.0. Tanmateix, en el moment de la nostra investigació, la utilitat encara era humit i inutilitzable. Els desenvolupadors creen una mena de , que els permet afegir nous estàndards ràpidament en el futur. Però fins ara simplement no funciona.
I no són totes les dificultats que hem trobat. Un dels passos del nostre pipeline és verificar que el RAML del dipòsit és correcte en relació amb l'especificació. Hem provat diverses utilitats. Sorprenentment, tots van jurar les nostres anotacions en diferents llocs i amb paraules dolentes completament diferents. I no sempre al punt :).
Al final, ens vam acomodar a un projecte ara obsolet, que també té una sèrie de problemes (de vegades s'estavella de la blau, té problemes quan es treballa amb expressions regulars). Així, no vam trobar la manera de resoldre els problemes de validació i conversió a partir d'eines gratuïtes, i vam decidir utilitzar una utilitat comercial. En el futur, a mesura que les eines OpenSource es tornen més madures, aquest problema pot ser més fàcil de resoldre. Mentrestant, els costos de mà d'obra i de temps per “acabar” ens semblaven més importants que el cost d'un servei comercial.
Conclusió
Després de tot això, hem volgut compartir la nostra experiència i assenyalar que abans d'escollir una eina per descriure contractes, cal definir clarament què en vols i quin pressupost estàs disposat a invertir. Si ens oblidem d'OpenSource, ja hi ha un gran nombre de serveis i productes que us ajudaran a comprovar, convertir i validar. Però són cars, i de vegades molt cars. Per a una gran empresa, aquests costos són tolerables, però per a una startup poden convertir-se en una gran càrrega.
Determineu el conjunt d'eines que utilitzareu més endavant. Per exemple, si només necessiteu mostrar un contracte, serà més fàcil utilitzar Swagger 2, que té una bonica API, perquè a RAML haureu de construir i mantenir el servei vosaltres mateixos.
Com més tasques tingueu, més àmplia serà la necessitat d'eines, i són diferents per a diferents plataformes, i és millor familiaritzar-se immediatament amb les versions disponibles per prendre una elecció que minimitzi els vostres costos en el futur.
Però val la pena reconèixer que tots els ecosistemes que existeixen avui en dia són imperfectes. Per tant, si a l'empresa hi ha aficionats als quals els agrada treballar a RAML perquè "permet expressar els seus pensaments amb més flexibilitat" o, per contra, prefereixen Swagger perquè "és més clar", el millor és deixar-los treballar. en què són Hi estan acostumats i ho volen, perquè les eines de qualsevol dels formats requereixen modificació amb un fitxer.
Pel que fa a la nostra experiència, en els següents posts parlarem de quines comprovacions estàtiques i dinàmiques realitzem en funció de la nostra arquitectura RAML-Swagger, així com quina documentació generem a partir dels contractes i com funciona tot plegat.
Només els usuaris registrats poden participar en l'enquesta. si us plau.
Quin idioma feu servir per anotar els contractes de microserveis?
-
RAML 0.8
-
RAML 1.0
-
Lluita 2
-
OAS3 (també conegut com)
-
Cianotipo
-
Altres
-
No utilitzant
Han votat 100 usuaris. 24 usuaris es van abstenir.
Font: www.habr.com