Шість шаблонів інтеграції для надійного з’єднання сервісів Node.js

Надсилання HTTP-запиту — це просто; справжній виклик полягає у підтримці функціональності інтеграції, коли інша система працює повільно, не працює або має іншу структуру. У цьому посібнику розглядаються шість патернів, які часто зустрічаються під час взаємодії сервісів Node.js з постачальниками платежів, CRM-системами, ERP-системами та між собою, а також перешкоди, які відрізняють демо-версію від надійної інтеграції.

1. Запит-відповідь: синхронна основа

У моделі запит-відповідь клієнт надсилає запит, сервер виконує роботу, а відповідь надходить через ту саму з’єднання. Цей підхід охоплює більшість повсякденних операцій: входження, створення чи оновлення записів, отримання інформації про клієнта, видалення ресурсу.

app.get("/users/:id", async (req, res) => {
  const user = await db.findUser(req.params.id);
  res.json(user);
});

Його легко дебагувати, і він є стандартом для операцій CRUD. Його слабкістю є тривалі операції: великий звіт чи великий файл можуть перевищити таймаути клієнта чи проксі. Також варто зазначити, що цей обробник повертає null із статусом 200, коли користувача немає; справжній кінцевий пункт має повертати 404.

2. Поллінг: запити до завершення роботи

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

Початок виконання завдання повертає його ID:

POST /reports

Response:
{
  "jobId": "abc123"
}

Потім клієнт періодично перевіряє кінцевий пункт статусу:

GET /reports/abc123/status

до тих пір, поки завдання не повідомить про своє завершення:

{
  "status": "completed"
}

Поллінг є простим та сумісним із брандмауерами, тому багато корпоративних систем досі від нього залежать. Недоліком є марна витрата трафіку, адже більшість перевірок повертають значення „ще ні“. Розтягуйте запити (дотримуючись значення Retry-After, якщо воно передано), встановіть загальний термін завершення та обробляйте як випадки failed, так і completed.

3. Webhooks: можливість для іншої сторони викликати вас

Webhooks змінюють напрямок взаємодії. Замість того, щоб ваш сервіс постійно запитував, провайдер надсилає HTTP-запит до вашого кінцевого пункту, коли щось відбувається: оплата успішна, замовлення оформлене, повідомлення надійшло, клієнт зареєструвався, змінилися запаси. Stripe, Slack, GitHub та Shopify активно використовують цю модель.

Мінімальний приймач у Express:

app.post("/webhook/payment", (req, res) => {
  const event = req.body;

  if (event.type === "payment.success") {
    console.log("Payment received!");
  }

  res.sendStatus(200);
});

Це показує основну структуру, але для продакшн-середовища приймач потребує більшого:

• Перевірте відправника. Будь-хто може опублікувати контент на публічному URL. Провайдери зазвичай підписують кожен надісланий даний, і ви повинні перевірити цей підпис (зазвичай порівнюючи його з необробленим тілом запиту), перш ніж довіряти події.
• Очікуйте дублікатів. Доставка даних зазвичай повторюється до отримання підтвердження, тому одна й та сама подія може надійти кілька разів. Зберігайте ідентифікатори оброблених подій та робіть функції обробки ідемпотентними.
• Швидко підтверджуйте. Швидко повертайте код 2xx та відкладіть повільну обробку у чергу; інакше провайдер може вичекати таймауту та надіслати дані знову.

Інтеграція, заснована на подіях, все частіше використовується через відсутність трафіку, пов’язаного з опитуванням.

4. Аутентифікація: підтвердження того, хто здійснює виклик

Кожна інтеграція починається з облікових даних. Три підходи охоплюють більшість випадків.

Ключі API

Найпростіший сценарій передбачає надсилання спільного секрету у заголовку:

GET /users

x-api-key: abc123xyz

У Node.js з axios ключ має походити з конфігурації, а не з вихідного коду:

axios.get(url, {
  headers: {
    "x-api-key": process.env.API_KEY
  }
});

Ключі API підходять для внутрішніх інструментів та простих інтеграцій сервер-сервер. Вони самі по собі не мають терміну дії чи ідентифікатора користувача, тому їх слід регулярно змінювати та обмежувати їхній діапазон настільки, наскільки це дозволяє постачальник.

JSON Web Tokens

JWT дозволяють здійснювати автентифікацію без стану. Зазвичай це відбувається так:

1. Користувач уходить у систему.
2. Сервер видає підписаний токен.
3. Клієнт зберігає токен.
4. Кожен наступний запит передає його у заголовку:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Видача токена в Node.js:

const token = jwt.sign(
  { userId: 1 },
  process.env.JWT_SECRET
);

Будь-яка служба з ключем верифікації може підтвердити токен без зберігання сеансу, що підходить для мікросервісів. Проблема полягає у скасуванні: токен залишається дійсним до закінчення терміну, тому завжди необхідно встановлювати параметр expiresIn, який у цьому фрагменті пропущений.

OAuth 2.0

OAuth 2.0 — це те, що забезпечує роботу довірених доступів: «Увійти через Google», входження у Facebook, система єдиного входу Microsoft enterprise, з’єднувачі CRM та будь-які сторонні додатки, які діють від імені користувача. У типовому процесі авторизації за кодом:

1. Користувач схвалює запит на доступ у провайдері.
2. Провайдер перенаправляє користувача назад із тимчасовим кодом авторизації.
3. Ваш сервер обмінює цей код на токен доступу.
4. Запити до API виконуються з використанням токена доступу.

Варто детально вивчити: токени доступу та оновлення, процес Authorization Code, процес Client Credentials для викликів між пристроями, PKCE та OpenID Connect — шар ідентифікації, що працює поверх OAuth.

5. Стійкість: проектування з урахуванням помилок

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

Повторна спроба невдалого виклику

Базовий цикл повторних спроб:

for (let i = 0; i < 3; i++) {
  try {
    return await axios.get(url);
  } catch (error) {
    console.log("Retrying...");
  }
}

У нинішньому вигляді він негайно робить повторну спробу без паузи, і якщо всі три спроби провалюються, він повертає undefined замість того, щоб викинути останню помилку, тож користувач не може дізнатися, що пішло не так. Потрібно викинути помилку знову після останньої спроби та повторювати лише тимчасові помилки (проблеми з мережею, таймаути, коди 5xx, 429), а не помилки 4xx, які завжди призводитимуть до однакового результату. Будьте обережні під час повторних спроб нейдентичних запитів, таких як оплати, якщо тільки API не підтримує ключі ідентичності.

Таймаути

Запит без таймауту може застрягти на невизначений час, утримуючи ресурси. Завжди встановлюйте таймаут:

axios.get(url, {
  timeout: 5000
});

Експоненційне збільшення інтервалу

Повторні спроби з фіксованим інтервалом продовжують навантажувати проблемний сервіс:

1s
1s
1s
1s

Подвоєння часу очікування щоразу дає йому можливість відновитися:

1s
2s
4s
8s
16s

Розрахунок виконується за одну рядкову команду:

const delay = attempt =>
  Math.pow(2, attempt) * 1000;

Встановіть максимальний термін затримки та додайте випадкове зміщення, щоб багато клієнтів, які одночасно зазнають проблем, не робили спроби повторно в унісон.

Захисники ланцюгів

Захисник ланцюга підраховує кількість збоїв у сервісі нижчого рівня, і після досягнення певного порогу припиняє виклики на період охолодження перед надсиланням спроби знову. Це запобігає каскадним збоям, виснаженню ресурсів та загальним збоям системи. Opossum є поширеним вибором у Node.js; Resilience4j виконує аналогічну функцію у Java, а Hystrix використовується у старіших системах.

6. Трансформація даних: переклад між системами

Дві системи рідко погоджуються щодо формату даних, тому значна частина роботи з інтеграції полягає у їх перекладі.

Посилання полів

Одна система використовує camelCase:

{
  "firstName": "John"
}

інша очікує snake_case:

{
  "first_name": "John"
}

Невеликий мапер з’єднує їх:

function transform(user) {
  return {
    first_name: user.firstName
  };
}

Функції-мапери легко тестувати в одиницях, і це допомагає уникнути особливостей постачальника в бізнес-логіці.

JSON та XML

Багато старих систем все ще використовують XML, тоді як новіші сервіси генерують JSON, тому шар інтеграції часто перетворює дані між цими форматами в обох напрямках.

Дати

Одна сторона може надсилати дані у форматі ISO:

2026-06-26

тоді як інша очікує форматування з днем на початку:

26/06/2026

Перетворюйте дані явно та чітко вказуйте часові зони, якщо значення містять час; дата, зміщена через північ, є класичною проблемою інтеграції.

Суми в валюті

Один сервіс повідомляє суму з десятковою часткою:

{
  "amount": 10.50
}

Інший вимагає цілочисельних одиниць меншої величини:

{
  "amount_cents": 1050
}

Значення з плаваючою комою не можуть точно представити кожну десяткову частку, тому під час конвертації необхідно заокруглювати (наприклад, Math.round(amount * 100)) та використовувати всередині цілочисельні сантими.

Як у практиці поєднуються ці патерни

Типова архітектура підприємства розміщує шлюз Node.js перед кількома бекендами:

Frontend
   |
Node.js API Gateway
   |
   +-- Authentication Service
   +-- Payment Service
   +-- CRM Service
   +-- ERP Systems
   +-- Notification Service

Ці з’єднання поєднують вищезгадані патерни: API з механізмом запит-відповідь, JWT та OAuth, вебхуки, механізми повторних спроб та захисту від збоїв, шари трансформації даних, а також моніторинг та логування. Для інженерів, які починають працювати з інтеграціями, найбільш корисними є REST API, вебхуки, JWT, OAuth 2.0, трансформація даних та проектування на основі подій, після чого йдуть техніки повторних спроб та стійкості, а потім методи опитування та захист від збоїв.

Основні висновки

• Використовуйте механізм запит-відповідь для швидких операцій; переходьте на поллінг або вебхуки, коли робота займає більше часу.
• Перевіряйте підписи вебхуків, усувайте дублікати подій та швидко підтверджуйте їх отримання.
• Зберігайте облікові дані у конфігурації, встановлюйте термін дії токенів та ретельно вивчайте процеси OAuth.
• Перезапускайте спроби лише у разі тимчасових помилок, з використанням таймаутів, обмежень експоненційного збільшення спроб та ефекту джиттера.
• Ізолюйте мапування даних у перевірених чистих функціях та з особливою увагою ставіться до дат та грошових сум.