Перейти до вмісту

Перенесла API на Huma v2 зі 100% відповідністю

Перенесла HTTP API з Fiber на Huma v2 — 649 шляхів і 760 операцій — досягнувши та втримавши 100% відповідність між маршрутами, які реєструє сервер, і описом OpenAPI, який він публікує.

760 операцій API перенесено, а опис лишився правдивим

Ситуація. API починався на Fiber, а валідацію запитів писали вручну, для кожного ендпоінта окремо. Це нормально, коли ендпоінтів жменька. Коли ж поверхня API розростається, це вже не нормально: валідація, написана вручну, перетворюється на податок на супровід, а дрібні неузгодженості непомітно просочуються, бо перевірки кожного ендпоінта — окрема неповторна сніжинка. До того ж єдиного опису форми API не було ніде.

Завдання. Мета — щоб валідація випливала з типів, а не з перевірок, написаних вручну, і щоб з’явився справжній контракт, який описує API, — і все це без зупинки на те, щоб переписати все одним махом.

Дія. HTTP‑рівень перенесено на Huma v2 поверх Fiber, тож наявний рантайм зберігся. Кожен ендпоінт отримує вхідні та вихідні структури, а Huma генерує з цих типів валідацію запитів і модель відповідей. Опис OpenAPI при цьому з’являється задарма, тобто документація встигає за кодом, а не застаріває у вікі. Усе нове писалося під Huma, наявні маршрути перенесено, і на чистому Fiber лишилося рівно два ендпоінти — WebSocket‑ендпоінти, де справді потрібен сам сокет, а модель запиту й відповіді Huma не пасує. З часом це виросло до 649 шляхів із 760 операціями, а перевірка в CI порівнює маршрути, які сервер реєструє насправді, з тими, що їх оголошує опис OpenAPI. Відповідність — 100%, і такою вона й лишається, бо через неописаний маршрут збірка падає.

Результат. Нові ендпоінти отримують валідацію та актуальну документацію без жодних додаткових зусиль, а цілий клас помилок в обробці запитів — отих «ой, а тут ми забули перевірити це поле» — зник. Коли операцій 760, API на практиці читають лише через опис, тож гарантія його повноти важить більше, ніж тоді, коли їх було п’ятдесят. Типізований контракт зробив API водночас безпечнішим для змін і простішим для передачі іншій людині, адже типи самі кажуть, чого чекає ендпоінт.

  • Залізниця, залізничні колії, вузол
    Фото: music4life / Pixabay
  • Складена карта, дорожня карта, маршрут
    Фото: cocoparisienne / Pixabay

Застосуйте цей досвід у своєму проєкті

Використайте «Перенесла API на Huma v2 зі 100% відповідністю» як відправну точку для схожого завдання у вашій організації. Послуги, що стоять за цією роботою, доступні й для вашого проєкту. Структура системи, спершу продумана на папері, щоб частини пасували одна до одної, а вартість була відома до першого рядка коду.

Переглянути наші послуги Зв'язатися з нами

Дізнайтеся, що привело до результату

Прочитайте про ситуацію, рішення та результат цього прикладу. Ми можемо обговорити, що відповідає вашим умовам, а що потребує іншого підходу. Перенесла API на Huma v2 зі 100% відповідністю — 760 операцій API перенесено, а опис лишився правдивим

Переглянути наші послуги Зв'язатися з нами

Одна частина довшого переліку — і він увесь на цьому сайті.

Кожен запис написано однаково: ситуація, завдання, що ми зробили і що змінилося.

Переглянути весь перелік

Визначте потрібне покращення

Опишіть робочий процес, наявні інтерфейси та користувачів, яким потрібна зміна. Ми можемо визначити перевірюваний результат і спосіб передачі, який дасть вашій команді змогу підтримувати його.

Дивитися, скільки це коштує Зв'язатися з нами

Хочете API з валідацією даних і доброю документацією?

Запитайте про рішення в роботі «Перенесла API на Huma v2 зі 100% відповідністю». Ви говоритимете з людьми, які можуть пояснити роботу й оцінити ваш проєкт.

Переглянути наші послуги
welcome@engineer.company +45 50 10 61 84 Копенгаген, Данія
QR-код сторінки «Перенесла HTTP API з Fiber на Huma v2 — 649 шляхів і 760 операцій — досягнувши та втримавши 100% відповідність між маршрутами, які реєструє сервер, і описом OpenAPI, який він публікує.»
Візьміть цю сторінку із собоюhttps://software.engineer.company/uk/portfolio/migrated-the-api-to-huma-v2-at-100-parity/