Այսպիսով, դա RAML կամ OAS (Swagger) է:

Միկրոծառայությունների դինամիկ աշխարհում ամեն ինչ կարող է փոխվել՝ ցանկացած բաղադրիչ կարող է վերաշարադրվել այլ լեզվով՝ օգտագործելով տարբեր շրջանակներ և ճարտարապետություն: Միայն պայմանագրերը պետք է մնան անփոփոխ, որպեսզի միկրոծառայության հետ հնարավոր լինի փոխազդել դրսից մշտական ​​հիմունքներով՝ անկախ ներքին փոխակերպումներից: Եվ այսօր մենք կխոսենք պայմանագրերի նկարագրության ձևաչափ ընտրելու մեր խնդրի մասին և կկիսվենք մեր գտած արտեֆակտներով:

Գրառումը պատրաստ է Աննա Մելեխովա и Վլադիմիր Լապատին

Միկրոծառայություններ. Acronis Cyber ​​Cloud-ը մշակելիս մենք հասկացանք, որ չենք կարող խուսափել դրանցից: Իսկ միկրոսերվիսի նախագծումն անհնար է առանց պայմանագրի պաշտոնականացման, որը ներկայացնում է միկրոսերվիսի միջերեսը։

Բայց երբ ապրանքը պարունակում է մեկից ավելի բաղադրիչ, և պայմանագրերի մշակումը դառնում է սովորական գործունեություն, դուք չեք կարող չսկսել մտածել գործընթացի օպտիմալացման մասին: Ակնհայտ է դառնում, որ ինտերֆեյսը (պայմանագիրը) և իրականացումը (միկրոսպասարկումը) պետք է համապատասխանեն միմյանց, որ տարբեր բաղադրիչներ պետք է կատարեն նույն բաները նույն ձևով, և որ առանց այս բոլոր որոշումների կենտրոնացված որոշումների կայացման, յուրաքանչյուր թիմ ստիպված կլինի. կրկին ու կրկին ժամանակ ծախսեք դրանք ստանալու համար:

Amazon microservices գծապատկերը թվիթ Վերներ Ֆոգելիս, Amazon-ի CTO
Ո՞րն է երկընտրանքը: Դե ֆակտո, միկրոծառայությունների հետ փոխազդելու երկու եղանակ կա՝ HTTP Rest և gRPC Google-ից: Չցանկանալով հայտնվել Google-ի տեխնոլոգիական փաթեթում՝ մենք ընտրեցինք HTTP Rest-ը: HTTP REST պայմանագրային ծանոթագրությունները առավել հաճախ նկարագրվում են երկու ձևաչափերից մեկով՝ RAML և OAS, որոնք նախկինում հայտնի էին որպես Swagger: Հետևաբար, յուրաքանչյուր մշակող թիմ կանգնած է ստանդարտներից որևէ մեկի ընտրության անհրաժեշտության հետ: Սակայն, ինչպես պարզվում է, այս ընտրությունը կարող է շատ դժվար լինել։

Ինչու են անհրաժեշտ ծանոթագրությունները:

Անոտացիան անհրաժեշտ է, որպեսզի արտաքին օգտագործողը կարողանա հեշտությամբ պարզել, թե ինչ կարելի է անել ձեր ծառայության հետ HTTP ինտերֆեյսի միջոցով: Այսինքն, հիմնական մակարդակում անոտացիան պետք է պարունակի առնվազն առկա ռեսուրսների ցանկ, դրանց HTTP մեթոդները, հարցումների մարմինները, պարամետրերի ցանկը, պահանջվող և աջակցվող վերնագրերի նշումը, ինչպես նաև վերադարձի կոդերը և պատասխանների ձևաչափերը: Պայմանագրի անոտացիայի չափազանց կարևոր տարրը նրանց բանավոր նկարագրությունն է («ինչ կլինի, եթե այս հարցման պարամետրը ավելացնեք հարցումին», «Ի՞նչ դեպքում կվերադարձվի 400 ծածկագիրը»):

Այնուամենայնիվ, երբ խոսքը վերաբերում է մեծ թվով միկրոծառայությունների մշակմանը, դուք ցանկանում եք լրացուցիչ արժեք ստանալ գրավոր ծանոթագրություններից: Օրինակ, հիմնվելով RAML/Swagger-ի վրա, դուք կարող եք ստեղծել և՛ հաճախորդի, և՛ սերվերի կոդ հսկայական թվով ծրագրավորման լեզուներով: Կարող եք նաև ավտոմատ կերպով ստանալ փաստաթղթեր միկրոսերվիսի համար և վերբեռնել այն ձեր ծրագրավորող-պորտալում :):

Կառուցվածքային պայմանագրի նկարագրության օրինակ

Ավելի քիչ տարածված է պայմանագրերի նկարագրությունների հիման վրա միկրոծառայությունների փորձարկման պրակտիկան: Եթե ​​գրել եք և՛ անոտացիա, և՛ բաղադրիչ, ապա կարող եք ստեղծել ավտոմատ թեստ, որը ստուգում է ծառայության համապատասխանությունը տարբեր տեսակի մուտքային տվյալների հետ: Արդյո՞ք ծառայությունը վերադարձնում է պատասխանի ծածկագիր, որը նկարագրված չէ ծանոթագրության մեջ: Արդյո՞ք այն կկարողանա ճիշտ մշակել ակնհայտ սխալ տվյալները:

Ավելին, ոչ միայն բուն պայմանագրերի, այլև ծանոթագրությունների վիզուալիզացման գործիքների որակյալ իրականացումը հնարավորություն է տալիս պարզեցնել աշխատանքը միկրոսերվիսի հետ: Այսինքն, եթե ճարտարապետը որակապես նկարագրել է պայմանագիրը, դրա հիման վրա դիզայներներն ու մշակողները ծառայությունը կիրականացնեն այլ ապրանքներում՝ առանց լրացուցիչ ժամանակի ծախսերի։

Լրացուցիչ գործիքները միացնելու համար և՛ RAML-ը, և՛ OAS-ն ունեն ստանդարտով չնախատեսված մետատվյալներ ավելացնելու հնարավորություն (օրինակ, այսպես է արվում OAS-ում).

Ընդհանրապես, միկրոծառայությունների համար պայմանագրերի օգտագործման կրեատիվության շրջանակը հսկայական է... գոնե տեսականորեն:

Ոզնու համեմատությունը օձի հետ

Ներկայումս Acronis-ում առաջնահերթ զարգացման ոլորտը Acronis Cyber ​​պլատֆորմի զարգացումն է: Acronis Cyber ​​​​Platform-ը երրորդ կողմի ծառայությունների ինտեգրման նոր կետեր է Acronis Cyber ​​​​Cloud-ի և գործակալական մասի հետ: Թեև մենք գոհ էինք RAML-ում նկարագրված մեր ներքին API-ներից, API-ի հրապարակման անհրաժեշտությունը կրկին առաջացրեց ընտրության հարցը. ծանոթագրության ո՞ր ստանդարտն է լավագույնս օգտագործել մեր աշխատանքի համար:

Ի սկզբանե թվում էր, թե երկու լուծում կա՝ ամենատարածված զարգացումները RAML-ն ու Swagger-ն էին (կամ OAS): Բայց իրականում պարզվեց, որ կա առնվազն ոչ թե 2 այլընտրանք, այլ 3 կամ ավելի։

Մի կողմից կա RAML-ը` հզոր և արդյունավետ լեզու: Այն լավ է իրականացնում հիերարխիան և ժառանգականությունը, ուստի այս ձևաչափն ավելի հարմար է մեծ ընկերությունների համար, որոնք շատ նկարագրությունների կարիք ունեն, այսինքն՝ ոչ թե մեկ ապրանք, այլ բազմաթիվ միկրոծառայություններ, որոնք ունեն պայմանագրերի ընդհանուր մասեր՝ նույնականացման սխեմաներ, տվյալների նույն տեսակները, սխալների մարմինները: .

Սակայն RAML-ի մշակող Mulesoft-ը միացել է Open API կոնսորցիումին, որը զարգացնում է. Swagger- ը. Հետևաբար, RAML-ը դադարեցրեց իր զարգացումը: Միջոցառման ձևաչափը պատկերացնելու համար պատկերացրեք, որ Linux-ի հիմնական բաղադրիչների սպասարկողները հեռացան Microsoft-ի համար: Այս իրավիճակը նախադրյալներ է ստեղծում Swagger-ի օգտագործման համար, որը դինամիկորեն զարգանում է և վերջին՝ երրորդ տարբերակով, գործնականում հասնում է RAML-ին ճկունության և ֆունկցիոնալության առումով:

Եթե ​​ոչ մի բանի համար...

Ինչպես պարզվում է, ոչ բոլոր բաց կոդով կոմունալ ծառայություններն են թարմացվել OAS 3.0-ին: Go-ում միկրոծառայությունների համար ամենակարևորը հարմարվելու բացակայությունն է լինելու գոռգոռալ ստանդարտի վերջին տարբերակի համար: Այնուամենայնիվ, Swagger 2-ի և Swagger 3-ի միջև տարբերությունն այն է հսկայական. Օրինակ, երրորդ տարբերակում մշակողները.

• Նույնականացման սխեմաների բարելավված նկարագրություն
• ավարտված JSON Schema-ի աջակցություն
• բարելավվել է օրինակներ ավելացնելու հնարավորությունը

Իրավիճակը ծիծաղելի է. ստանդարտ ընտրելիս պետք է դիտարկել RAML, Swagger 2 և Swagger 3 որպես առանձին այլընտրանքներ։ Այնուամենայնիվ, միայն Swagger 2-ն ունի լավ աջակցություն OpenSource գործիքների համար: RAML-ը շատ ճկուն է...և բարդ, և Swagger 3-ը վատ է աջակցվում համայնքի կողմից, այնպես որ դուք պետք է օգտագործեք հատուկ գործիքներ կամ առևտրային լուծումներ, որոնք բավականին թանկ են:

Ավելին, եթե Swagger-ում կան շատ գեղեցիկ հնարավորություններ, օրինակ՝ պատրաստի պորտալը editor.swagger.io, որի վրա կարող եք ներբեռնել անոտացիա և ստանալ դրա վիզուալիզացիան մանրամասն նկարագրությամբ, հղումներով և կապերով, ապա ավելի հիմնարար և ոչ այնքան ընկերական RAML-ի համար նման հնարավորություն չկա։ Այո, դուք կարող եք ինչ-որ բան որոնել GitHub-ում նախագծերի մեջ, գտնել այնտեղ անալոգը և ինքներդ տեղադրել այն: Այնուամենայնիվ, ամեն դեպքում, ինչ-որ մեկը ստիպված կլինի պահպանել պորտալը, որն այնքան էլ հարմար չէ հիմնական օգտագործման կամ փորձարկման կարիքների համար: Բացի այդ, swagger-ն ավելի «անսկզբունքային» է կամ ավելի ազատական. այն կարող է առաջանալ կոդի մեկնաբանություններից, ինչը, իհարկե, հակասում է API-ի առաջին սկզբունքին և չի աջակցվում RAML կոմունալ ծառայություններից որևէ մեկի կողմից:

Ժամանակին մենք սկսեցինք աշխատել RAML-ի հետ՝ որպես ավելի ճկուն լեզվի, և արդյունքում մենք ինքներս ստիպված էինք շատ բան անել։ Օրինակ, նախագծերից մեկն օգտագործում է կոմունալ ճյուղավորումներ միավորի թեստերում, որն աջակցում է միայն RAML 0.8-ին: Այսպիսով, մենք ստիպված եղանք հենակներ ավելացնել, որպեսզի կոմունալը կարողանա «ուտել» RAML 1.0 տարբերակը:

Ձեզ անհրաժեշտ է ընտրել.

Աշխատելով RAML-ի համար լուծումների էկոհամակարգի լրացման վրա՝ մենք եկանք այն եզրակացության, որ մենք պետք է RAML-ը փոխարկենք Swagger 2-ի և իրականացնենք դրա ամբողջ ավտոմատացումը, ստուգումը, փորձարկումը և հետագա օպտիմալացումը: Սա լավ միջոց է օգտագործելու և՛ RAML-ի ճկունությունը, և՛ համայնքի գործիքակազմի աջակցությունը Swagger-ից:

Այս խնդիրը լուծելու համար կան երկու OpenSource գործիքներ, որոնք պետք է ապահովեն պայմանագրի փոխարկում.

1. oas-raml-փոխարկիչ ներկայումս չաջակցվող կոմունալ ծրագիր է: Դրա հետ աշխատելիս մենք հայտնաբերեցինք, որ այն ունի մի շարք խնդիրներ բարդ RAML-ների հետ, որոնք «տարածված» են մեծ թվով ֆայլերի վրա: Այս ծրագիրը գրված է JavaScript-ով և կատարում է շարահյուսական ծառի ռեկուրսիվ անցում: Դինամիկ մուտքագրման պատճառով դժվարանում է հասկանալ այս կոդը, ուստի մենք որոշեցինք ժամանակ չվատնել մեռնող օգտակար հավելվածի համար patches գրելու համար:
2. webapi-վերլուծիչ - գործիք նույն ընկերության կողմից, որը պնդում է, որ պատրաստ է փոխակերպել ամեն ինչ և ամեն ինչ և ցանկացած ուղղությամբ: Մինչ օրս հայտարարվել է աջակցություն RAML 0.8, RAML 1.0 և Swagger 2.0 համար: Այնուամենայնիվ, մեր հետազոտության ժամանակ օգտակարությունը դեռևս կար ՉԱՓԱԶԱՆՑ խոնավ և անօգտագործելի: Մշակողները ստեղծում են մի տեսակ IR, թույլ տալով նրանց ապագայում արագ ավելացնել նոր չափանիշներ: Բայց առայժմ դա պարզապես չի աշխատում:

Եվ դա բոլոր դժվարությունները չէ, որ մենք հանդիպեցինք: Մեր խողովակաշարի քայլերից մեկն այն է, որ ստուգենք, թե արդյոք RAML-ը պահոցից ճիշտ է ճշգրտման համեմատ: Մենք փորձեցինք մի քանի կոմունալ ծառայություններ: Զարմանալի է, որ նրանք բոլորը տարբեր տեղերում հայհոյում էին մեր անոտացիաներին ու բոլորովին այլ վատ խոսքերով։ Եվ ոչ միշտ է կետին :):

Ի վերջո, մենք տեղավորվեցինք արդեն հնացած նախագծի վրա, որը նույնպես ունի մի շարք խնդիրներ (երբեմն այն խափանում է անսպասելիորեն, խնդիրներ է ունենում կանոնավոր արտահայտությունների հետ աշխատելիս): Այսպիսով, մենք չգտանք անվճար գործիքների վրա հիմնված վավերացման և փոխակերպման խնդիրները լուծելու միջոց և որոշեցինք օգտագործել կոմերցիոն կոմունալ ծրագիր: Ապագայում, քանի որ OpenSource գործիքները դառնում են ավելի հասուն, այս խնդիրը կարող է ավելի հեշտ լուծել: Միևնույն ժամանակ, «ավարտելու» աշխատուժը և ժամանակի ծախսերը մեզ ավելի զգալի թվացին, քան կոմերցիոն ծառայության արժեքը։

Ամփոփում

Այսքանից հետո մենք ուզում էինք կիսվել մեր փորձով և նշել, որ նախքան պայմանագրերի նկարագրության գործիք ընտրելը, պետք է հստակ սահմանել, թե ինչ եք ուզում դրանից և ինչ բյուջե եք պատրաստ ներդնել։ Եթե ​​մոռանանք OpenSource-ի մասին, ապա արդեն կան մեծ թվով ծառայություններ և ապրանքներ, որոնք կօգնեն ձեզ ստուգել, ​​վերափոխել և վավերացնել: Բայց դրանք թանկ են, իսկ երբեմն էլ՝ շատ թանկ։ Խոշոր ընկերության համար նման ծախսերը տանելի են, բայց ստարտափի համար դրանք կարող են մեծ բեռ դառնալ։

Որոշեք այն գործիքների հավաքածուն, որոնք դուք կօգտագործեք ավելի ուշ: Օրինակ, եթե ձեզ պարզապես անհրաժեշտ է պայմանագիր ցուցադրել, ապա ավելի հեշտ կլինի օգտագործել Swagger 2-ը, որն ունի գեղեցիկ API, քանի որ RAML-ում դուք պետք է ինքներդ կառուցեք և պահպանեք ծառայությունը։
Որքան շատ առաջադրանքներ ունենաք, այնքան ավելի լայն կլինի գործիքների կարիքը, և դրանք տարբեր են տարբեր հարթակների համար, և ավելի լավ է անմիջապես ծանոթանալ առկա տարբերակներին, որպեսզի ապագայում ձեր ծախսերը նվազագույնի հասցնող ընտրություն կատարեք:

Բայց արժե ընդունել, որ այսօր գոյություն ունեցող բոլոր էկոհամակարգերը անկատար են: Հետևաբար, եթե ընկերությունում կան երկրպագուներ, ովքեր սիրում են աշխատել RAML-ում, քանի որ «այն թույլ է տալիս ավելի ճկուն արտահայտել մտքերը», կամ, ընդհակառակը, նախընտրում են Swagger-ը, քանի որ «ավելի պարզ է», ավելի լավ է թողնել նրանց աշխատանքին։ Նրանք սովոր են դրան և ցանկանում են դա, քանի որ ցանկացած ձևաչափի գործիքները պահանջում են փոփոխություններ ֆայլով:

Ինչ վերաբերում է մեր փորձին, ապա հաջորդ գրառումներում մենք կխոսենք այն մասին, թե ինչ ստատիկ և դինամիկ ստուգումներ ենք անցկացնում՝ հիմնվելով մեր RAML-Swagger ճարտարապետության վրա, ինչպես նաև այն մասին, թե ինչ փաստաթղթեր ենք ստեղծում պայմանագրերից և ինչպես է այդ ամենը աշխատում:

Հարցմանը կարող են մասնակցել միայն գրանցված օգտվողները։ Մուտք գործել, խնդրում եմ:

Ի՞նչ լեզվով եք նշում միկրոսպասարկման պայմանագրերը:

• RAML 0.8

• RAML 1.0

• Կռվարար 2

• OAS3 (aka)

• Նախագիծ

• Այլ

• Չօգտագործելով

Քվեարկել է 100 օգտատեր։ 24 օգտատեր ձեռնպահ է մնացել։

Source: www.habr.com