Mikroservislərin dinamik dünyasında hər şey dəyişə bilər - hər hansı komponent fərqli çərçivələr və arxitekturadan istifadə edərək fərqli dildə yenidən yazıla bilər. Yalnız müqavilələr dəyişməz qalmalıdır ki, daxili metamorfozalardan asılı olmayaraq mikroservis xaricdən daimi olaraq qarşılıqlı əlaqədə ola bilsin. Və bu gün biz müqavilələri təsvir etmək üçün format seçmək problemimizdən danışacağıq və tapdığımız artefaktları paylaşacağıq.
Post hazırlanmışdır и
Mikroservislər. Acronis Cyber Cloud-u inkişaf etdirərkən onlardan qaça bilməyəcəyimizi başa düşdük. Mikroservisin dizaynı isə mikroservis interfeysini təmsil edən müqaviləni rəsmiləşdirmədən mümkün deyil.
Lakin məhsul birdən çox komponentdən ibarət olduqda və müqavilənin hazırlanması müntəzəm fəaliyyətə çevrildikdə, prosesin optimallaşdırılması haqqında düşünməyə başlaya bilməzsiniz. Aydın olur ki, interfeys (müqavilə) və tətbiqetmə (mikroservis) bir-birinə uyğun olmalıdır, müxtəlif komponentlər eyni şeyi eyni şəkildə etməlidir və bütün bu qərarlar üçün mərkəzləşdirilmiş qərar qəbul edilmədən hər bir komanda məcbur olacaq. onları almaq üçün təkrar-təkrar vaxt sərf edin.
Amazon mikroservis diaqramından Werner Vogelis, CTO Amazon
Dilemma nədir? De-fakto, mikroservislərlə qarşılıqlı əlaqə qurmağın iki yolu var - HTTP Rest və Google-dan gRPC. Google-un texnologiya yığınına qapılmaq istəmədiyimiz üçün HTTP Rest-i seçdik. HTTP REST müqavilə annotasiyaları ən çox iki formatdan birində təsvir edilir: RAML və OAS, əvvəllər Swagger kimi tanınır.Ona görə də hər bir inkişaf komandası standartlardan birini seçmək zərurəti ilə üzləşir. Ancaq göründüyü kimi, bu seçimi etmək çox çətin ola bilər.
Annotasiyalar niyə lazımdır?
Annotasiya ona görə lazımdır ki, xarici istifadəçi HTTP interfeysi vasitəsilə xidmətinizlə nə edilə biləcəyini asanlıqla anlaya bilsin. Yəni, əsas səviyyədə annotasiya ən azı mövcud resursların siyahısını, onların HTTP metodlarını, sorğu orqanlarını, parametrlərin siyahısını, tələb olunan və dəstəklənən başlıqların göstəricisini, həmçinin qaytarma kodları və cavab formatlarını ehtiva etməlidir. Müqavilə annotasiyasının son dərəcə vacib elementi onların şifahi təsviridir (“bu sorğu parametrini sorğuya əlavə etsəniz nə olacaq?”, “Hansı halda 400 kodu qaytarılacaq?”)
Bununla belə, çoxlu sayda mikroxidmətlərin yaradılmasına gəldikdə, siz yazılı annotasiyalardan əlavə dəyər çıxarmaq istəyirsiniz. Məsələn, RAML/Swagger əsasında çoxlu sayda proqramlaşdırma dillərində həm müştəri, həm də server kodu yarada bilərsiniz. Siz həmçinin avtomatik olaraq mikroservis üçün sənədləri qəbul edə və onu developer-portalınıza yükləyə bilərsiniz :).
Strukturlaşdırılmış müqavilə təsvirinin nümunəsi
Müqavilə təsvirləri əsasında mikroxidmətlərin sınaqdan keçirilməsi praktikası daha az yayılmışdır. Əgər siz həm annotasiya, həm də komponent yazmısınızsa, onda siz müxtəlif növ daxiletmə məlumatları ilə xidmətin adekvatlığını yoxlayan avtotest yarada bilərsiniz. Xidmət annotasiyada təsvir olunmayan cavab kodunu qaytarırmı? O, açıq-aydın yanlış məlumatları düzgün emal edə biləcəkmi?
Üstəlik, təkcə müqavilələrin deyil, həm də annotasiyaların vizuallaşdırılması üçün alətlərin yüksək keyfiyyətli icrası mikroservislə işi sadələşdirməyə imkan verir. Yəni, memar müqaviləni keyfiyyətcə təsvir edərsə, ona əsaslanaraq, dizaynerlər və tərtibatçılar əlavə vaxt xərcləri olmadan xidməti digər məhsullarda həyata keçirəcəklər.
Əlavə alətləri aktivləşdirmək üçün həm RAML, həm də OAS standartda nəzərdə tutulmayan metadata əlavə etmək imkanına malikdir ().
Ümumiyyətlə, mikroservislər üçün müqavilələrdən istifadədə yaradıcılıq sahəsi böyükdür... ən azı nəzəri cəhətdən.
Kirpinin ilanla müqayisəsi
Hazırda Acronis-də prioritet inkişaf sahəsi Acronis Kiber Platformasının inkişafıdır. Acronis Cyber Platformu üçüncü tərəf xidmətlərinin Acronis Cyber Cloud və agent hissəsi ilə inteqrasiyasının yeni nöqtələridir. RAML-də təsvir olunan daxili API-lərimizdən məmnun olsaq da, API-ni dərc etmək zərurəti yenidən seçim sualını gündəmə gətirdi: işimiz üçün hansı annotasiya standartından istifadə etmək daha yaxşıdır?
Əvvəlcə iki həll yolu olduğu görünürdü - ən çox yayılmış inkişaflar RAML və Swagger (və ya OAS) idi. Amma əslində məlum oldu ki, ən azı 2 deyil, 3 və ya daha çox alternativ var.
Bir tərəfdən RAML var - güclü və səmərəli dil. O, iyerarxiya və varisliyi yaxşı həyata keçirir, ona görə də bu format çoxlu təsvirlərə ehtiyacı olan böyük şirkətlər üçün daha uyğundur - yəni bir məhsul deyil, müqavilələrin ümumi hissələri olan bir çox mikroservislər - autentifikasiya sxemləri, eyni məlumat növləri, xəta orqanları. .
Lakin RAML-in tərtibatçısı Mulesoft, inkişaf edən Open API konsorsiumuna qoşuldu. . Buna görə də RAML öz inkişafını dayandırdı. Tədbirin formatını təsəvvür etmək üçün təsəvvür edin ki, əsas Linux komponentlərinin baxıcıları Microsoft-da işləmək üçün ayrılıblar. Bu vəziyyət dinamik inkişaf edən və ən son - üçüncü versiyada çeviklik və funksionallıq baxımından RAML-i praktiki olaraq tutan Swagger-dən istifadə üçün ilkin şərtlər yaradır.
Bir şey üçün olmasa ...
Göründüyü kimi, bütün açıq mənbəli kommunal proqramlar OAS 3.0-a yenilənməyib. Go-da mikroservislər üçün ən vacib şey uyğunlaşmanın olmaması olacaq standartın ən son versiyası üçün. Bununla belə, Swagger 2 və Swagger 3 arasındakı fərq budur . Məsələn, üçüncü versiyada tərtibatçılar:
- autentifikasiya sxemlərinin təkmilləşdirilmiş təsviri
- JSON Sxema dəstəyi
- nümunələr əlavə etmək qabiliyyətini təkmilləşdirdi
Vəziyyət gülməlidir: standart seçərkən RAML, Swagger 2 və Swagger 3-ü ayrıca alternativ kimi nəzərdən keçirmək lazımdır. Bununla belə, yalnız Swagger 2 OpenSource alətləri üçün yaxşı dəstəyə malikdir. RAML çox çevikdir... və mürəkkəbdir və Swagger 3 cəmiyyət tərəfindən zəif dəstəklənir, ona görə də siz mülkiyyət alətləri və ya kommersiya həllərindən istifadə etməli olacaqsınız, hansı ki, onlar olduqca bahalıdır.
Üstəlik, Swagger-də bir çox gözəl xüsusiyyətlər varsa, məsələn, hazır portal , bir annotasiya yükləyə və onun ətraflı təsviri, bağlantıları və əlaqələri ilə vizuallaşdırılmasını əldə edə bilərsiniz, onda daha fundamental və daha az dost RAML üçün belə bir fürsət yoxdur. Bəli, GitHub-da layihələr arasında nəsə axtara, orada analoq tapıb özünüz yerləşdirə bilərsiniz. Bununla belə, hər halda, kimsə əsas istifadə və ya sınaq ehtiyacları üçün o qədər də əlverişli olmayan portalı saxlamalı olacaq. Bundan əlavə, ləzzət daha "prinsipsiz" və ya daha liberaldır - koddakı şərhlərdən yarana bilər, bu, əlbəttə ki, API-nin birinci prinsipinə ziddir və RAML kommunallarının heç biri tərəfindən dəstəklənmir.
Bir vaxtlar biz daha çevik bir dil olaraq RAML ilə işləməyə başladıq və nəticədə özümüz çox şey etməli olduq. Məsələn, layihələrdən biri köməkçi proqramdan istifadə edir yalnız RAML 0.8-i dəstəkləyən vahid testlərində. Beləliklə, köməkçi proqramın RAML 1.0 versiyasını “yeyə bilməsi” üçün qoltuqağaqları əlavə etməli olduq.
Seçmək lazımdır?
RAML üçün həllərin ekosistemini tamamlamaq üzərində işləyərək belə bir nəticəyə gəldik ki, RAML-i Swagger 2-ə çevirməli və orada bütün avtomatlaşdırma, yoxlama, sınaq və sonrakı optimallaşdırma işləri aparmalıyıq. Bu, həm RAML-in çevikliyindən, həm də Swagger-in icma alətləri dəstəyindən istifadə etmək üçün yaxşı bir yoldur.
Bu problemi həll etmək üçün müqavilənin çevrilməsini təmin edən iki OpenSource aləti var:
- hazırda dəstəklənməyən köməkçi proqramdır. Onunla işləyərkən biz aşkar etdik ki, onun çoxlu sayda fayl üzərində “yayılan” mürəkkəb RAML-lərlə bağlı bir sıra problemləri var. Bu proqram JavaScript-də yazılmışdır və sintaksis ağacının rekursiv keçidini həyata keçirir. Dinamik yazıya görə, bu kodu başa düşmək çətinləşir, buna görə də ölməkdə olan bir yardım proqramı üçün yamaqlar yazmağa vaxt itirməməyə qərar verdik.
- - hər şeyi və hər şeyi və istənilən istiqamətə çevirməyə hazır olduğunu iddia edən eyni şirkətdən bir alət. Bu günə qədər RAML 0.8, RAML 1.0 və Swagger 2.0 üçün dəstək elan edilib. Bununla belə, araşdırmamız zamanı kommunal hələ də idi nəm və istifadəyə yararsızdır. Tərtibatçılar bir növ yaradır , onlara gələcəkdə yeni standartlar əlavə etməyə imkan verir. Ancaq bu günə qədər sadəcə işləmir.
Və qarşılaşdığımız bütün çətinliklər bu deyil. Boru kəmərimizdəki addımlardan biri depodan RAML-in spesifikasiyaya nisbətən düzgün olduğunu yoxlamaqdır. Bir neçə kommunal sınadıq. Qəribədir ki, onlar bizim annotasiyalarımızı müxtəlif yerlərdə və tamam başqa pis sözlərlə söyüblər. Həmişə nöqtəyə deyil :).
Sonda biz artıq köhnəlmiş bir layihə üzərində qərarlaşdıq, onun da bir sıra problemləri var (bəzən o, təsadüfən çökür, müntəzəm ifadələrlə işləyərkən problemlər yaranır). Beləliklə, biz pulsuz alətlər əsasında təsdiqləmə və konvertasiya problemlərini həll etmək üçün bir yol tapmadıq və kommersiya yardım proqramından istifadə etmək qərarına gəldik. Gələcəkdə, OpenSource alətləri daha yetkinləşdikcə, bu problemi həll etmək daha asan ola bilər. Bu arada, "bitirmə" üçün əmək və vaxt xərcləri bizə kommersiya xidmətinin qiymətindən daha əhəmiyyətli görünürdü.
Nəticə
Bütün bunlardan sonra biz öz təcrübəmizi bölüşmək və qeyd etmək istədik ki, müqavilələri təsvir etmək üçün alət seçməzdən əvvəl ondan nə istədiyinizi və hansı büdcəyə sərmayə qoymağa hazır olduğunuzu dəqiq müəyyənləşdirməlisiniz. OpenSource haqqında unutsaq, yoxlamaq, çevirmək və təsdiqləməkdə sizə kömək edəcək çoxlu sayda xidmət və məhsul artıq mövcuddur. Amma onlar bahadır, bəzən isə çox bahadır. Böyük bir şirkət üçün bu cür xərclər dözümlüdür, lakin başlanğıc üçün böyük bir yükə çevrilə bilər.
Daha sonra istifadə edəcəyiniz alətlər dəstini müəyyənləşdirin. Məsələn, sadəcə müqaviləni göstərmək lazımdırsa, gözəl API-yə malik olan Swagger 2-dən istifadə etmək daha asan olacaq, çünki RAML-də xidməti özünüz qurmalı və ona qulluq etməli olacaqsınız.
Tapşırıqlarınız nə qədər çox olsa, alətlərə ehtiyac bir o qədər geniş olacaq və onlar müxtəlif platformalar üçün fərqlidir və gələcəkdə xərclərinizi minimuma endirən seçim etmək üçün dərhal mövcud versiyalarla tanış olmaq daha yaxşıdır.
Ancaq etiraf etmək lazımdır ki, bu gün mövcud olan bütün ekosistemlər qeyri-kamildir. Buna görə də, əgər şirkətdə “fikirləri daha çevik ifadə etməyə imkan verir” deyə RAML-də işləməyi sevən pərəstişkarları varsa və ya əksinə, “daha aydındır” deyə Swagger-ə üstünlük verirlərsə, ən yaxşısı onları işləmək üçün buraxmaqdır. Onlar nə olduqlarına öyrəşiblər və bunu istəyirlər, çünki hər hansı bir formatın alətləri fayl ilə modifikasiya tələb edir.
Təcrübəmizə gəlincə, növbəti yazılarda RAML-Swagger arxitekturamız əsasında hansı statik və dinamik yoxlamalar apardığımızdan, həmçinin müqavilələrdən hansı sənədləri yaratdığımızdan və bunların hamısının necə işlədiyindən danışacağıq.
Sorğuda yalnız qeydiyyatdan keçmiş istifadəçilər iştirak edə bilər. xahiş edirəm.
Mikroservis müqavilələrini şərh etmək üçün hansı dildən istifadə edirsiniz?
-
RAML 0.8
-
RAML 1.0
-
Swagger 2
-
OAS3 (aka)
-
Blueprint
-
Digər
-
İstifadə etmir
100 istifadəçi səs verib. 24 istifadəçi bitərəf qalıb.
Mənbə: www.habr.com