Це здавалося автоматизацією, про яку можна було тільки мріяти — поки не перетворилося на кошмар обслуговування.
Інтеграція API може бути як захоплюючою, так і складною. Коли я почав аналізувати нову інтеграцію API в нашій екосистемі C++, я був оптимістом. Стандарт OpenAPI звучав позитивно в обговореннях і статтях і здавався ідеальним способом стандартизувати та автоматизувати більшу частину процесу за допомогою генератора OpenAPI (Swagger). Це історія про те, як я подолав ці виклики, навчився адаптуватися і врешті знайшов рішення, яке підійшло нашій команді.
Photo by Lyman Hansel Gerona on Unsplash
Початковий підхід та виклики
Коли я почав проект, я вибрав OpenAPI через його обіцянку автоматизації. Ідея генерувати шаблонний код і стандартизувати взаємодії з API звучала як ідеальний спосіб спростити розробку. API, який я інтегрував, був новим API Flights Global Distribution System від Travelport, і його структури даних були складними та важкими для розуміння. Крім того, Travelport поширював свою специфікацію за допомогою стандарту OpenAPI.
Не минуло багато часу, як я зрозумів, що варіанти плагінів для C++ були недостатніми. Генератори, які я пробував, створювали код, який в основному був несумісний з нашими специфічними вимогами та додавав великі, неподільні власницькі бібліотеки до наших проектів. Після невеликого дослідження генератора OpenAPI я зрозумів, що це не надто складно, і його можна розширити новим плагіном, використовуючи мінімалістичну бібліотеку nlohmann/json з відкритим кодом. Я витратив кілька днів на створення нового плагіна для генератора OpenAPI, занурився в кодову базу генератора на Java і навчився модифікувати його шаблони Mustache. Після деякого налагодження всі структури даних API, запити та відповіді були згенеровані і готові до використання. Тоді це здалося великою перемогою, оскільки я вважав, що зекономив багато часу, уникаючи написання структур даних API з нуля.
Однак після кількох оновлень версій API та змін, що включали реорганізацію всієї ієрархії API в термінах OpenAPI, стиль спадкування та додавання нових функцій, стало очевидно, що підтримка та обслуговування генератора створюватиме довгострокові проблеми. Більше того, API не завжди суворо дотримувався своєї специфікації, що вимагало додаткової обробки аномалій у згенерованому коді.
Прийняття складного рішення змінити підхід
Після кількох тижнів боротьби з генератором я запросив критичну зустріч з нашим головним розробником. Він терпляче вислухав мене, поділився своїм досвідом з інструментами автоматизації, і ми разом оцінили переваги та недоліки можливих рішень. Зрештою, він залишив рішення за мною. Я витратив ще кілька годин на фінальне дослідження, перегляд коду та зважування переваг і недоліків обох підходів.
Поглянувши з боку, я зрозумів, що ручне програмування було правильним шляхом вперед. Спочатку це здавалося визнанням поразки. Я витратив стільки часу, намагаючись зробити автоматизацію робочою, а тепер мені доводилося починати з нуля. Однак підтримка і заохочення, які я отримав за своє рішення, дали мені нову енергію для початку.
Виявлення переваг ручного програмування
Коли я почав програмувати вручну, переваги стали очевидними. Без обмежень згенерованого коду я отримав повний контроль над тим, як API інтегрується в нашу систему. Я зміг спростити логіку, зменшити залежності і зробити код легшим для читання та підтримки. Важливою перевагою було використання інструментів штучного інтелекту, які значно еволюціонували і зробили багато повторюваних задач ефективнішими. Те, що почалося як розчарування, перетворилося на можливість створити більш чисте і ефективне рішення.
Уроки, що я засвоїв
Цей досвід навчив мене кількох важливих уроків, які я візьму з собою в подальшу кар'єру розробника:
1.
Автоматизація не завжди є вирішенням: Хоча інструменти автоматизації можуть бути потужними, вони не є універсальним рішенням для всіх випадків. Важливо оцінити, чи підходить інструмент для вашого проекту, перш ніж витрачати на нього занадто багато часу.
2. Почати знову не страшно: Визнати, що обраний шлях не працює, може бути важко, але іноді це найкращий спосіб рухатись далі. Початок знову дозволив мені створити рішення, яке краще відповідало нашим потребам.
3. Підтримка має значення: Протягом усього цього процесу підтримка мого керівника справила величезний вплив. Знаючи, що я маю свободу самостійно приймати рішення і вчитися без страху перед невдачею, я зміг змінити курс, коли це було необхідно.
4. Ручне програмування має своє місце: Написання коду вручну може зайняти більше часу на початку, але часто призводить до більш гнучкого і підтримуваного рішення. У цьому випадку це було саме те, що нам потрібно було.
Практичні поради для розробників
Якщо ви стикаєтеся з подібними викликами, ось кілька порад з мого досвіду:
Попросіть про підтримку: Не бійтеся звертатися до своєї команди або керівництва за порадою та підтримкою.
Зосередьтеся на простоті: Іноді найпростіше рішення є найкращим. Не бійтеся відступити від автоматизації, якщо вона створює більше складнощів, ніж того варта.
Не бійтеся відкидати роботу: Коли ваша робота більше не служить вам, пора рухатись далі. Уникайте пастки витрачених коштів (sunk-cost fallacy).
Використовуйте штучний інтелект, де це можливо: Штучний інтелект може стати значною допомогою, зменшуючи повторювані задачі та підвищуючи продуктивність. Не бійтеся, якщо перші спроби не дають ідеальних результатів.
Висновок
Оглядаючись назад, мій досвід інтеграції API Travelport навчив мене набагато більше, ніж я очікував. Спочатку я вважав автоматизацію кінцевою метою, але зрозумів, що іноді крок назад і прийняття ручного програмування може призвести до кращих результатів. Цей досвід зміцнив важливість гнучкості та цінність підтримки. Найголовніше, він нагадав мені, що кожен виклик — це можливість навчитися і вирости як розробнику.
Чи стикалися ви з подібними труднощами при автоматизованому генеруванні коду? Поділіться своїм досвідом у коментарях.
Перекладено з: What I Wish I Knew Before Using the OpenAPI Generator