Шысь тэпатароў інтеграціі для надзеяного з’ёднання служб 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. Прадастальнікі зазвычай падпісваюць кожны пакет даных, і вы должны пераканаўцеся ў гэтым падпісе (зазвычай у пораўнанні з необработаным тэлам запиту) прыцемна да доверлення паданых дадзеных.
• Чакайце на дуплікаты. Даны зазвычай падаюць знову і зноў пакуль не будзе падтверджэння, таму адны і тыя ж дадзеныя можаць прыйсці больш чым раз. Зберагайце ID обробланых падзей і стваруйце прыемнікі, якія будуць ідэмпатныя.
• Падтвердзіце быстра. Шыбкая адпаведь 2xx і пераказваўанне повольных задач у чергу; іншым чыным прадастальнік можа выключыцься і перасłaць даны знову.

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

4. Аутентыкацыя: падтверджэнне таго, хто выканаў запыт

Кожная інтэграцыя пачынаецца з аутентыкацыйных даных. Тры падходы пакрываюць большасць случаяў.

Клучы API

Самы просты спосаб — адправка спяльнай таёмніцы ў загалоўку:

GET /users

x-api-key: abc123xyz

У Node.js з абляцыямі ключ должен выходзіць з настройкаў, а не з коду выканання:

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 single sign-on, канектары 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, webhooks, механізмы перапрыбуткі і захисту, шары трансформаціі, а таксама монітарынг і логаванне. Для інжынераў, якія пераходзяць да роботы з інтэграцыяй, першыя практычныя рынкі — это REST API, webhooks, JWT, OAuth 2.0, трансформація дадзэнняў і проектаванне на адной з прычын кантэксту, пасля чаго — технікі перапрыбуткі і стойкасці, а потым — polling і circuit breakers.

Галоўныя вывары

• Для быстрых операцый выкорыстоўваюце модель запыт-адказ; калі робота трывае, перайдзіце на методы polling або webhooks.
• Пераканаўваеце падпісы webhook-аў, усуваеце дуплікаты запускаючыхся задач і шырока паведамляеце пра ўсё.
• Зберагаеце аутантыфікацыйныя данні ў настройкach, назначаеце тэрмін даведжання токенам і правільна вучыцеся працаваць з механізмамі OAuth.
• Прабуйце зноў толькі у разы тымчасовых абяканняў, з настаўленым таймаутам, обмежаным экспанэнцыйным адступленням і паўтарэнням спроб.
• Ізолюйце карэткаванне дадзеных у перапрацаваных чыстых функціях, а даты і грошы трэба обрабоўваць з адзінаковай абераганасцю.