У динамічному світі мікросервісів може змінитися все що завгодно — будь-який компонент можна переписати іншою мовою, використовуючи інші фреймворки та архітектуру. Незмінними повинні залишатися лише контракти, у тому, щоб із микросервисом можна було взаємодіяти ззовні певної постійної основі, незалежно від внутрішніх метаморфоз. І сьогодні ми розповімо про нашу проблему вибору формату опису контрактів та поділимося знайденими артефактами.
Пост підготували и
Мікросервіси. При розробці Acronis Cyber Cloud ми зрозуміли, що нам нікуди від них не подітися. А проектування мікросервісу неможливе без формалізації контракту, який є інтерфейсом мікросервісу.
Але коли продукт міститься більше ніж один компонент, і розробка контракту стає регулярною активністю, мимоволі починаєш замислюватися про оптимізацію процесу. Стає очевидним, що інтерфейс (контракт) та імплементація (мікросервіс) повинні один одному відповідати, що різні компоненти повинні робити ті самі речі однаково, і що без централізованого прийняття всіх цих рішень кожна команда буде змушена знову і знову витрачати час на їх отримання .
Схема мкросервісів Amazon з Вернера Вогеліса, СTO Amazon
У чому полягає дилема? Де факто є два способи взаємодії мікросервісів – HTTP Rest та gRPC від компанії Google. Не бажаючи бути залученими до стек технологій Google, ми вибрали HTTP Rest. Анотації до контрактів HTTP REST найчастіше описуються одним із двох форматів: RAML і OAS, раніше відомий як Swagger. Тому кожна команда розробників стикається з необхідністю зробити вибір на користь одного зі стандартів. Але, як з'ясувалося, зробити цей вибір може бути непросто.
Навіщо потрібні інструкції?
Анотація потрібна для того, щоб зовнішній користувач міг легко розібратися, що можна робити з сервісом через його HTTP-інтерфейс. Тобто на базовому рівні анотація повинна містити як мінімум список доступних ресурсів, їх HTTP-методів, тіла запитів, перерахування параметрів, зазначення необхідних заголовків, що підтримуються, а також кодів повернення і форматів відповідей. Вкрай важливим елементом інструкції договору є та його словесне опис(“що буде, якщо додати цей query-параметр до запиту?”, “у якому разі повернеться код 400?”)
Тим не менш, коли йдеться про розробку великої кількості мікросервісів, хочеться отримувати додаткову користь із написаних інструкцій. Наприклад, на основі RAML/Swagger можна генерувати і клієнтський, і серверний код на величезній кількості програмованих мов. А ще можна автоматично отримувати документацію до мікросервісу та заливати її на ваш developer-portal :).
Приклад структурованого опису договору
Рідше зустрічається практика тестування мікросервісів з урахуванням описів договорів. Якщо ви написали і анотацію, і компонент, можна створити автотест, перевіряючий адекватність роботи сервісу з різними типами даних на вході. Чи не повертає сервіс код відповіді, що не описаний в інструкції? Чи зможе коректно обробити свідомо неправильні дані?
Більше того, якісна реалізація не лише самих контрактів, а й інструментарію для візуалізації анотацій дозволяє спростити роботу з мікросервісом. Тобто якщо архітектор якісно описав контракт, на його підставі дизайнери та розробники впроваджуватимуть сервіс в інші продукти без додаткових витрат часу.
Для роботи додаткових інструментів і RAML, і OAS мають можливість додавання метаданих, які не передбачені стандартом ().
Загалом поле для творчості у застосуванні контрактів для мікросервісів — величезне… принаймні теоретично
Порівняння їжака з вужем
Нині пріоритетний напрямок розробки у Acronis – розвиток Acronis Cyber Platform. Acronis Cyber Platform – це нові точки інтеграції сторонніх сервісів із Acronis Cyber Cloud та агентською частиною. Хоча наші внутрішні API, описані в RAML, нас влаштовували, необхідність публікації API знову порушила питання вибору: який стандарт анотацій краще використовувати для нашої роботи?
Спочатку здавалося, що рішень два – це найпоширеніші розробки RAML та Swagger (або OAS). Але за фактом виявилося, що альтернатив, як мінімум, не 2, а 3 або більше.
З одного боку є RAML – потужна та ефективна мова. У ньому добре реалізована ієрархія і успадкування, тому цей формат більше підходить для великих компаній, яким потрібно багато описів — тобто не один продукт, а багато мікросервісів, які мають спільні частини контрактів — схеми аутенфікації, однакові типи даних, тіла помилок.
Але розробник RAML, компанія Mulesoft, приєдналася до консорціуму Open API, що займається розвитком . Тому RAML призупинив свій розвиток. Щоб уявити формат події, уявіть, що мейнтейнери основних компонентів Linux пішли працювати в Microsoft. Така ситуація створює передумови для того, щоб використовувати Swagger, який динамічно розвивається і в останній – третій версії – практично наздоганяє RAML за гнучкістю та функціональністю.
Якби не одне але…
Як виявилось, далеко не всі open-source утиліти оновилися до версії OAS 3.0. Для мікросервісів на Go найкритичнішою буде відсутність адаптації під нову версію стандарту. Однак різниця між Swagger 2 і Swagger 3 . Наприклад, у третій версії розробники:
- покращили опис схем аутентифікації
- підтримку JSON Schema
- прокачали можливість додавання прикладів
Ситуація виходить кумедна: при виборі стандарту слід розглядати RAML, Swagger 2 та Swagger 3 як окремі альтернативи. При цьому лише Swagger 2 має гарну підтримку інструментарію OpenSource. RAML - дуже гнучкий ... і складний, а Swagger 3 слабо підтримуються ком'юніті, так що вам доведеться користуватися інструментами власної розробки або комерційними рішеннями, які зазвичай коштують дуже дорого.
При цьому, якщо у Swagger існує багато приємних можливостей, таких як готовий портал , на який можна завантажити анотацію та отримати її візуалізацію з докладним описом, посиланнями та зв'язками, то для більш фундаментального та менш доброзичливого RAML такої можливості немає. Так, можна пошукати щось серед проектів на GitHub, знайти там аналог та самостійно його розгорнути. Однак у будь-якому випадку хтось повинен буде підтримувати портал, що не так зручно для базового використання чи тестових потреб. Крім того, swagger більш "безпринципний", ну або ліберальний - його можна генерувати з коментарів у коді, що, звичайно, йде врозріз з принципом API first і не підтримується жодної з утиліт 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, вже зараз є багато сервісів і продуктів, які допоможуть зробити перевірку, конвертувати, провести валідацію. Але вони коштують дорого, а іноді дуже дорого. Для великої компанії такі витрати терпимі, але для стартапу можуть стати великим навантаженням.
Визначити набір інструментів, які ви використовуватимете пізніше. Наприклад, якщо вам потрібно просто відображати контракт, простіше буде використовувати Swagger 2, який має гарний API, адже в RAML вам доведеться піднімати і підтримувати сервіс самостійно.
Чим більше буде у вас завдань, тим ширшою буде потреба в інструментах, а вони різні для різних платформ, і краще відразу ознайомитися з доступними версіями, щоб зробити вибір, який мінімізує ваші витрати в майбутньому.
Але варто визнати, що всі екосистеми, які існують на сьогоднішній день, недосконалі. Тому якщо в компанії є фанати, які люблять працювати в RAML, тому що "він дозволяє гнучкіше висловлювати думки", або, навпаки, віддають перевагу Swagger, тому що "він зрозуміліший", - найкраще залишити їх працювати в тому, в чому вони звикли і хочуть, бо інструментарій будь-якого формату вимагає доопрацювання напилком.
Що стосується нашого досвіду, у наступних постах ми розповімо про те, які статичні та динамічні перевірки ми проводимо на базі нашої RAML-Swagger архітектури, а також про те, яку документацію ми генеруємо з контрактів, і яким чином все це працює.
Тільки зареєстровані користувачі можуть брати участь в опитуванні. , будь ласка.
А яку мову ви використовуєте для інструкцій контрактів мікросервісів?
-
RAML 0.8
-
RAML 1.0
-
Чванство 2
-
OAS3 (aka)
-
План
-
Інший
-
Не використовую
Проголосували 100 користувачів. Утрималися 24 користувача.
Джерело: habr.com