Объект options и его поля

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

Основная идея объекта заключается в том, что логика приложения отделяется от конфигурации. Это позволяет переиспользовать обработчики и изменять поведение системы без переписывания бизнес-логики.

Базовая форма объекта options

Структура объекта обычно имеет следующий вид:

const options = {
  method: 'GET',
  path: '/users',
  handler: (request, h) => {},
  validate: {},
  auth: false
};

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

Поле method

Поле method определяет HTTP-метод, для которого активируется обработчик.

Допустимые значения:

  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
  • OPTIONS

Пример:

const options = {
  method: 'POST',
  path: '/create-user',
  handler: createUserHandler
};

При отсутствии поля маршрут может становиться универсальным или наследовать поведение от уровня приложения, если библиотека поддерживает такие механизмы.

Поле path

path задаёт маршрут, по которому будет вызываться обработчик.

Особенности:

  • поддержка параметров маршрута
  • возможность вложенных сегментов
  • использование динамических частей

Пример:

const options = {
  method: 'GET',
  path: '/users/{id}',
  handler: getUserById
};

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

Поле handler

handler является центральной функцией обработки запроса. Она получает объект запроса и объект ответа (или утилитарный объект h, если используется паттерн helper).

Пример:

const options = {
  method: 'GET',
  path: '/status',
  handler: (request, h) => {
    return { status: 'ok' };
  }
};

Handler может быть:

  • синхронной функцией
  • асинхронной функцией
  • ссылкой на внешний модуль

Поле validate

validate используется для проверки входящих данных. Оно может включать валидацию параметров пути, query-параметров, тела запроса и заголовков.

Типичная структура:

const options = {
  method: 'POST',
  path: '/users',
  handler: createUser,
  validate: {
    payload: userSchema,
    query: querySchema,
    params: paramsSchema
  }
};

Основные области применения:

  • проверка структуры данных
  • контроль типов
  • ограничение допустимых значений
  • предотвращение некорректных запросов на уровне маршрута

Поле auth

Поле auth управляет доступом к маршруту.

Возможные значения:

  • false — авторизация отключена
  • строка стратегии — использование конкретного механизма аутентификации
  • объект конфигурации — расширенные настройки

Пример:

const options = {
  method: 'GET',
  path: '/profile',
  handler: profileHandler,
  auth: 'jwt'
};

Расширенный вариант:

auth: {
  strategy: 'jwt',
  scope: ['admin', 'user']
}

Поле payload

payload управляет обработкой тела запроса.

Основные параметры:

  • parse — включение или отключение парсинга
  • output — формат результата (raw, stream, data)
  • maxBytes — ограничение размера

Пример:

const options = {
  method: 'POST',
  path: '/upload',
  handler: uploadHandler,
  payload: {
    maxBytes: 1048576,
    output: 'stream'
  }
};

Это поле особенно важно при работе с файлами и потоковыми данными.

Поле response

response управляет формированием ответа, включая сериализацию и постобработку.

Пример:

const options = {
  method: 'GET',
  path: '/data',
  handler: getData,
  response: {
    modify: true,
    options: {
      language: 'en'
    }
  }
};

Возможности поля:

  • изменение структуры ответа
  • глобальное форматирование
  • применение трансформаций перед отправкой

Поле cache

cache отвечает за кэширование результата обработчика.

Пример:

const options = {
  method: 'GET',
  path: '/stats',
  handler: statsHandler,
  cache: {
    expiresIn: 60000,
    privacy: 'public'
  }
};

Основные параметры:

  • expiresIn — время жизни кэша
  • privacy — уровень приватности
  • segment — логическое разделение кэша

Поле timeout

timeout ограничивает время выполнения запроса.

Пример:

const options = {
  method: 'GET',
  path: '/slow-operation',
  handler: slowHandler,
  timeout: 5000
};

Если обработчик превышает заданное время, система прерывает выполнение и возвращает ошибку.

Поле tags

tags используется для маркировки маршрутов и последующей фильтрации или логирования.

const options = {
  method: 'GET',
  path: '/metrics',
  handler: metricsHandler,
  tags: ['internal', 'metrics']
};

Применение:

  • группировка маршрутов
  • аналитика
  • мониторинг
  • генерация документации

Поле pre

pre задаёт цепочку предварительных обработчиков, которые выполняются до основного handler.

Пример:

const options = {
  method: 'GET',
  path: '/dashboard',
  pre: [
    { method: checkAuth },
    { method: loadUser }
  ],
  handler: dashboardHandler
};

Особенности:

  • последовательное выполнение
  • передача результата между шагами
  • возможность остановки цепочки при ошибке

Поле plugins

plugins используется для расширения поведения маршрута через сторонние или внутренние модули.

const options = {
  method: 'GET',
  path: '/analytics',
  handler: analyticsHandler,
  plugins: {
    logging: {
      level: 'debug'
    }
  }
};

Механизм позволяет:

  • подключать расширения без изменения основного кода
  • конфигурировать поведение отдельных маршрутов
  • изолировать функциональность

Поле description и metadata

description и metadata применяются для документирования маршрута и хранения вспомогательной информации.

const options = {
  method: 'GET',
  path: '/health',
  handler: healthHandler,
  description: 'Проверка состояния сервиса',
  metadata: {
    version: '1.0',
    owner: 'backend-team'
  }
};

Использование:

  • генерация API-документации
  • внутренние справочники
  • интеграция с системами мониторинга

Взаимодействие полей внутри options

Объект options не является набором независимых параметров. Его поля взаимодействуют между собой:

  • validate влияет на входные данные для handler
  • auth определяет доступ к выполнению pre и handler
  • cache может полностью обходить handler при наличии валидного кэша
  • timeout может прерывать цепочку pre и основной обработчик
  • response применяется после выполнения всех этапов обработки

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

Оглавление