Использование промежуточных обработчиков

Express - это веб-фреймворк маршрутизации и промежуточной обработки с минимальной собственной функциональностью: приложение Express, по сути, представляет собой серию вызовов функций промежуточной обработки.

Функции промежуточной обработки (middleware) - это функции, имеющие доступ к объекту запроса (req), объекту ответа (res) и к следующей функции промежуточной обработки в цикле “запрос-ответ” приложения. Следующая функция промежуточной обработки, как правило, обозначается переменной next.

Функции промежуточной обработки могут выполнять следующие задачи:

• Выполнение любого кода.
• Внесение изменений в объекты запросов и ответов.
• Завершение цикла “запрос-ответ”.
• Вызов следующей функции промежуточной обработки из стека.

Если текущая функция промежуточной обработки не завершает цикл “запрос-ответ”, она должна вызвать next() для передачи управления следующей функции промежуточной обработки. В противном случае запрос зависнет.

Приложение Express может использовать следующие типы промежуточных обработчиков:

• Промежуточный обработчик уровня приложения
• Промежуточный обработчик уровня маршрутизатора
• Промежуточный обработчик для обработки ошибок
• Встроенные промежуточные обработчики
• Промежуточные обработчики сторонних поставщиков ПО

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

Промежуточный обработчик уровня приложения

Свяжите промежуточный обработчик уровня приложения с экземпляром объекта приложения, воспользовавшись функциями app.use() и app.METHOD(), где METHOD - метод HTTP запроса, обрабатываемый функцией промежуточной обработки (например, GET, PUT или POST) в нижнем регистре.

В данном примере представлена функция промежуточной обработки без пути монтирования. Эта функция выполняется при каждом получении запроса приложением.

var app = express();

app.use(function (req, res, next) {
  console.log('Time:', Date.now());
  next();
});

В данном примере представлена функция промежуточной обработки, монтируемая в путь /user/:id. Эта функция выполняется для всех типов запросов HTTP в пути /user/:id.

app.use('/user/:id', function (req, res, next) {
  console.log('Request Type:', req.method);
  next();
});

В данном примере представлен маршрут и функция его обработки (система промежуточных обработчиков). Эта функция обрабатывает запросы GET, адресованные ресурсам в пути /user/:id.

app.get('/user/:id', function (req, res, next) {
  res.send('USER');
});

Ниже приводится пример загрузки последовательности функций промежуточной обработки в точку монтирования, с указанием пути монтирования. Этот пример иллюстрирует создание вспомогательного стека промежуточных обработчиков, с выводом информации о запросе для всех типов запросов HTTP, адресованных ресурсам в пути /user/:id.

app.use('/user/:id', function(req, res, next) {
  console.log('Request URL:', req.originalUrl);
  next();
}, function (req, res, next) {
  console.log('Request Type:', req.method);
  next();
});

Обработчики маршрутов позволяют определить несколько маршрутов для одного пути. В приведенном ниже примере определено два маршрута для запросов GET, адресованных ресурсам в пути /user/:id. Второй маршрут не создает никаких неудобств, но его вызов никогда не будет выполнен, поскольку первый маршрут завершает цикл “запрос-ответ”.

В данном примере представлен вспомогательный стек промежуточных обработчиков для обработки запросов GET, адресованных ресурсам в пути /user/:id.

app.get('/user/:id', function (req, res, next) {
  console.log('ID:', req.params.id);
  next();
}, function (req, res, next) {
  res.send('User Info');
});

// handler for the /user/:id path, which prints the user ID
app.get('/user/:id', function (req, res, next) {
  res.end(req.params.id);
});

Для того чтобы пропустить остальные функции дополнительной обработки в стеке промежуточных обработчиков маршрутизатора, вызовите next('route') для передачи управления следующему маршруту. ПРИМЕЧАНИЕ: next('route') работает только в функциях промежуточной обработки, загруженных с помощью функций app.METHOD() или router.METHOD().

В данном примере представлен вспомогательный стек промежуточных обработчиков для обработки запросов GET, адресованных ресурсам в пути /user/:id.

app.get('/user/:id', function (req, res, next) {
  // if the user ID is 0, skip to the next route
  if (req.params.id == 0) next('route');
  // otherwise pass the control to the next middleware function in this stack
  else next(); //
}, function (req, res, next) {
  // render a regular page
  res.render('regular');
});

// handler for the /user/:id path, which renders a special page
app.get('/user/:id', function (req, res, next) {
  res.render('special');
});

Промежуточный обработчик уровня маршрутизатора

Промежуточный обработчик уровня маршрутизатора работает так же, как и промежуточный обработчик уровня приложения, но он привязан к экземпляру express.Router().

var router = express.Router();

Загрузите промежуточный обработчик уровня маршрутизатора с помощью функций router.use() и router.METHOD().

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

var app = express();
var router = express.Router();

// a middleware function with no mount path. This code is executed for every request to the router
router.use(function (req, res, next) {
  console.log('Time:', Date.now());
  next();
});

// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path
router.use('/user/:id', function(req, res, next) {
  console.log('Request URL:', req.originalUrl);
  next();
}, function (req, res, next) {
  console.log('Request Type:', req.method);
  next();
});

// a middleware sub-stack that handles GET requests to the /user/:id path
router.get('/user/:id', function (req, res, next) {
  // if the user ID is 0, skip to the next router
  if (req.params.id == 0) next('route');
  // otherwise pass control to the next middleware function in this stack
  else next(); //
}, function (req, res, next) {
  // render a regular page
  res.render('regular');
});

// handler for the /user/:id path, which renders a special page
router.get('/user/:id', function (req, res, next) {
  console.log(req.params.id);
  res.render('special');
});

// mount the router on the app
app.use('/', router);

Промежуточный обработчик для обработки ошибок

Определите функции промежуточного обработчика для обработки ошибок так же, как другие функции промежуточной обработки, но с указанием не трех, а четырех аргументов в сигнатуре (err, req, res, next)):

app.use(function(err, req, res, next) {
  console.error(err.stack);
  res.status(500).send('Something broke!');
});

Подробная информация о промежуточном обработчике ошибок приведена в разделе Обработка ошибок.

Встроенные промежуточные обработчики

Начиная с версии 4.x, Express не является зависимым от Connect. За исключением express.static, все функции промежуточной обработки, ранее включенные в Express, находятся в отдельных модулях. Ознакомьтесь со списком функций промежуточной обработки.

express.static(root, [options])

Единственной встроенной функцией промежуточной обработки в Express является express.static. Эта функция основана на serve-static и отвечает за предоставление статических ресурсов приложения Express.

Аргумент root указывает на корневой каталог, из которого предоставляются статические ресурсы.

Необязательный объект options может содержать следующие свойства:

Ниже приводится пример использования функции промежуточной обработки express.static с объектом дополнительных опций:

var options = {
  dotfiles: 'ignore',
  etag: false,
  extensions: ['htm', 'html'],
  index: false,
  maxAge: '1d',
  redirect: false,
  setHeaders: function (res, path, stat) {
    res.set('x-timestamp', Date.now());
  }
}

app.use(express.static('public', options));

Для каждого приложения допускается наличие нескольких статических каталогов:

app.use(express.static('public'));
app.use(express.static('uploads'));
app.use(express.static('files'));

Дополнительную информацию о функции serve-static и ее опциях можно найти в документации по serve-static.

Промежуточные обработчики сторонних поставщиков ПО

Для расширения функциональности приложений Express используются промежуточные обработчики сторонних поставщиков ПО.

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

В приведенном ниже примере показана установка и загрузка функции промежуточной обработки для синтаксического анализа cookie cookie-parser.

$ npm install cookie-parser

var express = require('express');
var app = express();
var cookieParser = require('cookie-parser');

// load the cookie-parsing middleware
app.use(cookieParser());

Список функций промежуточных обработчиков, предоставляемых сторонними поставщиками ПО и часто используемых в Express, приведен в разделе Промежуточные обработчики сторонних поставщиков ПО.