Nan mond dinamik mikwosèvis yo, nenpòt bagay ka chanje — nenpòt eleman ka reekri nan yon lang diferan, lè l sèvi avèk diferan kad ak achitekti. Sèlman kontra yo ta dwe rete san chanjman pou mikwosèvis la ka kominike avèk soti deyò sou kèk baz pèmanan, kèlkeswa metamòfoz entèn yo. Ak jodi a nou pral pale sou pwoblèm nou an nan chwazi yon fòma pou dekri kontra ak pataje zafè nou te jwenn yo.
Post prepare и
Microservices. Lè nou devlope Acronis Cyber Cloud, nou reyalize ke nou pa t 'kapab chape anba yo. Epi konsepsyon yon mikwosèvis enposib san yo pa ofisyèlman kontra a, ki reprezante koòdone nan mikwosèvis la.
Men, lè yon pwodwi gen plis pase yon eleman, ak devlopman kontra vin yon aktivite regilye, ou pa ka ede men kòmanse reflechi sou optimize pwosesis. Li vin evidan ke koòdone (kontra) ak aplikasyon an (mikwosèvis) dwe matche youn ak lòt, ke diferan konpozan dwe fè menm bagay yo nan menm fason an, e ke san yo pa pran yon desizyon santralize nan tout desizyon sa yo, chak ekip yo pral fòse yo. pase tan ankò e ankò pou jwenn yo.
Amazon microservices dyagram soti nan Werner Vogelis, CTO Amazon
Ki sa ki dilèm nan? Defakto, gen de fason yo kominike mikwosèvis - HTTP Rest ak gRPC soti nan Google. Nou pa vle pran nan pil teknoloji Google la, nou te chwazi HTTP Rest. Annotasyon kontra HTTP REST yo dekri pi souvan nan youn nan de fòma: RAML ak OAS, ansyen ke yo rele Swagger.Se poutèt sa, chak ekip devlopman ap fè fas ak nesesite pou yo chwazi youn nan estanda yo. Men, kòm li vire soti, fè chwa sa a ka trè difisil.
Poukisa yo bezwen anotasyon?
Anotasyon an nesesè pou yon itilizatè ekstèn ka fasilman konnen ki sa ki ka fè ak sèvis ou atravè koòdone HTTP li yo. Sa vle di, nan yon nivo debaz, anotasyon an dwe genyen omwen yon lis resous ki disponib, metòd HTTP yo, kò demann, yon lis paramèt, yon endikasyon sou tèt obligatwa ak sipòte, osi byen ke kòd retounen ak fòma repons. Yon eleman trè enpòtan nan anotasyon kontra a se deskripsyon vèbal yo ("sa ki pral rive si ou ajoute paramèt rechèch sa a nan demann lan?", "Nan ki ka kòd 400 pral retounen?")
Sepandan, lè li rive devlope yon gwo kantite mikwosèvis, ou vle ekstrè valè adisyonèl nan annotasyon ekri yo. Pou egzanp, ki baze sou RAML/Swagger, ou ka jenere tou de kliyan ak kòd sèvè nan yon gwo kantite lang pwogramasyon. Ou kapab tou otomatikman resevwa dokiman pou mikwosèvis la epi telechaje li sou pòtal pwomotè w la :).
Egzanp yon deskripsyon kontra estriktire
Mwens komen se pratik nan tès mikwosèvis ki baze sou deskripsyon kontra yo. Si ou te ekri tou de yon anotasyon ak yon eleman, Lè sa a, ou ka kreye yon tès oto ki tcheke konpetans nan sèvis la ak divès kalite done opinyon. Èske sèvis la retounen yon kòd repons ki pa dekri nan anotasyon an? Èske li pral kapab kòrèkteman trete done evidamman kòrèk?
Anplis, bon jan kalite aplikasyon pa sèlman kontra yo tèt yo, men tou zouti yo pou vizyalize annotasyon fè li posib senplifye travay la ak mikwosèvis la. Sa vle di, si achitèk la kalitatif dekri kontra a, ki baze sou li, konsèpteur ak devlopè pral aplike sèvis la nan lòt pwodwi san yo pa depans tan adisyonèl.
Pou pèmèt zouti adisyonèl, tou de RAML ak OAS gen kapasite pou ajoute metadata estanda a pa prevwa ().
An jeneral, sijè ki abòde lan pou kreyativite nan lè l sèvi avèk kontra pou mikwosèvis se gwo ... omwen nan teyori.
Konparezon nan yon e ak yon koulèv
Kounye a, zòn devlopman priyorite nan Acronis se devlopman nan Acronis Cyber Platform. Acronis Cyber Platform se nouvo pwen entegrasyon sèvis twazyèm pati ak Acronis Cyber Cloud ak pati ajan an. Malgre ke nou te kontan ak API entèn nou yo dekri nan RAML, nesesite pou pibliye API a ankò te poze kesyon an nan chwa: ki estanda anotasyon ki pi bon yo itilize pou travay nou an?
Okòmansman, li te sanble ke te gen de solisyon - devlopman ki pi komen yo te RAML ak Swagger (oswa OAS). Men, an reyalite li te tounen soti ke gen omwen pa 2 altènativ, men 3 oswa plis.
Sou yon bò gen RAML - yon lang pwisan ak efikas. Li aplike yerachi ak eritaj byen, kidonk fòma sa a pi apwopriye pou gwo konpayi ki bezwen anpil deskripsyon - sa vle di, pa yon sèl pwodwi, men anpil mikwosèvis ki gen pati komen nan kontra - rapid otantifikasyon, menm kalite done yo, kò erè. .
Men, pwomotè RAML, Mulesoft, te rantre nan Open API consortium, ki ap devlope . Se poutèt sa, RAML sispann devlopman li. Pou imajine fòma evènman an, imajine ke moun ki kenbe prensipal eleman Linux yo kite travay nan Microsoft. Sitiyasyon sa a kreye kondisyon yo pou itilize Swagger, ki ap devlope dinamik ak nan dènye vèsyon an - twazyèm - pratikman kenbe ak RAML an tèm de fleksibilite ak fonctionnalités.
Si se pa pou yon sèl bagay...
Kòm li sanble, se pa tout sèvis piblik sous louvri yo te mete ajou nan OAS 3.0. Pou mikwosèvis nan Go, bagay ki pi enpòtan yo pral mank adaptasyon pou dènye vèsyon estanda a. Sepandan, diferans ki genyen ant Swagger 2 ak Swagger 3 se . Pou egzanp, nan twazyèm vèsyon an devlopè yo:
- amelyore deskripsyon rapid otantifikasyon
- Sipò JSON Schema
- amelyore kapasite pou ajoute egzanp
Sitiyasyon an se komik: lè w ap chwazi yon estanda, ou bezwen konsidere RAML, Swagger 2 ak Swagger 3 kòm altènatif separe. Sepandan, sèlman Swagger 2 gen bon sipò pou zouti OpenSource. RAML trè fleksib... ak konplèks, ak Swagger 3 mal sipòte pa kominote a, kidonk ou pral oblije sèvi ak zouti propriétaires oswa solisyon komèsyal, ki gen tandans yo dwe byen chè.
Anplis, si gen anpil karakteristik bèl nan Swagger, tankou yon pòtal pare-fè , sou ki ou ka Upload yon anotasyon epi jwenn vizyalizasyon li yo ak yon deskripsyon detaye, lyen ak koneksyon, Lè sa a, pou RAML ki pi fondamantal ak mwens zanmitay pa gen okenn opòtinite sa yo. Wi, ou ka chèche yon bagay nan mitan pwojè yo sou GitHub, jwenn yon analogue la epi deplwaye li tèt ou. Sepandan, nan nenpòt ka, yon moun ap oblije kenbe pòtal la, ki pa tèlman pratik pou itilizasyon debaz oswa bezwen tès yo. Anplis de sa, swagger se plis "san prensip", oswa plis liberal - li ka pwodwi nan kòmantè nan kòd la, ki, nan kou, ale kont prensip la API premye epi yo pa sipòte pa nenpòt nan sèvis piblik RAML yo.
Nan yon lè nou te kòmanse travay ak RAML kòm yon lang ki pi fleksib, e kòm rezilta nou te oblije fè anpil bagay nou menm. Pou egzanp, youn nan pwojè yo sèvi ak sèvis piblik la nan tès inite yo, ki sèlman sipòte RAML 0.8. Se konsa, nou te oblije ajoute beki pou sèvis piblik la te kapab "manje" RAML vèsyon 1.0.
Ou bezwen chwazi?
Lè nou te travay sou ranpli ekosistèm solisyon pou RAML, nou te rive nan konklizyon ke nou bezwen konvèti RAML nan Swagger 2 epi pote soti nan tout automatisation, verifikasyon, tès ak optimize ki vin apre ladan l. Sa a se yon bon fason pou ogmante fleksibilite RAML ak sipò zouti kominotè Swagger.
Pou rezoud pwoblèm sa a, gen de zouti OpenSource ki ta dwe bay konvèsyon kontra:
- se yon sèvis piblik ki pa sipòte kounye a. Pandan w ap travay ak li, nou dekouvri ke li gen yon kantite pwoblèm ak RAML konplèks ki "gaye" sou yon gwo kantite dosye. Pwogram sa a ekri nan JavaScript epi li fè yon travèse rekursif nan yon pye bwa sentaks. Akòz sezisman dinamik, li vin difisil pou konprann kòd sa a, kidonk nou deside pa pèdi tan ekri plak pou yon sèvis piblik ki mouri.
- - yon zouti ki soti nan konpayi an menm ki reklamasyon yo dwe pare yo konvèti anyen ak tout bagay, ak nan nenpòt direksyon. Pou dat, yo te anonse sipò pou RAML 0.8, RAML 1.0 ak Swagger 2.0. Sepandan, nan moman rechèch nou an, sèvis piblik la te toujou mouye e ki pa ka itilize. Devlopè kreye yon kalite , ki pèmèt yo byen vit ajoute nouvo estanda nan tan kap vini an. Men, jiskaprezan li jis pa travay.
E sa a se pa tout difikilte nou te rankontre. Youn nan etap sa yo nan tiyo nou an se verifye ke RAML ki soti nan depo a kòrèk anrapò ak spesifikasyon la. Nou te eseye plizyè sèvis piblik. Etonan, yo tout te sèmante sou annotations nou yo nan diferan kote ak ak move mo konplètman diferan. Epi yo pa toujou nan pwen an :).
Nan fen a, nou rezoud sou yon pwojè kounye a demode, ki gen tou yon kantite pwoblèm (pafwa li aksidan soti nan ble a, gen pwoblèm lè w ap travay ak ekspresyon regilye). Kidonk, nou pa t 'jwenn yon fason yo rezoud pwoblèm yo nan validation ak konvèsyon ki baze sou zouti gratis, ak deside sèvi ak yon sèvis piblik komèsyal yo. Nan tan kap vini an, kòm zouti OpenSource vin pi matirite, pwoblèm sa a ka vin pi fasil pou rezoud. Antretan, depans travay ak tan pou "fini" te sanble pi enpòtan pase pri yon sèvis komèsyal.
Konklizyon
Apre tout bagay sa yo, nou te vle pataje eksperyans nou yo epi sonje ke anvan ou chwazi yon zouti pou dekri kontra yo, ou bezwen defini klèman sa ou vle soti nan li ak ki bidjè ou vle envesti. Si nou bliye sou OpenSource, gen deja yon gwo kantite sèvis ak pwodwi ki pral ede w tcheke, konvèti, ak valide. Men, yo chè, epi pafwa trè chè. Pou yon gwo konpayi, depans sa yo tolerab, men pou yon demaraj yo ka vin yon gwo fado.
Detèmine seri zouti ou pral itilize pita. Pou egzanp, si ou jis bezwen montre yon kontra, li pral pi fasil yo sèvi ak Swagger 2, ki gen yon API bèl, paske nan RAML ou pral gen yo bati ak kenbe sèvis la tèt ou.
Plis travay ou genyen, se pi laj bezwen zouti yo, epi yo diferan pou platfòm diferan, epi li pi bon imedyatman familyarize tèt ou ak vèsyon ki disponib yo nan lòd yo fè yon chwa ki minimize depans ou nan tan kap vini an.
Men, li vo rekonèt ke tout ekosistèm ki egziste jodi a se enpafè. Se poutèt sa, si gen fanatik nan konpayi an ki renmen travay nan RAML paske "li pèmèt ou eksprime panse plis fleksib," oswa, okontrè, prefere Swagger paske "li pi klè," li pi bon pou kite yo travay. nan sa yo ye Yo abitye ak li epi yo vle li, paske zouti yo nan nenpòt nan fòma yo mande pou modifikasyon ak yon dosye.
Kòm pou eksperyans nou an, nan pòs sa yo nou pral pale sou ki chèk estatik ak dinamik nou fè ki baze sou achitekti RAML-Swagger nou an, osi byen ke ki dokiman nou jenere nan kontra yo, ak ki jan li tout travay.
Se sèlman itilizatè ki anrejistre ki ka patisipe nan sondaj la. , tanpri.
Ki lang ou itilize pou anote kontra mikwosèvis yo?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (aka)
-
Plan
-
Lòt
-
Pa itilize
100 itilizatè yo te vote. 24 itilizatè te absteni.
Sous: www.habr.com