În lumea dinamică a microserviciilor, orice se poate schimba — orice componentă poate fi rescrisă într-o altă limbă, folosind cadre și arhitecturi diferite. Doar contractele ar trebui să rămână neschimbate, astfel încât microserviciul să poată fi interacționat din exterior pe o bază permanentă, indiferent de metamorfozele interne. Și astăzi vom vorbi despre problema noastră de a alege un format pentru descrierea contractelor și vom împărtăși artefactele pe care le-am găsit.
Postare pregătită и
Microservicii. Când am dezvoltat Acronis Cyber Cloud, ne-am dat seama că nu putem scăpa de ei. Iar proiectarea unui microserviciu este imposibilă fără formalizarea contractului, care reprezintă interfața microserviciului.
Dar atunci când un produs conține mai mult de o componentă, iar dezvoltarea contractului devine o activitate obișnuită, nu poți să nu începi să te gândești la optimizarea proceselor. Devine evident că interfața (contractul) și implementarea (microserviciul) trebuie să se potrivească între ele, că diferitele componente trebuie să facă aceleași lucruri în același mod și că fără o luare a deciziilor centralizată a tuturor acestor decizii, fiecare echipă va fi obligată să petrece timpul din nou și din nou pentru a le obține.
Diagrama microserviciilor Amazon de la Werner Vogelis, CTO Amazon
Care este dilema? De fapt, există două moduri de a interacționa cu microservicii - HTTP Rest și gRPC de la Google. Nevrând să fim prinși în tehnologia Google, am ales HTTP Rest. Adnotările contractului HTTP REST sunt descrise cel mai adesea în unul dintre cele două formate: RAML și OAS, cunoscute anterior ca Swagger.De aceea, fiecare echipă de dezvoltare se confruntă cu nevoia de a alege unul dintre standarde. Dar după cum se dovedește, a face această alegere poate fi foarte dificil.
De ce sunt necesare adnotările?
Adnotarea este necesară pentru ca un utilizator extern să-și dea seama cu ușurință ce se poate face cu serviciul dvs. prin interfața sa HTTP. Adică, la nivel de bază, adnotarea trebuie să conțină cel puțin o listă de resurse disponibile, metodele HTTP ale acestora, corpurile de solicitare, o listă de parametri, o indicație a antetelor necesare și acceptate, precum și coduri de returnare și formate de răspuns. Un element extrem de important al adnotării contractului este descrierea verbală a acestora („ce se va întâmpla dacă adăugați acest parametru de interogare la cerere?”, „În ce caz va fi returnat codul 400?”)
Cu toate acestea, când vine vorba de dezvoltarea unui număr mare de microservicii, doriți să extrageți valoare suplimentară din adnotările scrise. De exemplu, pe baza RAML/Swagger, puteți genera atât codul client, cât și codul serverului într-un număr mare de limbaje de programare. De asemenea, puteți primi automat documentația pentru microserviciu și o puteți încărca pe portalul pentru dezvoltatori :).
Exemplu de descriere a unui contract structurat
Mai puțin obișnuită este practica de a testa microservicii pe baza descrierilor contractelor. Dacă ați scris atât o adnotare, cât și o componentă, atunci puteți crea un autotest care verifică caracterul adecvat al serviciului cu diferite tipuri de date de intrare. Serviciul returnează un cod de răspuns care nu este descris în adnotare? Va putea procesa corect date evident incorecte?
Mai mult, implementarea de înaltă calitate nu numai a contractelor în sine, ci și a instrumentelor de vizualizare a adnotărilor face posibilă simplificarea muncii cu microserviciul. Adică, dacă arhitectul a descris calitativ contractul, pe baza acestuia, designerii și dezvoltatorii vor implementa serviciul în alte produse fără costuri suplimentare de timp.
Pentru a activa instrumente suplimentare, atât RAML, cât și OAS au capacitatea de a adăuga metadate neprevăzute de standard ().
În general, spațiul de creativitate în utilizarea contractelor pentru microservicii este uriaș... cel puțin în teorie.
Comparația unui arici cu un șarpe
În prezent, zona de dezvoltare prioritară la Acronis este dezvoltarea Platformei Acronis Cyber. Acronis Cyber Platform reprezintă noi puncte de integrare a serviciilor terță parte cu Acronis Cyber Cloud și partea agent. Deși am fost mulțumiți de API-urile noastre interne descrise în RAML, necesitatea de a publica API-ul a ridicat din nou întrebarea alegerii: care standard de adnotare este cel mai bine să folosim pentru munca noastră?
Inițial, părea că există două soluții - cele mai comune dezvoltări au fost RAML și Swagger (sau OAS). Dar de fapt s-a dovedit că există cel puțin nu 2 alternative, ci 3 sau mai multe.
Pe de o parte există RAML - un limbaj puternic și eficient. Implementează bine ierarhia și moștenirea, așa că acest format este mai potrivit pentru companiile mari care au nevoie de multe descrieri - adică nu un singur produs, ci multe microservicii care au părți comune ale contractelor - scheme de autentificare, aceleași tipuri de date, corpuri de eroare. .
Dar dezvoltatorul RAML, Mulesoft, s-a alăturat consorțiului Open API, care se dezvoltă . Prin urmare, RAML și-a suspendat dezvoltarea. Pentru a vă imagina formatul evenimentului, imaginați-vă că întreținerii principalelor componente Linux au plecat să lucreze pentru Microsoft. Această situație creează premisele pentru utilizarea Swagger, care se dezvoltă dinamic și în cea mai recentă - versiunea a treia - practic ajunge din urmă RAML în ceea ce privește flexibilitatea și funcționalitatea.
Dacă nu pentru unul, dar...
După cum se dovedește, nu toate utilitățile open-source au fost actualizate la OAS 3.0. Pentru microservicii din Go, cel mai critic lucru va fi lipsa de adaptare pentru cea mai recentă versiune a standardului. Cu toate acestea, diferența dintre Swagger 2 și Swagger 3 este . De exemplu, în cea de-a treia versiune dezvoltatorii:
- descrierea îmbunătățită a schemelor de autentificare
- Suport pentru schema JSON
- a îmbunătățit capacitatea de a adăuga exemple
Situația este amuzantă: atunci când alegeți un standard, trebuie să luați în considerare RAML, Swagger 2 și Swagger 3 ca alternative separate. Cu toate acestea, doar Swagger 2 are un suport bun pentru instrumentele OpenSource. RAML este foarte flexibil... și complex, iar Swagger 3 este slab susținut de comunitate, așa că va trebui să utilizați instrumente proprietare sau soluții comerciale, care tind să fie destul de costisitoare.
Mai mult, dacă există multe caracteristici frumoase în Swagger, cum ar fi un portal gata făcut , pe care puteți încărca o adnotare și obțineți vizualizarea acesteia cu o descriere detaliată, link-uri și conexiuni, apoi pentru RAML mai fundamental și mai puțin prietenos nu există o astfel de oportunitate. Da, puteți căuta ceva printre proiecte pe GitHub, puteți găsi un analog acolo și îl puteți implementa singur. Cu toate acestea, în orice caz, cineva va trebui să întrețină portalul, ceea ce nu este atât de convenabil pentru utilizarea de bază sau nevoile de testare. În plus, swagger este mai „neprincipială” sau mai liberală - poate fi generată din comentariile din cod, care, desigur, contravine primului principiu API și nu este susținut de niciunul dintre utilitarele RAML.
La un moment dat am început să lucrăm cu RAML ca un limbaj mai flexibil și, ca urmare, a trebuit să facem o mulțime de lucruri singuri. De exemplu, unul dintre proiecte folosește utilitatea în testele unitare, care acceptă doar RAML 0.8. Așa că a trebuit să adăugăm cârje, astfel încât utilitarul să poată „mânca” RAML versiunea 1.0.
Trebuie să alegi?
După ce am lucrat la finalizarea ecosistemului de soluții pentru RAML, am ajuns la concluzia că trebuie să convertim RAML în Swagger 2 și să realizăm toate automatizările, verificarea, testarea și optimizarea ulterioară în acesta. Aceasta este o modalitate bună de a valorifica atât flexibilitatea RAML, cât și suportul pentru instrumentele comunitare de la Swagger.
Pentru a rezolva această problemă, există două instrumente OpenSource care ar trebui să ofere conversie contractului:
- este un utilitar neacceptat în prezent. În timp ce lucrăm cu el, am descoperit că are o serie de probleme cu RAML-uri complexe care sunt „împrăștiate” pe un număr mare de fișiere. Acest program este scris în JavaScript și efectuează o parcurgere recursivă a unui arbore de sintaxă. Datorită tastării dinamice, devine dificil să înțelegem acest cod, așa că am decis să nu pierdem timpul scriind patch-uri pentru un utilitar pe cale de dispariție.
- - un instrument de la aceeași companie care pretinde că este gata să convertească orice și totul, și în orice direcție. Până în prezent, a fost anunțat suport pentru RAML 0.8, RAML 1.0 și Swagger 2.0. Cu toate acestea, la momentul cercetării noastre, utilitatea era încă umed și inutilizabil. Dezvoltatorii creează un fel de , permițându-le să adauge rapid noi standarde în viitor. Dar până acum pur și simplu nu funcționează.
Și nu sunt toate dificultățile pe care le-am întâlnit. Unul dintre pașii din conducta noastră este să verificăm dacă RAML din depozit este corect în raport cu specificația. Am încercat mai multe utilități. În mod surprinzător, toți au înjurat adnotările noastre în locuri diferite și cu cu totul alte cuvinte rele. Și nu întotdeauna la obiect :).
În cele din urmă, ne-am stabilit pe un proiect acum învechit, care are și o serie de probleme (uneori se blochează din senin, are probleme când lucrezi cu expresii regulate). Astfel, nu am găsit o modalitate de a rezolva problemele de validare și conversie pe baza instrumentelor gratuite și am decis să folosim un utilitar comercial. În viitor, pe măsură ce instrumentele OpenSource devin mai mature, această problemă poate deveni mai ușor de rezolvat. Între timp, costurile cu forța de muncă și timp pentru „finisare” ni s-au părut mai semnificative decât costul unui serviciu comercial.
Concluzie
După toate acestea, am vrut să împărtășim experiența noastră și să observăm că înainte de a alege un instrument de descriere a contractelor, trebuie să definiți clar ce doriți de la acesta și ce buget sunteți dispus să investiți. Dacă uităm de OpenSource, există deja un număr mare de servicii și produse care vă vor ajuta să verificați, să convertiți și să validați. Dar sunt scumpe și uneori foarte scumpe. Pentru o companie mare, astfel de costuri sunt tolerabile, dar pentru un startup pot deveni o povară mare.
Determinați setul de instrumente pe care îl veți folosi mai târziu. De exemplu, dacă trebuie doar să afișați un contract, va fi mai ușor să utilizați Swagger 2, care are un API frumos, deoarece în RAML va trebui să construiți și să întrețineți singur serviciul.
Cu cât aveți mai multe sarcini, cu atât nevoia de instrumente va fi mai largă și acestea sunt diferite pentru diferite platforme și este mai bine să vă familiarizați imediat cu versiunile disponibile pentru a face o alegere care să vă minimizeze costurile în viitor.
Dar merită să recunoaștem că toate ecosistemele care există astăzi sunt imperfecte. Prin urmare, dacă există fani în companie cărora le place să lucreze în RAML pentru că „îți permite să-ți exprimi gândurile mai flexibil” sau, dimpotrivă, preferă Swagger pentru că „este mai clar”, cel mai bine este să-i lași să lucreze în ceea ce sunt Ei sunt obișnuiți și doresc, deoarece instrumentele oricăruia dintre formate necesită modificare cu un fișier.
În ceea ce privește experiența noastră, în postările următoare vom vorbi despre ce verificări statice și dinamice efectuăm pe baza arhitecturii RAML-Swagger, precum și ce documentație generăm din contracte și cum funcționează totul.
Numai utilizatorii înregistrați pot participa la sondaj. , Vă rog.
Ce limbă folosiți pentru adnotarea contractelor de microservicii?
-
RAML 0.8
-
RAML 1.0
-
Trăiască 2
-
OAS3 (alias)
-
Blueprint
-
Alte
-
Nu folosesc
Au votat 100 utilizatori. 24 utilizatori s-au abținut.
Sursa: www.habr.com