Переопределение параметров для конкретного вызова

В Iron параметры запроса строятся по принципу каскадной конфигурации: существуют глобальные настройки клиента, настройки экземпляра и локальные параметры конкретного вызова. Приоритет всегда остаётся за наиболее узким уровнем, что позволяет гибко управлять поведением библиотеки без дублирования конфигурации.

Любой вызов в Iron опирается на три уровня параметров:

  • глобальные настройки (default config)
  • настройки экземпляра клиента
  • параметры конкретного запроса

Принцип переопределения: локальные параметры всегда имеют наивысший приоритет и перекрывают значения, заданные выше по иерархии.

Это поведение критично для сценариев, где один и тот же клиент используется в разных условиях: разные таймауты, заголовки, режимы кэширования или политики повторных попыток.

Базовая конфигурация клиента

При создании клиента обычно задаются значения по умолчанию:

import { Iron } fr om "iron";

const client = new Iron({
  baseURL: "https://api.service.com",
  timeout: 5000,
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer TOKEN_DEFAULT"
  }
});

Эти параметры применяются ко всем запросам, если они не переопределены на более низком уровне.

Переопределение параметров в конкретном вызове

Основной механизм гибкости Iron заключается в возможности передать альтернативные параметры прямо в момент вызова метода.

const response = await client.get("/users", {
  timeout: 10000,
  headers: {
    "Authorization": "Bearer TOKEN_SPECIAL"
  }
});

В этом примере:

  • timeout заменяет значение 5000 на 10000
  • Authorization перезаписывает глобальный заголовок
  • остальные параметры (например, Content-Type) наследуются от клиента

Частичное переопределение объектов

Важно, что переопределение работает не на уровне полного замещения объекта, а на уровне слияния.

headers: {
  "Authorization": "Bearer TOKEN_SPECIAL"
}

В данном случае:

  • объект headers не заменяет полностью глобальный
  • происходит merge (поверхностное объединение)
  • ключи, отсутствующие в локальном объекте, сохраняются из глобального

Таким образом, если глобально задано:

headers: {
  "Content-Type": "application/json",
  "Authorization": "Bearer TOKEN_DEFAULT"
}

а локально передано:

headers: {
  "Authorization": "Bearer TOKEN_SPECIAL"
}

итоговый набор будет:

{
  "Content-Type": "application/json",
  "Authorization": "Bearer TOKEN_SPECIAL"
}

Переопределение параметров запроса для методов

Каждый HTTP-метод в Iron поддерживает локальные параметры.

GET-запросы

client.get("/posts", {
  params: {
    lim it: 10,
    sort: "desc"
  }
});

Если глобально задано:

params: {
  limit: 50
}

результат будет:

  • limit: 10 (локальный приоритет)
  • sort: desc (добавлен локально)
  • глобальный limit игнорируется

POST и тело запроса

Для методов с телом запроса переопределение работает аналогично:

client.post("/users", {
  data: {
    name: "Alex",
    role: "admin"
  }
});

Если глобально установлен шаблон:

data: {
  role: "user",
  active: true
}

результирующий payload:

{
  name: "Alex",
  role: "admin",
  active: true
}

Локальный role перекрывает глобальный, остальные поля объединяются.

Переопределение таймаутов и политик

Одним из наиболее частых сценариев является изменение сетевых ограничений для отдельных запросов.

client.get("/heavy-report", {
  timeout: 30000,
  retry: 0
});

Даже если клиент глобально настроен на:

timeout: 5000,
retry: 3

локальный вызов полностью заменяет поведение:

  • увеличивается допустимое время ожидания
  • отключаются повторные попытки

Переопределение базового URL

Iron позволяет временно направить запрос на другой сервер:

client.get("/status", {
  baseURL: "https://backup.api.service.com"
});

Это полезно для:

  • failover-сценариев
  • тестовых окружений
  • A/B маршрутизации

Глобальный baseURL при этом не изменяется и остаётся неизменным для других запросов.

Иерархия слияния параметров

Поведение системы можно формализовать:

  1. берутся глобальные настройки клиента
  2. применяется конфигурация экземпляра
  3. накладываются параметры вызова
  4. выполняется глубокое/поверхностное слияние (в зависимости от типа поля)

Простые значения (number, string, boolean) полностью заменяются.

Объекты проходят частичное объединение.

Переопределение через функцию-конфигуратор

В некоторых версиях Iron поддерживается передача конфигурации через функцию, что позволяет динамически изменять параметры перед отправкой запроса:

client.get("/profile", (config) => {
  return {
    ...config,
    timeout: config.env === "prod" ? 8000 : 2000
  };
});

Это добавляет ещё один уровень гибкости:

  • параметры вычисляются на лету
  • можно учитывать окружение, состояние приложения или предыдущие запросы

Приоритет конфликтующих значений

При пересечении ключей действует строгая схема:

  • локальный вызов > instance config > global config
  • внутри объекта: последний записанный ключ в merge побеждает только при одинаковом уровне

Пример:

global: { timeout: 5000 }
instance: { timeout: 7000 }
call: { timeout: 2000 }

итог: 2000

Типичные ошибки при переопределении

Часто встречаются логические ошибки при работе с вложенными объектами:

  • ожидание полного замещения headers вместо merge
  • попытка удалить ключ через undefined вместо явного управления конфигурацией
  • конфликт параметров params/data при копировании объектов

Понимание механизма слияния критично для предсказуемого поведения запросов.

Переопределение в цепочках запросов

При использовании цепочных вызовов параметры могут уточняться на каждом шаге:

client
  .withConfig({ timeout: 8000 })
  .get("/feed", { timeout: 2000 });

Здесь второй уровень перекрывает первый, несмотря на промежуточную настройку.

Переопределение параметров в Iron формирует основу гибкой конфигурации запросов, позволяя адаптировать поведение клиента без дублирования и без необходимости создавать новые экземпляры под каждую задачу.

Оглавление