HTTP-клиенты в Node.js
Сервис редко работает в одиночку: он ходит в базу, платёжный шлюз, сервис уведомлений и чужие API. Каждый такой вызов — это соединение, дедлайн, возможный повтор и обработка ошибки, и именно на них приходится заметная часть p99 и инцидентов. Разберём, как устроены HTTP-клиенты Node.js, чем fetch отличается от http.request и какие настройки превращают исходящий запрос из «просто await» в предсказуемую операцию.
Содержание
- Почему исходящий запрос — часть архитектуры
- Три уровня API: fetch, undici и http.request
- Ответ не равен ошибке
- Соединения и keep-alive
- Пул соединений и лимиты
- Таймауты на каждом уровне
- Отмена запроса
- Стриминг ответа и размер тела
- Ретраи и идемпотентность
- Клиент как модуль: конфигурация и наблюдаемость
- Отличия от браузерного fetch
- Частые ошибки
- Эксперименты
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Почему исходящий запрос — часть архитектуры
Исходящий запрос выглядит как одна строка await fetch(url), но за ней стоят четыре независимых решения:
- соединение — новое или переиспользованное, сколько их всего и кому они принадлежат;
- время — сколько ждать установки соединения, заголовков и тела по отдельности и сколько на всё вместе;
- повтор — какие сбои считать временными и безопасно ли выполнить запрос ещё раз;
- данные — читать ответ целиком в память или потоком, и какого размера ответ допустим.
Пропущенное решение не исчезает, а превращается в поведение по умолчанию. Клиент без таймаута ждёт бесконечно и держит соединение из пула. Клиент без проверки статуса принимает страницу ошибки прокси за JSON. Клиент с ретраями на всё подряд усиливает сбой внешнего сервиса. Поэтому HTTP-клиент в сервисе — такой же конфигурируемый модуль, как пул базы данных, а не набор вызовов в бизнес-логике.
Три уровня API: fetch, undici и http.request
В Node есть три уровня абстракции, и выбирать между ними стоит осознанно.
| Уровень | API | Что даёт | Чего не делает |
|---|---|---|---|
| Высокий | fetch (undici) | web-стандарт, редиректы, распаковка, web streams | не проверяет статус, не хранит куки, не даёт прямого доступа к сокету |
| Средний | undici.request | Node-стрим, таймауты клиента, меньше слоёв | не следует редиректам, не парсит тело |
| Низкий | node:http, node:https | агент, сокет, заголовки, полный контроль | всё вручную: редиректы, gzip, JSON |
Глобальный fetch появился в Node 18 и внутри работает на undici — HTTP/1.1-клиенте, который Node использует и для собственных нужд. Снаружи это знакомый web API:
const res = await fetch('https://api.example.com/users/42', { signal });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const user = await res.json();
Средний уровень — undici.request: те же соединения и агенты, но ответ приходит Node-стримом, а редиректы и разбор тела остаются на вызывающем.
import { request } from 'undici';
const { statusCode, headers, body } = await request(
'https://api.example.com/report.csv',
{ method: 'GET' },
);
for await (const chunk of body) {
// чанк приходит по мере чтения, без буферизации всего файла
}
Низкий уровень — node:https. Здесь нет ни распаковки, ни следования редиректам, ни JSON-хелперов, но есть прямой доступ к агенту и сокету:
import { request } from 'node:https';
const req = request('https://api.example.com/users/42', (res) => {
res.setEncoding('utf8');
res.on('data', (chunk) => { /* ... */ });
res.on('end', () => { /* ... */ });
});
req.on('timeout', () => req.destroy(new Error('ETIMEDOUT')));
req.end();
Практическое правило: fetch — по умолчанию, http.request — когда нужен контроль, которого fetch не даёт. Например, для прокси с mTLS, нестандартного агента, чтения трейлеров или очень горячего пути, где лишние слои абстракции мешают. Для обычного вызова внешнего API возможностей fetch и настроенного диспетчера достаточно.
Отдельно стоит помнить, что fetch в Node — это HTTP/1.1. Мультиплексирования HTTP/2 у него нет: для h2 нужен node:http2 или специализированный клиент. Для большинства сервисов это не проблема, но при разговоре с h2-only шлюзом выбор уже другой.
Ответ не равен ошибке
Главная ловушка fetch — он не бросает исключение на HTTP-ошибку. Ответ 500 — такой же успешно полученный Response, как и 200; отличается только res.ok и res.status.
const res = await fetch(url, { signal });
if (!res.ok) {
const text = await res.text(); // тело ошибки может быть HTML от прокси
throw new HttpError(res.status, text.slice(0, 500));
}
const data = await res.json();
Отсюда два следствия. Во-первых, проверка статуса должна быть в одном месте — в модуле клиента, а не в каждом обработчике. Во-вторых, тело ошибки нужно читать защищённо: внешний сервис может вернуть HTML, пустую строку или гигантский stack trace, и res.json() на нём упадёт с SyntaxError, замаскировав исходную проблему.
Что вообще может пойти не так:
| Ситуация | Как выглядит | Что делать |
|---|---|---|
| DNS, TCP, TLS, обрыв | TypeError: fetch failed, причина в err.cause | ретрай по коду или алерт |
| Таймаут или отмена | TimeoutError / AbortError | различать уход клиента и дедлайн |
| HTTP 4xx | res.ok === false, статус конкретный | бизнес-ошибка, обычно без ретрая |
| HTTP 5xx | res.ok === false | ретрай только для идемпотентных вызовов |
| Невалидный JSON | SyntaxError при res.json() | ошибка контракта, алерт |
У fetch есть и полезные умолчания: редиректы он проходит сам (до 20), content-encoding распаковывает, accept-encoding добавляет. redirect: 'manual' в Node возвращает настоящий 3xx с заголовком location, а не «непрозрачный» ответ, как в браузере.
Ещё одна деталь: у ответов 204, 304 и HEAD тела нет. res.body === null, а res.json() на таком ответе бросит исключение — проверяйте статус и метод до разбора.
Соединения и keep-alive
Новое HTTPS-соединение — это DNS-запрос, TCP-рукопожатие и TLS-рукопожатие. На локальной сети это единицы миллисекунд, до удалённого дата-центра — десятки, а при плохом DNS или проблемах с TLS — сотни. Keep-alive позволяет отправить следующий запрос по уже открытому соединению и заплатить за рукопожатие один раз.
Работает это на двух сторонах:
- клиент помечает соединение как переиспользуемое (в HTTP/1.1 это
Connection: keep-alive, умолчание) и держит его в пуле; - сервер не закрывает соединение сразу после ответа, а ждёт следующий запрос в пределах
keepAliveTimeout.
В Node 19+ глобальный агент http уже включает keep-alive, а fetch/undici держит пул соединений на каждый origin сам. Но у этой схемы есть классическая ловушка — гонка таймаутов. Если сервер или балансировщик закрывает idle-соединение через 60 секунд, а клиент считает его живым пять минут, очередной запрос уйдёт в уже закрытый сокет и упадёт с ECONNRESET. Поэтому клиентский idle-таймаут должен быть меньше серверного:
import { Agent } from 'undici';
const agent = new Agent({
keepAliveTimeout: 30_000, // меньше idle-таймаута сервера и балансировщика
});
На серверной стороне обратное правило: если вы поднимаете server.keepAliveTimeout, поднимите и headersTimeout, иначе Node закроет соединение раньше, чем клиент дошлёт заголовки.
server.keepAliveTimeout = 65_000; // больше, чем idle-таймаут nginx
server.headersTimeout = 66_000; // должен быть больше keepAliveTimeout
ECONNRESET на переиспользованном соединении не всегда означает, что запрос дошёл до сервиса: он мог умереть на этапе отправки. Для идемпотентных методов такой сбой безопасно повторить, для POST — только с ключом идемпотентности.
Ещё один скрытый расход: DNS. Node не кеширует результаты dns.lookup, а каждое новое соединение снова обращается к резолверу через пул libuv. Пока соединения переиспользуются, это незаметно; при высокой частоте новых соединений DNS становится узким местом и конкурирует за те же четыре потока пула, что и файловые операции.
Пул соединений и лимиты
Пул решает две задачи: не открывать бесконечно много сокетов и переиспользовать уже открытые. Размер пула — это лимит одновременных запросов к конкретному origin, а не лимит нагрузки вообще.
Для fetch пул задаётся через undici.Agent:
import { Agent } from 'undici';
const agent = new Agent({
connections: 16, // одновременных соединений на origin
connectTimeout: 3_000, // установка соединения
headersTimeout: 10_000, // ожидание заголовков ответа
bodyTimeout: 30_000, // пауза между чанками тела
keepAliveTimeout: 30_000, // сколько держать idle-соединение
});
undici — обычная зависимость (npm i undici), хотя внутри Node уже есть его копия. Агент передают либо явно в запрос, либо глобально:
// точечно: только для этого клиента
const res = await fetch(url, { dispatcher: agent, signal });
// глобально: для всех fetch в процессе
import { setGlobalDispatcher } from 'undici';
setGlobalDispatcher(agent);
Опция dispatcher — расширение undici, которого нет в браузерном fetch. Глобальная установка действует на весь процесс, включая сторонние библиотеки, поэтому в сервисе с разными внешними API чаще настраивают отдельный агент на каждого зависимого сервиса.
Для node:http аналог — http.Agent:
import { Agent } from 'node:http';
const agent = new Agent({
keepAlive: true,
maxSockets: 16, // соединений на origin
maxFreeSockets: 8, // сколько idle держать
timeout: 30_000, // socket timeout
});
Три правила, которые спасают от неожиданностей:
- Лимит пула — не rate limit. Запросы сверх лимита не отбрасываются, а стоят в очереди внутри агента. При неограниченной очереди они копятся в памяти и приходят с уже истёкшим дедлайном.
- Пулы не общие между origin. Десять соединений к платежному шлюзу не мешают десяти к базе, но и не помогают: у каждого хоста свой пул.
- Лимит должен быть согласован с внешним сервисом. Если API разрешает 20 rps, а пул держит 16 соединений, ограничение всё равно задаёт дедлайн, а не агент.
Для HTTP/2 пул соединений выглядит иначе: одно соединение мультиплексирует много запросов, поэтому connections — это уже не число одновременных запросов. Встроенный fetch h2 не умеет, и это ещё один аргумент не считать его универсальным клиентом для любых протоколов.
Таймауты на каждом уровне
Бесконечное ожидание — не «надёжность», а способ исчерпать пул и память. Но одного общего таймаута мало: зависнуть можно на разных этапах, и диагностировать их нужно отдельно.
| Что ограничиваем | fetch | undici.Agent | http.request |
|---|---|---|---|
| Установка соединения | signal | connectTimeout | timeout (после назначения сокета) |
| Ожидание заголовков | signal | headersTimeout | socket timeout |
| Тело ответа | signal | bodyTimeout | socket timeout |
| Общий дедлайн | AbortSignal.timeout(ms) | сигнал | сигнал или ручной таймер |
У fetch собственной опции timeout нет — таймаут делают сигналом:
const res = await fetch(url, {
signal: AbortSignal.timeout(5_000),
});
Важная деталь: таймер AbortSignal.timeout стартует в момент создания сигнала. Если создать его в конфиге или на старте функции, а запрос начать позже, дедлайн съестся подготовкой. Если сигнал создан один раз на несколько попыток, вторая попытка получит уже сработавший сигнал. Поэтому сигнал создают прямо перед конкретной попыткой.
Второй нюанс — что именно обрывает сигнал. AbortSignal.timeout отменяет и установку соединения, и чтение тела: тело большого ответа тоже перестанет читаться. headersTimeout в undici ограничивает только ожидание заголовков, а bodyTimeout — паузу между чанками, а не общую длительность передачи.
Для http.request таймаут — это таймаут неактивности сокета, а не общий дедлайн:
const req = request(url, { timeout: 5_000 }, (res) => { /* ... */ });
req.on('timeout', () => {
req.destroy(new Error('ETIMEDOUT')); // без destroy запрос продолжит висеть
});
Событие timeout само по себе ничего не прерывает: если его не обработать, запрос может висеть дальше. И помните, что таймаут на попытку — не то же самое, что дедлайн на всю операцию: три попытки по пять секунд плюс backoff легко выходят за дедлайн клиента.
Дедлайн принято пробрасывать сверху вниз. Если входящий запрос имеет бюджет 8 секунд, внешние вызовы должны получать не «свои» 30 секунд, а остаток бюджета:
const deadlineAt = performance.now() + 8_000;
async function callWithBudget(url) {
const remaining = deadlineAt - performance.now();
if (remaining <= 0) throw new Error('deadline exceeded');
return fetch(url, { signal: AbortSignal.timeout(remaining) });
}
Отмена запроса
Отмена нужна в трёх случаях: клиент ушёл, работа потеряла смысл из-за ошибки соседней операции, истёк общий дедлайн. Во всех случаях используется один механизм — AbortController и его AbortSignal.
const controller = new AbortController();
res.on('close', () => {
if (!res.writableEnded) controller.abort(); // клиент ушёл, ответ ещё не отправлен
});
const signal = AbortSignal.any([
controller.signal,
AbortSignal.timeout(5_000),
]);
try {
const upstream = await fetch(url, { signal });
res.json(await upstream.json());
} catch (err) {
if (err.name === 'AbortError') return; // отмена клиентом — не ошибка сервиса
throw err; // TimeoutError и сетевые сбои — инцидент
}
AbortSignal.any объединяет несколько сигналов: срабатывает первый. Это стандартный способ совместить «клиент ушёл» и «дедлайн истёк», не заводя два вложенных try/catch.
Проверять только err.name === 'AbortError' недостаточно. Если отменить контроллер с причиной (controller.abort(new Error('client disconnected'))), fetch отклонится этой причиной, а не AbortError. Надёжнее смотреть на signal.aborted и signal.reason:
catch (err) {
if (signal.aborted) {
// это отмена, а не сбой внешнего сервиса
}
}
http.request тоже принимает signal в опциях и обрывает запрос при отмене; без сигнала для этого используют req.destroy(). Сигнал удобнее тем, что связывает HTTP-вызов с остальной цепочкой отмены, но в обоих случаях соединение рвётся, а не возвращается в пул.
Отмена не откатывает уже сделанное: если запрос дошёл до внешнего сервиса и тот успел списать деньги, отмена лишь прекратит ожидание ответа. Поэтому операции с побочными эффектами должны быть идемпотентными независимо от отмены.
Стриминг ответа и размер тела
res.json() и res.arrayBuffer() читают ответ целиком в память. Для небольшого JSON это нормально; для выгрузки, архива или файла на сотни мегабайт — прямой путь к OOM. Арифметика простая: 100 МБ ответа × 50 одновременных запросов = 5 ГБ, которые никто не планировал.
fetch возвращает res.body как web ReadableStream. В Node его можно перебирать for await или превратить в Node-стрим:
import { createWriteStream } from 'node:fs';
import { Readable } from 'node:stream';
import { pipeline } from 'node:stream/promises';
const res = await fetch(fileUrl, { signal });
if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
await pipeline(
Readable.fromWeb(res.body),
createWriteStream('report.zip'),
);
pipeline обеспечивает backpressure: если диск пишет медленнее сети, чтение ответа притормозится, и память не вырастет. Подробнее об этом — в статье «Стримы и backpressure».
Для ответов, которые должны помещаться в память, лимит ставят вручную: content-length можно подделать или не указывать вовсе (chunked), поэтому считать байты нужно по факту:
async function readLimited(res, maxBytes) {
let total = 0;
const chunks = [];
for await (const chunk of res.body) {
total += chunk.byteLength;
if (total > maxBytes) {
await res.body.cancel(); // не дочитываем и освобождаем соединение
throw new Error('response too large');
}
chunks.push(chunk);
}
return Buffer.concat(chunks);
}
Отдельная ловушка — не дочитать тело. Если вернуть управление, не вызвав res.json(), res.text() или res.body.cancel(), соединение останется занятым и не вернётся в пул. При потоке таких запросов процесс упирается в сокеты, хотя внешний сервис давно ответил.
Тело запроса тоже можно стримить, но у fetch для этого нужен флаг duplex:
import { createReadStream } from 'node:fs';
import { Readable } from 'node:stream';
await fetch(uploadUrl, {
method: 'PUT',
body: Readable.toWeb(createReadStream('backup.tar.gz')),
duplex: 'half', // требование undici для потокового тела
});
У потокового тела есть цена: его нельзя переиспользовать. Повтор запроса потребует нового стрима — это важно для ретраев, о которых дальше.
Ретраи и идемпотентность
Повторять запрос можно не потому, что он упал, а потому, что повтор безопасен. Ключевое свойство — идемпотентность: повтор не создаёт дополнительного эффекта.
| Метод | Идемпотентен | Комментарий |
|---|---|---|
GET, HEAD, OPTIONS, TRACE | да | читают, не меняют состояние |
PUT, DELETE | да | повтор приводит к тому же состоянию |
POST | нет | создаёт новую сущность при каждом вызове |
PATCH | обычно нет | зависит от операции, по умолчанию не повторяют |
Ретраить имеет смысл только временные сбои:
- сетевые ошибки до получения ответа:
ECONNRESET,ECONNREFUSED,ETIMEDOUT,EAI_AGAIN,UND_ERR_CONNECT_TIMEOUT,UND_ERR_HEADERS_TIMEOUT; - статусы
408,425,429,502,503,504; Retry-Afterв ответе — прямое указание, сколько ждать.
Не ретраят 400, 401, 403, 404, 409, 422, ошибки TLS и неверный сертификат: повтор не исправит ни валидацию, ни права, ни конфигурацию. 500 — спорный случай: он может быть транзиентным, но может и повторяться на каждом вызове, поэтому по умолчанию его не ретраят без явного решения.
Простейший цикл с экспоненциальной задержкой и jitter:
import { setTimeout as sleep } from 'node:timers/promises';
const RETRYABLE_CODES = new Set([
'ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'EAI_AGAIN',
'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT',
]);
const RETRYABLE_STATUS = new Set([408, 425, 429, 502, 503, 504]);
function isRetryable(err) {
if (err.name === 'TimeoutError') return true;
if (err.name === 'AbortError') return false;
if (RETRYABLE_STATUS.has(err.status)) return true;
const code = err.code ?? err.cause?.code;
return RETRYABLE_CODES.has(code);
}
async function withRetry(makeRequest, { attempts = 3, base = 200, cap = 2_000 } = {}) {
for (let attempt = 0; ; attempt++) {
try {
return await makeRequest();
} catch (err) {
if (attempt >= attempts - 1 || !isRetryable(err)) throw err;
const ceiling = Math.min(cap, base * 2 ** attempt);
await sleep(Math.random() * ceiling); // full jitter
}
}
}
Два условия, без которых эта схема не работает: 5xx на границе клиента нужно превратить в HttpError со статусом, иначе isRetryable увидит только успешный Response; а TimeoutError ретраят, только если это таймаут попытки, а не исчерпанный общий дедлайн.
makeRequest — именно фабрика, а не готовый промис: каждая попытка должна создать новый запрос. Стрим-тело и FormData одноразовы, а AbortSignal.timeout продолжает тикать и может прервать уже следующую попытку.
Для POST (и любого неидемпотентного вызова) нужен ключ идемпотентности — стабильный идентификатор операции, который сервер проверяет и не выполняет работу дважды:
import { randomUUID } from 'node:crypto';
const idempotencyKey = randomUUID(); // один на всю операцию, не на попытку
const res = await fetch(url, {
method: 'POST',
headers: { 'idempotency-key': idempotencyKey },
body: JSON.stringify(payload),
});
Если генерировать ключ внутри попытки, каждая попытка будет новой операцией и защита исчезнет.
Ещё две детали, без которых ретраи делают хуже:
- Перед повтором закройте тело неудачного ответа.
res.body.cancel()илиres.text()— иначе соединение останется занятым. - Ограничьте общий бюджет. Три попытки с backoff и таймаутом по пять секунд могут идти дольше, чем весь входящий запрос. Дедлайн считается на операцию, а не на попытку, и проверяется перед каждой из них.
Теория backoff, jitter и Retry-After подробно разобрана в статье «Ретраи и exponential backoff». Отдельный уровень — circuit breaker и bulkhead: они останавливают поток запросов к уже лежащему сервису, чтобы ретраи не превратились в самонанесённый DDoS. Этот механизм разбирается в статье «Таймауты, ретраи и graceful shutdown».
Клиент как модуль: конфигурация и наблюдаемость
Если fetch вызывают из десяти файлов с разными заголовками и таймаутами, поведение сервиса становится непредсказуемым. Внешний API заслуживает отдельного модуля: один агент, один базовый URL, одна политика ошибок и ретраев.
// clients/billing.js
import { Agent } from 'undici';
const agent = new Agent({
connections: 10,
connectTimeout: 2_000,
headersTimeout: 5_000,
bodyTimeout: 10_000,
keepAliveTimeout: 30_000,
});
const BASE_URL = process.env.BILLING_URL;
export async function createCharge(order, { signal } = {}) {
const res = await fetch(`${BASE_URL}/charges`, {
method: 'POST',
headers: {
'content-type': 'application/json',
'idempotency-key': order.id,
},
body: JSON.stringify({ amount: order.amount }),
dispatcher: agent,
signal: AbortSignal.any(
[signal, AbortSignal.timeout(5_000)].filter(Boolean),
),
});
if (!res.ok) throw new HttpError(res.status, await res.text());
return res.json();
}
Такой модуль — естественное место для метрик и логов. Что стоит фиксировать на каждом исходящем вызове:
- метод, host и путь — без query-параметров, в которых могут быть токены;
- статус, длительность и номер попытки — по ним видно деградацию зависимости;
- код ошибки из
err.cause—fetch failedбез причины бесполезен для диагностики; - request-id и
traceparent— их нужно явно положить в исходящие заголовки:AsyncLocalStorageхранит контекст внутри процесса, но сам HTTP-заголовки не добавляет; - число занятых соединений и размер очереди — если in-flight растёт, а статусы ещё
200, значит зависимость тормозит.
Чего логировать не стоит: заголовки authorization и cookie, тела запросов и ответов, полные URL с секретами. Успешные вызовы можно сэмплировать, ошибки — логировать всегда.
Отдельное решение — не менять глобальный fetch. Патчи глобального диспетчера влияют на все библиотеки в процессе, включая те, о существовании которых вы забыли. Явный dispatcher в клиенте внешнего сервиса делает настройку локальной и предсказуемой.
Отличия от браузерного fetch
API один, среда разная. Код, который «работает и там, и там», обычно использует только общее подмножество, а серверные возможности стоит держать в клиентском модуле.
| Аспект | Браузер | Node.js |
|---|---|---|
| CORS | проверяется браузером | не существует: сервер вызывает любой origin |
| Куки | cookie-jar, credentials | не хранятся, передаются вручную заголовком |
| Прокси | системный или браузерный | по умолчанию HTTP_PROXY не читается |
| Редиректы | автоматически, manual — opaque | автоматически, manual — реальный 3xx |
| Тело ответа | web stream без Node-хелперов | web stream + for await и Readable.fromWeb |
| Соединения | браузер управляет пулом | undici.Agent или http.Agent |
| HTTP/2 | обычно поддержан | встроенный fetch — только HTTP/1.1 |
keepalive | догрузка после закрытия вкладки | не управляет переиспользованием соединения |
Отсюда типичные ошибки при переносе кода: ожидание, что Node-клиент «сам» добавит куки, что HTTP_PROXY подхватится из окружения, что res.body можно без преобразования отдать в Node-pipeline (нужен Readable.fromWeb), что keepalive: true включает keep-alive. И обратная: в браузере нельзя отключить проверку TLS-сертификата или подменить агент, а в Node можно — и это почти всегда плохая идея, даже если очень хочется обойти стенд.
Частые ошибки
- Нет таймаута. Запрос висит, соединение занято, пул исчерпан, входящий клиент давно ушёл.
- Нет проверки
res.ok. Тело ошибки парсится как успешный ответ, а баг всплывает на уровне бизнес-логики. res.json()без чтения текста ошибки. HTML от прокси превращается вSyntaxError, исходный статус теряется.- Ретрай всего подряд. POST дублируется, 401 повторяется три раза, сбой внешнего сервиса усиливается.
- Ретрай с телом-стримом. Повтор использует уже исчерпанный поток и падает или отправляет пустое тело.
- Ключ идемпотентности внутри попытки. Каждый повтор становится новой операцией.
- Незакрытое тело ответа. Соединение не возвращается в пул; при потоке запросов кончаются сокеты.
arrayBuffer()для большого файла. Память растёт линейно от размера ответа и числа параллельных вызовов.- Безлимитный пул. Сотни соединений к чужому API вместо очереди и лимита.
- Логирование
err.messageбезerr.cause. В логе остаётсяfetch failedи ничего больше. - Глобальный патч диспетчера. Настройка для одного сервиса меняет поведение всех fetch в процессе.
Эксперименты
Три коротких запуска, которые показывают разницу между «код работает» и «код ведёт себя предсказуемо».
1. Ответ 500 — не исключение
const res = await fetch('http://localhost:3000/users');
console.log(res.status, res.ok); // 500 false
console.log(typeof res.json); // function — тело ещё можно разобрать
// никакого throw не было: статус проверяют вручную
Если заменить сервер на res.statusCode = 200, тот же код вернёт 200 true. Разницы в обработке ошибок нет — и это главная причина, по которой проверка статуса должна быть в клиенте.
2. Keep-alive переиспользует соединение
import { createServer, Agent, request } from 'node:http';
let connections = 0;
const server = createServer((req, res) => res.end('ok'));
server.on('connection', () => connections++);
server.listen(0, async () => {
const url = `http://127.0.0.1:${server.address().port}`;
const agent = new Agent({ keepAlive: true, maxSockets: 1 });
for (let i = 0; i < 3; i++) {
await new Promise((resolve, reject) => {
const req = request(url, { agent }, (res) => {
res.resume();
res.on('end', resolve);
});
req.on('error', reject);
req.end();
});
}
console.log(connections); // 1 — три запроса, одно TCP-соединение
agent.destroy();
server.close();
});
Замените agent на { agent: false } — счётчик покажет три соединения. Разница в стоимости — три DNS/TCP/TLS-рукопожатия вместо одного.
3. Таймаут обрывает ожидание
const started = performance.now();
try {
await fetch('http://localhost:3000/slow', {
signal: AbortSignal.timeout(100),
});
} catch (err) {
console.log(err.name, Math.round(performance.now() - started));
// TimeoutError ~100
}
Если маршрут /slow отвечает через 300 мс, без сигнала запрос вернётся примерно через 300 мс, а с сигналом — через 100. Обратите внимание: таймер стартовал при создании сигнала, поэтому создавать его нужно непосредственно перед вызовом.
Ключевые тезисы для интервью
fetchотклоняется только при сетевом сбое и отмене;4xx/5xx— это успешно полученный ответ, поэтому проверкаres.ok— обязательная часть клиента, а не деталь обработчика.- Настоящая причина
TypeError: fetch failedлежит вerr.cause(ECONNREFUSED,ENOTFOUND,UND_ERR_*), и логировать нужно её, а не общее сообщение. - Keep-alive переиспользует TCP/TLS-соединение, а пул ограничивает число одновременных соединений на origin; очередь сверх лимита ждёт в памяти, поэтому пул сочетают с дедлайном, а клиентский idle-таймаут держат меньше серверного.
- У запроса четыре независимых времени: установка соединения, заголовки, тело и общий дедлайн;
fetchумеет только сигнал,undici.Agentиhttp.requestдают раздельные таймауты, аAbortSignal.timeoutстартует в момент создания. - Ретрай допустим только для идемпотентных операций и временных сбоев, с backoff и jitter; тело-стрим нельзя переиспользовать, а ключ идемпотентности должен быть стабильным для всех попыток.
- Ответ читают потоком с backpressure и лимитом байт; не дочитанное тело держит соединение и не возвращается в пул.
- Серверный
fetch— не браузерный: нет CORS и cookie-jar, не читаетсяHTTP_PROXY,manual-редирект возвращает реальный3xx, а HTTP/2 встроенный клиент не поддерживает.
Заключение
HTTP-клиент в Node — это не выбор библиотеки, а набор решений о соединениях, времени, повторах и данных. fetch закрывает большинство задач, пока ему заданы пул, таймауты и проверка статуса; http.request нужен там, где требуется контроль над сокетом и потоком. Предсказуемость дают три вещи: дедлайн, проброшенный через всю цепочку вызовов, повтор только безопасных операций и чтение ответа с ограничением размера. Всё это стоит держать в одном модуле на каждый внешний сервис — тогда деградация зависимости видна в логах и метриках, а не выясняется по жалобам пользователей.
Полезные ссылки
- fetch в Node.js — глобальный
fetch, отличия от браузера,dispatcher - undici —
Agent,request, пулы соединений и таймауты - HTTP Agent —
keepAlive,maxSockets,maxFreeSockets - http.request — опции запроса,
signal,timeout - AbortSignal —
timeout,any,reason - Ретраи и exponential backoff — backoff, jitter,
Retry-After, идемпотентность