An der dynamescher Welt vu Mikroservicer kann alles änneren - all Komponent kann an enger anerer Sprooch nei geschriwwe ginn, mat verschiddene Kaderen an Architektur. Nëmme Kontrakter sollen onverännert bleiwen, sou datt de Mikroservice vu baussen op eng permanent Basis interagéiert ka ginn, onofhängeg vun internen Metamorphosen. An haut wäerte mir iwwer eise Problem schwätzen fir e Format ze wielen fir Kontrakter ze beschreiwen an d'Artefakte ze deelen déi mir fonnt hunn.
Post virbereet и
Mikroservicer. Wann Dir Acronis Cyber Cloud entwéckelt, hu mir gemierkt datt mir hinnen net konnten entkommen. An e Mikroservice ze designen ass onméiglech ouni de Kontrakt ze formaliséieren, deen d'Interface vum Mikroservice duerstellt.
Awer wann e Produkt méi wéi ee Komponent enthält, an d'Kontraktentwécklung eng regulär Aktivitéit gëtt, kënnt Dir net hëllefen, iwwer Prozessoptimiséierung ze denken. Et gëtt evident datt d'Interface (Kontrakt) an d'Ëmsetzung (Mikroservice) matenee passen, datt verschidde Komponenten déiselwecht Saache mussen op déiselwecht Manéier maachen, an datt ouni eng zentraliséiert Entscheedung vun all dësen Entscheedungen all Team gezwongen ass verbréngt ëmmer erëm Zäit fir se ze kréien.
Amazon Microservices Diagramm vun Werner Vogelis, CTO Amazon
Wat ass den Dilemma? De facto ginn et zwee Weeër fir Mikroservicer ze interagéieren - HTTP Rest a gRPC vu Google. Net wëllen am Google's Technologie Stack agefaange ginn, hu mir HTTP Rest gewielt. HTTP REST Kontrakt Annotatiounen ginn am meeschten an engem vun zwee Formater beschriwwen: RAML an OAS, fréier bekannt als Swagger. Dofir ass all Entwécklungsteam mat der Bedierfnes konfrontéiert ee vun de Standarden ze wielen. Awer wéi et sech erausstellt, kann dës Wiel ganz schwéier sinn.
Firwat sinn Annotatiounen néideg?
D'Annotatioun ass néideg fir datt en externe Benotzer einfach erausfannen wat mat Ärem Service duerch seng HTTP-Interface ka gemaach ginn. Dat ass, op engem Basisniveau muss d'Annotatioun op d'mannst eng Lëscht vu verfügbare Ressourcen enthalen, hir HTTP-Methoden, Ufroorganer, eng Oplëschtung vu Parameteren, eng Indikatioun vun den erfuerderlechen an ënnerstëtzten Header, souwéi Retourcodes an Äntwertformater. En extrem wichtegt Element vun der Kontraktannotatioun ass hir mëndlech Beschreiwung ("wat geschitt wann Dir dësen Ufroparameter op d'Ufro bäidréit?", "A wéi engem Fall gëtt de Code 400 zréckginn?")
Wéi och ëmmer, wann et drëm geet eng grouss Zuel vu Mikroservicer z'entwéckelen, wëllt Dir zousätzlech Wäert aus de schrëftleche Annotatiounen extrahéieren. Zum Beispill, baséiert op RAML / Swagger, kënnt Dir souwuel Client- a Servercode an enger grousser Zuel vu Programméierungssproochen generéieren. Dir kënnt och automatesch Dokumentatioun fir de Mikroservice kréien an se op Ären Entwécklerportal eroplueden :).
Beispill vun enger strukturéierter Kontrakt Beschreiwung
Manner heefeg ass d'Praxis fir Mikroservicer ze testen op Basis vu Kontraktbeschreiwungen. Wann Dir souwuel eng Annotatioun wéi och eng Komponent geschriwwen hutt, da kënnt Dir en Autotest erstellen, deen d'Adequatitéit vum Service mat verschiddenen Typen vun Inputdaten iwwerpréift. Gitt de Service en Äntwertcode zréck deen net an der Annotatioun beschriwwe gëtt? Wäert et fäeg sinn offensichtlech falsch Donnéeën korrekt ze veraarbechten?
Ausserdeem, qualitativ héichwäerteg Ëmsetzung vun net nëmmen de Kontrakter selwer, awer och d'Tools fir d'Visualiséierung vun Annotatiounen mécht et méiglech d'Aarbecht mam Mikroservice ze vereinfachen. Dat ass, wann den Architekt qualitativ beschriwwen de Kontrakt, baséiert op et, Designer an Entwéckler wäert de Service an anere Produiten ëmsetzen ouni zousätzlech Zäit Käschten.
Fir zousätzlech Tools z'erméiglechen, souwuel RAML wéi och OAS hunn d'Fäegkeet Metadaten derbäi ze ginn, déi net vum Standard virgesi sinn ().
Am Allgemengen ass de Spillraum fir Kreativitéit beim Gebrauch vu Kontrakter fir Mikroservicer enorm ... op d'mannst an der Theorie.
Verglach vun engem Kéiseker mat enger Schlaang
De Moment ass de prioritären Entwécklungsberäich bei Acronis d'Entwécklung vun der Acronis Cyber Plattform. Acronis Cyber Plattform ass nei Punkte vun der Integratioun vun Drëtt Partei Servicer mat Acronis Cyber Cloud an dem Agent Deel. Och wa mir frou waren mat eisen internen APIen, déi am RAML beschriwwe goufen, huet de Besoin fir d'API ze publizéieren erëm d'Fro vun der Wiel opgeworf: wéi eng Annotatiounsstandard ass am beschten fir eis Aarbecht ze benotzen?
Am Ufank huet et geschéngt datt et zwou Léisunge wieren - déi heefegst Entwécklunge waren RAML a Swagger (oder OAS). Mä eigentlech huet sech erausgestallt, datt et op d'mannst net 2 Alternativen ginn, mä 3 oder méi.
Engersäits gëtt et RAML - eng mächteg an effizient Sprooch. Et implementéiert d'Hierarchie an d'Ierfschaft gutt, sou datt dëst Format méi gëeegent ass fir grouss Firmen déi vill Beschreiwunge brauchen - dat heescht net ee Produkt, mee vill Mikroservicer déi gemeinsam Deeler vu Kontrakter hunn - Authentifikatiounsschemaen, déiselwecht Datentypen, Feelerkierper .
Awer den Entwéckler vu RAML, Mulesoft, huet sech dem Open API Konsortium ugeschloss, deen entwéckelt . Dofir huet RAML seng Entwécklung suspendéiert. Fir d'Format vum Event virzestellen, stellt Iech vir datt d'Inhalter vun den Haapt Linux Komponenten verlooss hunn fir bei Microsoft ze schaffen. Dës Situatioun schaaft d'Viraussetzunge fir Swagger ze benotzen, déi dynamesch entwéckelt an an der leschter - drëtter Versioun - praktesch mat RAML a punkto Flexibilitéit a Funktionalitéit erfaasst.
Wann net fir eng Saach ...
Wéi et sech erausstellt, sinn net all Open-Source Utilities op OAS 3.0 aktualiséiert ginn. Fir Mikroservicer am Go ass déi kriteschst Saach de Mangel un Adaptatioun fir déi lescht Versioun vum Standard. Wéi och ëmmer, den Ënnerscheed tëscht Swagger 2 a Swagger 3 ass . Zum Beispill, an der drëtter Versioun sinn d'Entwéckler:
- verbessert Beschreiwung vun Authentifikatioun Schemaen
- JSON Schema Ënnerstëtzung
- Upgrade d'Fäegkeet fir Beispiller ze addéieren
D'Situatioun ass witzeg: Wann Dir e Standard wielt, musst Dir RAML, Swagger 2 a Swagger 3 als separat Alternativen betruechten. Wéi och ëmmer, nëmmen Swagger 2 huet gutt Ënnerstëtzung fir OpenSource Tools. RAML ass ganz flexibel ... a komplex, an Swagger 3 ass schlecht vun der Gemeinschaft ënnerstëtzt, also musst Dir propriétaire Tools oder kommerziell Léisungen benotzen, déi éischter deier sinn.
Ausserdeem, wann et vill flott Features am Swagger sinn, sou wéi e fäerdege Portal , op där Dir eng Annotatioun eropluede kënnt a seng Visualiséierung mat enger detailléierter Beschreiwung, Linken a Verbindungen kritt, da gëtt et fir de méi fundamentalen a manner frëndlechen RAML keng esou Méiglechkeet. Jo, Dir kënnt eppes ënner Projeten op GitHub sichen, en Analog do fannen an et selwer ofsetzen. Wéi och ëmmer, iergendeen muss de Portal erhalen, wat net sou bequem ass fir Basisnotzung oder Testbedürfnisser. Zousätzlech ass Swagger méi "prinzipiell" oder méi liberal - et kann aus Kommentaren am Code generéiert ginn, wat natierlech géint den API éischte Prinzip geet an net vun engem vun den RAML Utilities ënnerstëtzt gëtt.
Mir hunn eng Kéier ugefaang mam RAML als méi flexibel Sprooch ze schaffen, an doduerch hu mir vill Saache selwer misse maachen. Zum Beispill benotzt ee vun de Projeten den Utility an Eenheetstester, déi nëmmen RAML 0.8 ënnerstëtzt. Also hu mir Krutchen derbäigesat fir datt den Utility RAML Versioun 1.0 "iessen" konnt.
Braucht Dir ze wielen?
Nodeems mir un der Ofschloss vum Ökosystem vu Léisunge fir RAML geschafft hunn, sinn mir zur Conclusioun komm datt mir RAML an Swagger 2 mussen konvertéieren an all d'Automatisatioun, d'Verifizéierung, d'Test an d'spéider Optimiséierung dran ausféieren. Dëst ass e gudde Wee fir souwuel d'Flexibilitéit vum RAML wéi och d'Communautéit Tooling Support vu Swagger ze profitéieren.
Fir dëse Problem ze léisen, ginn et zwee OpenSource Tools déi Kontraktkonversioun ubidden:
- ass en aktuell net ënnerstëtzten Utility. Iwwerdeems mat et schaffen, mir entdeckt, datt et eng Rei vu Problemer mat komplex RAMLs huet, datt iwwer eng grouss Zuel vun Fichieren "verbreet" sinn. Dëse Programm ass a JavaScript geschriwwen a mécht e rekursive Traversal vun engem Syntaxbaum. Wéinst dynamesche Schreifweis gëtt et schwéier dëse Code ze verstoen, also hu mir beschloss keng Zäit ze verschwenden fir Patches fir e Stierwen Utility ze schreiwen.
- - e Tool vun der selwechter Firma déi behaapt prett ze sinn alles an alles ze konvertéieren, an all Richtung. Bis haut ass Ënnerstëtzung fir RAML 0.8, RAML 1.0 a Swagger 2.0 ugekënnegt. Wéi och ëmmer, zur Zäit vun eiser Fuerschung war d'Utility nach ëmmer fiicht an onbrauchbar. Entwéckler schafen eng Zort , wat hinnen erlaabt an Zukunft séier nei Standarden ze addéieren. Mee bis elo geet et einfach net.
An dat sinn net all Schwieregkeeten, déi mir begéint hunn. Ee vun de Schrëtt an eiser Pipeline ass fir z'iwwerpréiwen datt de RAML aus dem Repository richteg ass par rapport zu der Spezifizéierung. Mir hunn e puer Utilities probéiert. Iwwerraschend hunn se all op verschiddene Plazen a mat komplett anere schlechte Wierder op eis Annotatiounen geschwuer. An net ëmmer zum Punkt :).
Um Enn hu mir eis op en elo ausgezeechente Projet niddergelooss, deen och eng Rei Problemer huet (heiansdo klappt en aus dem Blo, Problemer beim Schaffen mat regulären Ausdréck). Also hu mir kee Wee fonnt fir d'Problemer vun der Validatioun an der Konversioun op Basis vu gratis Tools ze léisen, an hunn decidéiert e kommerziellen Utility ze benotzen. An Zukunft, wéi OpenSource Tools méi al ginn, kann dëse Problem méi einfach ginn ze léisen. An der Tëschenzäit hunn d'Aarbechts- an d'Zäitkäschte fir "Finishing" eis méi bedeitend geschéngt wéi d'Käschte vun engem kommerziellen Service.
Konklusioun
No all deem, mir wollten eis Erfahrung ze deelen an Notiz datt ier Dir e Tool fir Kontrakter beschreiwen, Dir musst kloer definéieren wat Dir wëllt aus et a wat Budget Dir sidd bereet ze investéieren. Wa mir iwwer OpenSource vergiessen, ginn et schonn eng grouss Zuel vu Servicer a Produkter déi Iech hëllefen ze kontrolléieren, konvertéieren a validéieren. Awer si sinn deier, an heiansdo ganz deier. Fir eng grouss Firma sinn esou Käschten tolerabel, awer fir e Startup kënne se eng grouss Belaaschtung ginn.
Bestëmmt de Set vun Tools déi Dir spéider benotzt. Zum Beispill, wann Dir just e Kontrakt muss weisen, wäert et méi einfach sinn Swagger 2 ze benotzen, deen e schéinen API huet, well an RAML musst Dir de Service selwer bauen an erhalen.
Wat méi Aufgaben Dir hutt, wat méi breet ass de Besoin fir Tools, a si sinn ënnerschiddlech fir verschidde Plattformen, an et ass besser Iech direkt mat de verfügbare Versioune vertraut ze maachen fir e Choix ze maachen deen Är Käschten an Zukunft miniméiert.
Awer et ass derwäert ze erkennen datt all Ökosystemer déi haut existéieren onvollstänneg sinn. Dofir, wann et Fans an der Firma sinn, déi gären am RAML schaffen well "et Iech erlaabt Gedanken méi flexibel auszedrécken", oder am Géigendeel, Swagger léiwer well "et ass méi kloer", ass et am beschten se ze schaffen ze loossen a wat se sinn Si si gewinnt a wëllen et, well d'Tools vun engem vun de Formater Ännerunge mat enger Datei erfuerderen.
Wat eis Erfahrung ugeet, wäerte mir an de folgende Posts schwätzen iwwer wat statesch an dynamesch Kontrollen mir maachen op Basis vun eiser RAML-Swagger Architektur, wéi och wéi eng Dokumentatioun mir aus Kontrakter generéieren, a wéi et alles funktionnéiert.
Nëmme registréiert Benotzer kënnen un der Ëmfro deelhuelen. , wann ech glift.
Wéi eng Sprooch benotzt Dir fir Mikroservicekontrakter ze annotéieren?
-
RAML 0.8
-
RAML 1.0
-
Schweier 2
-
OAS3 (eng)
-
MGMT
-
Aner
-
Net benotzt
100 Benotzer hunn gestëmmt. 24 Benotzer hu sech enthalen.
Source: will.com