Микро үйлчилгээний динамик ертөнцөд юу ч өөрчлөгдөж болно - аливаа бүрэлдэхүүн хэсгийг өөр хэлээр, өөр хүрээ, архитектур ашиглан дахин бичиж болно. Зөвхөн гэрээнүүд өөрчлөгдөхгүй байх ёстой бөгөөд ингэснээр дотоод метаморфозоос үл хамааран микро үйлчилгээ нь гаднаас байнгын харилцан үйлчлэлцэх боломжтой болно. Өнөөдөр бид гэрээг дүрслэх хэлбэрийг сонгох асуудлынхаа талаар ярилцаж, олсон олдворуудаа хуваалцах болно.
Нийтлэл бэлдсэн и
Бичил үйлчилгээ. Acronis Cyber Cloud-ийг хөгжүүлэхдээ бид тэднээс зугтаж чадахгүй гэдгээ ойлгосон. Мөн бичил үйлчилгээний интерфейсийг төлөөлдөг гэрээг албан ёсны болгохгүйгээр бичил үйлчилгээг зохион бүтээх боломжгүй юм.
Гэвч бүтээгдэхүүн нь нэгээс олон бүрэлдэхүүн хэсгийг агуулж, гэрээ боловсруулах нь байнгын үйл ажиллагаа болсон үед та үйл явцыг оновчтой болгох талаар бодохгүй байхын аргагүй юм. Интерфейс (гэрээ) ба хэрэгжилт (микросервис) нь хоорондоо таарч байх ёстой, өөр өөр бүрэлдэхүүн хэсгүүд ижил зүйлийг ижил аргаар хийх ёстой бөгөөд эдгээр бүх шийдвэрийг төвлөрсөн шийдвэр гаргахгүйгээр баг бүр өөр өөр байх ёстой нь тодорхой болж байна. тэднийг авахын тулд дахин дахин цаг зарцуулдаг.
Амазоны микро үйлчилгээний диаграмаас Werner Vogelis, CTO Amazon
Ямар асуудал байна вэ? Үнэн хэрэгтээ микро үйлчилгээтэй харилцах хоёр арга байдаг - HTTP Rest болон Google-ийн gRPC. Бид Google-ийн технологийн стект автахыг хүсээгүй тул HTTP Rest-ийг сонгосон. HTTP REST гэрээний тайлбарыг ихэвчлэн хоёр форматын аль нэгээр тайлбарладаг: RAML болон OAS, өмнө нь Swagger. Иймээс хөгжүүлэлтийн баг бүр стандартуудын аль нэгийг сонгох шаардлагатай тулгардаг. Гэхдээ энэ сонголтыг хийхэд маш хэцүү байх болно.
Яагаад тэмдэглэгээ хэрэгтэй вэ?
Тэмдэглэгээ нь гадны хэрэглэгч HTTP интерфэйсээр дамжуулан таны үйлчилгээг юу хийж болохыг хялбархан олж мэдэхийн тулд шаардлагатай. Өөрөөр хэлбэл, үндсэн түвшинд тэмдэглэгээ нь дор хаяж боломжтой нөөцийн жагсаалт, тэдгээрийн HTTP аргууд, хүсэлтийн биетүүд, параметрүүдийн жагсаалт, шаардлагатай болон дэмжигдсэн толгойнуудын заалт, түүнчлэн буцах код, хариултын форматыг агуулсан байх ёстой. Гэрээний тайлбарын маш чухал элемент бол тэдний аман тайлбар юм ("хэрэв та хүсэлтэд энэ асуулгын параметрийг нэмбэл юу болох вэ?", "Ямар тохиолдолд 400 кодыг буцааж өгөх вэ?")
Гэсэн хэдий ч, олон тооны микро үйлчилгээг хөгжүүлэх тухайд та бичсэн тайлбараас нэмэлт үнэ цэнийг гаргаж авахыг хүсч байна. Жишээлбэл, RAML/Swagger дээр үндэслэн та маш олон тооны програмчлалын хэлээр клиент болон серверийн кодыг үүсгэж болно. Та мөн бичил үйлчилгээний баримт бичгийг автоматаар хүлээн авч, хөгжүүлэгч порталдаа байршуулах боломжтой :).
Бүтэцлэгдсэн гэрээний тайлбарын жишээ
Гэрээний тайлбар дээр үндэслэн бичил үйлчилгээг турших явдал бага түгээмэл байдаг. Хэрэв та тайлбар болон бүрэлдэхүүн хэсгийн аль алиныг нь бичсэн бол янз бүрийн төрлийн оролтын өгөгдлөөр үйлчилгээний хүрэлцээг шалгах автомат тест үүсгэж болно. Үйлчилгээ нь тайлбарт тайлбарлаагүй хариултын кодыг буцаадаг уу? Энэ нь илт буруу өгөгдлийг зөв боловсруулж чадах уу?
Түүгээр ч зогсохгүй, зөвхөн гэрээ байгуулаад зогсохгүй тэмдэглэгээг дүрслэх хэрэгслүүдийг чанарын өндөр түвшинд хэрэгжүүлэх нь бичил үйлчилгээтэй ажиллах ажлыг хялбарчлах боломжийг олгодог. Өөрөөр хэлбэл, хэрэв архитектор гэрээг өндөр чанартайгаар тайлбарласан бол түүнд үндэслэн дизайнерууд болон хөгжүүлэгчид нэмэлт цаг хугацаа зарцуулахгүйгээр үйлчилгээг бусад бүтээгдэхүүнд хэрэгжүүлэх болно.
Нэмэлт хэрэгслийг идэвхжүүлэхийн тулд RAML болон OAS хоёулаа стандартад заагаагүй мета өгөгдлийг нэмэх боломжтой ().
Ерөнхийдөө бичил үйлчилгээний гэрээг ашиглах бүтээлч байдлын цар хүрээ асар том юм ... наад зах нь онолын хувьд.
Зараа могойтой харьцуулах
Одоогийн байдлаар Acronis-ийн хөгжлийн тэргүүлэх чиглэл бол Acronis кибер платформыг хөгжүүлэх явдал юм. Acronis Cyber Platform нь Acronis Cyber Cloud болон агент хэсэгтэй гуравдагч талын үйлчилгээг нэгтгэх шинэ цэгүүд юм. Хэдийгээр бид RAML-д тайлбарласан дотоод API-ууддаа сэтгэл хангалуун байсан ч API-г дахин нийтлэх хэрэгцээ шаардлагаас үүдэн сонголт хийх асуулт гарч ирэв: бидний ажилд аль тэмдэглэгээний стандартыг ашиглах нь дээр вэ?
Эхэндээ хоёр шийдэл байгаа юм шиг санагдаж байсан - хамгийн түгээмэл хөгжүүлэлт бол RAML ба Swagger (эсвэл OAS) юм. Гэвч үнэн хэрэгтээ дор хаяж 2 биш, 3 ба түүнээс дээш хувилбарууд байдаг нь тогтоогдсон.
Нэг талаас RAML байдаг - хүчирхэг, үр дүнтэй хэл. Энэ нь шатлал, өв залгамжлалыг сайн хэрэгжүүлдэг тул энэ формат нь маш олон тайлбар шаарддаг томоохон компаниудад илүү тохиромжтой, өөрөөр хэлбэл нэг бүтээгдэхүүн биш, харин гэрээний нийтлэг хэсгүүдтэй олон бичил үйлчилгээнүүд - баталгаажуулалтын схем, ижил өгөгдлийн төрөл, алдааны биетүүд. .
Гэхдээ RAML-ийн хөгжүүлэгч Mulesoft нь хөгжиж буй Open API консорциумд нэгдсэн. . Тиймээс RAML хөгжлийг зогсоосон. Үйл явдлын форматыг төсөөлөхийн тулд Линуксийн үндсэн бүрэлдэхүүн хэсгүүдийн засварчид Microsoft-д ажиллахаар явсан гэж төсөөлөөд үз дээ. Энэ нөхцөл байдал нь динамикаар хөгжиж байгаа Swagger-ийг ашиглах урьдчилсан нөхцөлийг бүрдүүлдэг бөгөөд хамгийн сүүлийн үеийн гурав дахь хувилбар нь уян хатан байдал, функциональ байдлын хувьд RAML-ийг бараг гүйцэж чаддаг.
Хэрэв нэг зүйл биш бол ...
Үүнээс харахад бүх нээлттэй эхийн хэрэгслүүд OAS 3.0 болгон шинэчлэгдээгүй байна. Go дахь микро үйлчилгээний хувьд хамгийн чухал зүйл бол дасан зохицох чадваргүй байх болно стандартын хамгийн сүүлийн хувилбарын хувьд. Гэсэн хэдий ч Swagger 2 болон Swagger 3 хоёрын ялгаа нь . Жишээлбэл, гурав дахь хувилбарт хөгжүүлэгчид:
- баталгаажуулалтын схемүүдийн сайжруулсан тайлбар
- JSON схемийн дэмжлэг
- жишээ нэмэх чадварыг сайжруулсан
Нөхцөл байдал инээдтэй байна: стандартыг сонгохдоо та RAML, Swagger 2, Swagger 3-ийг тусдаа хувилбар болгон авч үзэх хэрэгтэй. Гэсэн хэдий ч зөвхөн Swagger 2 нь OpenSource хэрэгслийг сайн дэмждэг. RAML нь маш уян хатан бөгөөд нарийн төвөгтэй бөгөөд Swagger 3 нь олон нийтийн дэмжлэг муутай тул та өмчийн хэрэгсэл эсвэл арилжааны шийдлүүдийг ашиглах хэрэгтэй болно, энэ нь нэлээд үнэтэй байдаг.
Түүнээс гадна Swagger-д бэлэн портал гэх мэт олон сайхан боломжууд байвал , үүн дээр та тайлбарыг байршуулж, түүний дүрслэлийг дэлгэрэнгүй тайлбар, холбоос, холболтоор авах боломжтой бол илүү суурь, ээлтэй RAML-ийн хувьд ийм боломж байхгүй. Тийм ээ, та GitHub дээрх төслүүдээс ямар нэг зүйлийг хайж, аналогийг нь олж, өөрөө байрлуулж болно. Гэсэн хэдий ч ямар ч тохиолдолд хэн нэгэн порталыг хадгалах шаардлагатай болно, энэ нь үндсэн хэрэглээ эсвэл туршилтын хэрэгцээнд тийм ч тохиромжтой биш юм. Нэмж дурдахад, swagger нь илүү "зарчимгүй" эсвэл илүү чөлөөтэй байдаг - үүнийг кодын тайлбараас үүсгэж болох бөгөөд энэ нь мэдээжийн хэрэг API-ийн эхний зарчимтай зөрчилддөг бөгөөд RAML хэрэгслүүдийн аль нь ч дэмжигддэггүй.
Нэгэн цагт бид RAML хэлийг илүү уян хатан хэл болгон ажиллаж эхэлсэн бөгөөд үүний үр дүнд бид маш олон зүйлийг өөрсдөө хийх шаардлагатай болсон. Жишээлбэл, төслүүдийн аль нэг нь хэрэгслийг ашигладаг Зөвхөн RAML 0.8-ийг дэмждэг нэгжийн туршилтуудад. Тиймээс бид RAML 1.0 хувилбарыг "идэх" тул таяг нэмэх шаардлагатай болсон.
Та сонгох хэрэгтэй юу?
RAML-ийн шийдлүүдийн экосистемийг дуусгахаар ажилласны дараа бид RAML-ийг Swagger 2 болгон хөрвүүлж, бүх автоматжуулалт, баталгаажуулалт, туршилт, дараагийн оновчлолыг хийх хэрэгтэй гэсэн дүгнэлтэд хүрсэн. Энэ нь RAML-ийн уян хатан байдал болон Swagger-ийн олон нийтийн хэрэгслийн дэмжлэгийг хоёуланг нь ашиглах сайн арга юм.
Энэ асуудлыг шийдэхийн тулд гэрээний хөрвүүлэлтийг хангах хоёр OpenSource хэрэгсэл байдаг:
- нь одоогоор дэмжигдээгүй хэрэгсэл юм. Түүнтэй ажиллах явцад бид олон тооны файлууд дээр "тархсан" нарийн төвөгтэй RAML-уудтай холбоотой хэд хэдэн асуудал байгааг олж мэдсэн. Энэ програм нь JavaScript дээр бичигдсэн бөгөөд синтакс модны рекурсив хөдөлгөөнийг гүйцэтгэдэг. Динамик бичихийн улмаас энэ кодыг ойлгоход хэцүү болж байгаа тул бид үхэж буй хэрэгслийн засваруудыг бичихэд цаг алдахгүй байхаар шийдсэн.
- - юуг ч, юуг ч, ямар ч чиглэлд хөрвүүлэхэд бэлэн гэж хэлдэг ижил компанийн хэрэгсэл. Өнөөдрийг хүртэл RAML 0.8, RAML 1.0 болон Swagger 2.0-д дэмжлэг үзүүлэхээ зарласан. Гэсэн хэдий ч, бидний судалгаа хийх үед энэ хэрэгсэл хэвээр байсан чийгтэй, ашиглах боломжгүй. Хөгжүүлэгчид нэг төрлийг бий болгодог , ирээдүйд шинэ стандартуудыг хурдан нэмэх боломжийг тэдэнд олгоно. Гэхдээ өнөөг хүртэл энэ нь зүгээр л ажиллахгүй байна.
Энэ нь бидний тулгарсан бүх бэрхшээл биш юм. Манай дамжуулах хоолойн нэг алхам бол репозитороос авсан RAML нь техникийн үзүүлэлттэй харьцуулахад зөв эсэхийг шалгах явдал юм. Бид хэд хэдэн хэрэгслийг туршиж үзсэн. Гайхалтай нь тэд бүгд өөр өөр газар, шал өөр муухай үгээр бидний тайлбарыг харааж байсан. Үргэлж цэг дээр биш :).
Эцэст нь бид хуучирсан төсөл дээр шийдсэн бөгөөд энэ нь бас хэд хэдэн асуудалтай байдаг (заримдаа энэ нь гэнэт унадаг, ердийн илэрхийлэлтэй ажиллахад асуудал гардаг). Тиймээс бид үнэ төлбөргүй хэрэгсэл дээр үндэслэн баталгаажуулах, хөрвүүлэх асуудлыг шийдэх арга замыг олж чадаагүй бөгөөд арилжааны хэрэгслийг ашиглахаар шийдсэн. Ирээдүйд, OpenSource хэрэгслүүд илүү боловсронгуй болох тусам энэ асуудлыг шийдвэрлэхэд хялбар болж магадгүй юм. Энэ хооронд "дуусгах" хөдөлмөр, цаг хугацааны зардал нь арилжааны үйлчилгээний зардлаас илүү чухал мэт санагдсан.
дүгнэлт
Энэ бүхний дараа бид өөрсдийн туршлагаа хуваалцахыг хүссэн бөгөөд гэрээг тайлбарлах хэрэгслийг сонгохын өмнө та үүнээс юу хүсч байгаагаа, ямар төсөв хөрөнгө оруулах хүсэлтэй байгаагаа тодорхой тодорхойлох хэрэгтэй. Хэрэв бид OpenSource-ийг мартвал танд шалгах, хөрвүүлэх, баталгаажуулахад туслах олон тооны үйлчилгээ, бүтээгдэхүүн аль хэдийн бий болсон. Гэхдээ тэд үнэтэй, заримдаа маш үнэтэй байдаг. Томоохон компанийн хувьд ийм зардлыг тэвчих боломжтой боловч гарааны бизнест энэ нь том ачаа болж хувирдаг.
Дараа нь ашиглах хэрэгслүүдээ тодорхойл. Жишээлбэл, хэрэв та зүгээр л гэрээг харуулах шаардлагатай бол RAML дээр та үйлчилгээг өөрөө бүтээж, засвар үйлчилгээ хийх шаардлагатай тул үзэсгэлэнтэй API-тай Swagger 2-г ашиглах нь илүү хялбар байх болно.
Танд илүү олон даалгавар байх тусам багаж хэрэгслийн хэрэгцээ илүү өргөн байх болно, тэдгээр нь өөр өөр платформуудад өөр өөр байдаг бөгөөд ирээдүйд зардлаа багасгах сонголт хийхийн тулд боломжтой хувилбаруудтай нэн даруй танилцах нь дээр.
Гэхдээ өнөөдөр оршин байгаа бүх экосистем төгс бус гэдгийг хүлээн зөвшөөрөх нь зүйтэй. Тиймээс, хэрэв компанид RAML-д ажиллах дуртай фенүүд байгаа бол "энэ нь танд бодлоо илүү уян хатан илэрхийлэх боломжийг олгодог" эсвэл эсрэгээрээ "илүү ойлгомжтой" учраас Swagger-ийг илүүд үздэг бол тэднийг ажлаа орхих нь дээр. Аль ч форматын хэрэгсэл нь файлын тусламжтайгаар өөрчлөхийг шаарддаг тул тэд үүнд дассан бөгөөд үүнийг хүсдэг.
Бидний туршлагын хувьд бид RAML-Swagger архитектур дээр үндэслэн ямар статик болон динамик шалгалт хийдэг, мөн гэрээнээс ямар баримт бичгийг үүсгэдэг, энэ бүхэн хэрхэн ажилладаг талаар дараагийн нийтлэлүүдэд ярих болно.
Зөвхөн бүртгэлтэй хэрэглэгчид санал асуулгад оролцох боломжтой. , гуйя.
Та бичил үйлчилгээний гэрээг ямар хэлээр тэмдэглэдэг вэ?
-
RAML 0.8
-
RAML 1.0
-
Сваггер 2
-
OAS3 (өөрөөр хэлбэл)
-
зураг төсөл
-
Бусад
-
Ашиглахгүй байна
100 хэрэглэгч санал өгсөн. 24 хэрэглэгч түдгэлзсэн.
Эх сурвалж: www.habr.com