ეს არის RAML თუ OAS (Swagger)?

მიკროსერვისების დინამიურ სამყაროში ყველაფერი შეიძლება შეიცვალოს - ნებისმიერი კომპონენტი შეიძლება გადაიწეროს სხვა ენაზე, სხვადასხვა ჩარჩოებისა და არქიტექტურის გამოყენებით. მხოლოდ კონტრაქტები უნდა დარჩეს უცვლელი, რათა მიკროსერვისს შეეძლოს გარედან ურთიერთქმედება მუდმივ საფუძველზე, მიუხედავად შიდა მეტამორფოზებისა. დღეს კი ვისაუბრებთ კონტრაქტების აღწერისთვის ფორმატის არჩევის პრობლემაზე და გავაზიარებთ ჩვენს მიერ ნაპოვნი არტეფაქტებს.

პოსტი მომზადებულია ანა მელეხოვა и ვლადიმერ ლაპატინი

მიკროსერვისები. Acronis Cyber ​​Cloud-ის შემუშავებისას მივხვდით, რომ მათ ვერ გავექცევით. მიკროსერვისის დაპროექტება კი შეუძლებელია კონტრაქტის ფორმალიზების გარეშე, რომელიც წარმოადგენს მიკროსერვისის ინტერფეისს.

მაგრამ როდესაც პროდუქტი შეიცავს ერთზე მეტ კომპონენტს და კონტრაქტის შემუშავება რეგულარულ საქმიანობად იქცევა, თქვენ არ შეგიძლიათ არ დაიწყოთ ფიქრი პროცესის ოპტიმიზაციაზე. აშკარა ხდება, რომ ინტერფეისი (კონტრაქტი) და იმპლემენტაცია (მიკროსერვისი) უნდა ემთხვეოდეს ერთმანეთს, რომ სხვადასხვა კომპონენტმა უნდა გააკეთოს ერთი და იგივე მოქმედებები ერთნაირად და რომ ყველა ამ გადაწყვეტილების ცენტრალიზებული გადაწყვეტილების მიღების გარეშე, თითოეული გუნდი იძულებული იქნება. გაატარეთ დრო ისევ და ისევ მათ მისაღებად.

ამაზონის მიკროსერვისების დიაგრამა ტვიტი ვერნერ ვოგელისი, ამაზონის CTO
რა არის დილემა? დე ფაქტო, მიკროსერვისებთან ურთიერთქმედების ორი გზა არსებობს - HTTP Rest და gRPC Google-ისგან. არ გვსურს Google-ის ტექნოლოგიის დასტაში ჩაბმა, ჩვენ ავირჩიეთ HTTP Rest. HTTP REST კონტრაქტის ანოტაციები ყველაზე ხშირად აღწერილია ერთ-ერთ ორ ფორმატში: RAML და OAS, ადრე ცნობილი როგორც Swagger. ამიტომ, განვითარების ყველა გუნდს აწყდება ერთ-ერთი სტანდარტის არჩევის აუცილებლობა. მაგრამ როგორც ირკვევა, ამ არჩევანის გაკეთება შეიძლება ძალიან რთული იყოს.

რატომ არის საჭირო ანოტაციები?

ანოტაცია საჭიროა იმისათვის, რომ გარე მომხმარებელმა ადვილად გაარკვიოს, რა შეიძლება გაკეთდეს თქვენს სერვისთან მისი HTTP ინტერფეისის საშუალებით. ანუ, საბაზისო დონეზე, ანოტაცია უნდა შეიცავდეს მინიმუმ ხელმისაწვდომი რესურსების ჩამონათვალს, მათ HTTP მეთოდებს, მოთხოვნის ორგანოებს, პარამეტრების ჩამონათვალს, საჭირო და მხარდაჭერილი სათაურების მითითებას, აგრეთვე დაბრუნების კოდებსა და პასუხების ფორმატებს. კონტრაქტის ანოტაციის უაღრესად მნიშვნელოვანი ელემენტია მათი სიტყვიერი აღწერა („რა მოხდება, თუ ამ მოთხოვნის პარამეტრს დაამატებთ მოთხოვნას?“, „რა შემთხვევაში დაბრუნდება კოდი 400?“)

თუმცა, როდესაც საქმე ეხება დიდი რაოდენობით მიკროსერვისების განვითარებას, თქვენ გსურთ მიიღოთ დამატებითი მნიშვნელობა დაწერილი ანოტაციებიდან. მაგალითად, RAML/Swagger-ზე დაყრდნობით, შეგიძლიათ შექმნათ როგორც კლიენტის, ასევე სერვერის კოდი პროგრამირების ენების დიდ რაოდენობაზე. თქვენ ასევე შეგიძლიათ ავტომატურად მიიღოთ დოკუმენტაცია მიკროსერვისისთვის და ატვირთოთ იგი თქვენს დეველოპერ-პორტალზე :).

სტრუქტურირებული ხელშეკრულების აღწერილობის მაგალითი

ნაკლებად გავრცელებულია მიკროსერვისების ტესტირების პრაქტიკა კონტრაქტის აღწერილობების საფუძველზე. თუ თქვენ დაწერეთ როგორც ანოტაცია, ასევე კომპონენტი, მაშინ შეგიძლიათ შექმნათ ავტომატური ტესტი, რომელიც ამოწმებს სერვისის ადეკვატურობას სხვადასხვა ტიპის შეყვანის მონაცემებით. აბრუნებს სერვისი პასუხის კოდს, რომელიც არ არის აღწერილი ანოტაციაში? შეძლებს თუ არა აშკარად არასწორი მონაცემების სწორად დამუშავებას?

უფრო მეტიც, არა მხოლოდ თავად კონტრაქტების, არამედ ანოტაციების ვიზუალიზაციის ინსტრუმენტების მაღალი ხარისხის განხორციელება შესაძლებელს ხდის მიკროსერვისთან მუშაობის გამარტივებას. ანუ, თუ არქიტექტორმა ხარისხობრივად აღწერა კონტრაქტი, მასზე დაყრდნობით, დიზაინერები და დეველოპერები განახორციელებენ მომსახურებას სხვა პროდუქტებში დამატებითი დროის ხარჯების გარეშე.

დამატებითი ხელსაწყოების ჩასართავად, როგორც RAML-ს, ასევე OAS-ს აქვთ უნარი დაამატონ მეტამონაცემები, რომლებიც არ არის გათვალისწინებული სტანდარტით (მაგალითად, ასე კეთდება OAS-ში).

ზოგადად, კრეატიულობის სფერო მიკროსერვისებისთვის კონტრაქტების გამოყენებისას უზარმაზარია... თეორიულად მაინც.

ზღარბის შედარება გველთან

ამჟამად Acronis-ის განვითარების პრიორიტეტული სფეროა Acronis კიბერ პლატფორმის განვითარება. Acronis კიბერ პლატფორმა არის მესამე მხარის სერვისების ინტეგრაციის ახალი პუნქტები Acronis Cyber ​​Cloud-თან და აგენტურ ნაწილთან. მიუხედავად იმისა, რომ ჩვენ კმაყოფილი ვიყავით RAML-ში აღწერილი ჩვენი შიდა API-ებით, API-ს გამოქვეყნების აუცილებლობამ კვლავ წამოჭრა არჩევანის კითხვა: რომელი ანოტაციის სტანდარტია საუკეთესო გამოსაყენებლად ჩვენი სამუშაოსთვის?

თავდაპირველად, ჩანდა, რომ არსებობდა ორი გამოსავალი - ყველაზე გავრცელებული განვითარება იყო RAML და Swagger (ან OAS). მაგრამ სინამდვილეში აღმოჩნდა, რომ არსებობს მინიმუმ არა 2 ალტერნატივა, არამედ 3 ან მეტი.

ერთის მხრივ არის RAML - ძლიერი და ეფექტური ენა. ის კარგად ახორციელებს იერარქიას და მემკვიდრეობას, ამიტომ ეს ფორმატი უფრო შესაფერისია მსხვილი კომპანიებისთვის, რომლებსაც სჭირდებათ ბევრი აღწერა - ანუ არა ერთი პროდუქტი, არამედ მრავალი მიკროსერვისი, რომლებსაც აქვთ კონტრაქტების საერთო ნაწილები - ავთენტიფიკაციის სქემები, მონაცემთა იგივე ტიპები, შეცდომების ორგანოები. .

მაგრამ RAML-ის დეველოპერი, Mulesoft, შეუერთდა Open API კონსორციუმს, რომელიც ავითარებს შაგრერი. ამიტომ RAML-მა შეაჩერა მისი განვითარება. ღონისძიების ფორმატის წარმოსადგენად, წარმოიდგინეთ, რომ Linux-ის ძირითადი კომპონენტების შემსრულებლები გაემგზავრნენ სამუშაოდ Microsoft-ისთვის. ეს ვითარება ქმნის Swagger-ის გამოყენების წინაპირობებს, რომელიც დინამიურად ვითარდება და უახლესი - მესამე ვერსიით - მოქნილობისა და ფუნქციონალურობის თვალსაზრისით პრაქტიკულად ემთხვევა RAML-ს.

ერთი რამ რომ არა...

როგორც ირკვევა, ყველა ღია კოდის პროგრამა არ არის განახლებული OAS 3.0-ზე. Go-ში მიკროსერვისებისთვის ყველაზე კრიტიკული იქნება ადაპტაციის ნაკლებობა წადი-მტვრევა სტანდარტის უახლესი ვერსიისთვის. თუმცა, განსხვავება Swagger 2-სა და Swagger 3-ს შორის არის უზარმაზარი. მაგალითად, მესამე ვერსიაში დეველოპერები:

• ავტორიზაციის სქემების გაუმჯობესებული აღწერა
• დაასრულა JSON სქემის მხარდაჭერა
• განახლებულია მაგალითების დამატების შესაძლებლობა

სიტუაცია სასაცილოა: სტანდარტის არჩევისას, თქვენ უნდა გაითვალისწინოთ 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-ში და ასრულებს სინტაქსის ხის რეკურსიულ გადაკვეთას. დინამიური აკრეფის გამო, ძნელი ხდება ამ კოდის გაგება, ამიტომ გადავწყვიტეთ, არ დავკარგოთ დრო მომაკვდავი უტილიტასთვის პატჩების დაწერაში.
2. ვებაპი-პარსერი - ინსტრუმენტი იმავე კომპანიისგან, რომელიც აცხადებს, რომ მზად არის გადაიყვანოს ყველაფერი და ყველაფერი და ნებისმიერი მიმართულებით. დღეისათვის გამოცხადდა მხარდაჭერა 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 მომხმარებელმა თავი შეიკავა.

წყარო: www.habr.com