Express

express()

Создаёт приложение Express. Функция express() — это функция верхнего уровня, экспортируемая модулем express.

var express = require('express')
var app = express()

Методы

express.json([options])

Это встроенная функция middleware в Express. Она анализирует входящие запросы с JSON-payload и основана на body-parser.

Возвращает middleware, который анализирует только JSON и рассматривает только запросы, где заголовок Content-Type соответствует параметру type. Этот парсер принимает любой Unicode-кодировку тела и поддерживает автоматическую распаковку gzip и deflate кодировок.

Новый объект body, содержащий обработанные данные, заполняется в объекте request после middleware (т.е. req.body), или пустым объектом ({}) если не было тела для анализа, заголовок Content-Type не совпал или произошла ошибка.

В следующей таблице описаны свойства необязательного объекта options.

express.raw([options])

Это встроенная функция middleware в Express. Она анализирует входящие payloads запроса в Buffer и основана на body-parser.

Возвращает middleware, анализирующий все тела как Buffer и рассматривает только запросы, где заголовок Content-Type соответствует параметру type. Этот парсер принимает любой Unicode-кодировку тела и поддерживает автоматическую распаковку gzip и deflate кодировок.

Новый body Buffer объект, содержащий обработанные данные, заполняется в объекте request после middleware (т.е. req.body), или пустым объектом ({}) если не было тела для анализа, заголовок Content-Type не совпал или произошла ошибка.

В следующей таблице описаны свойства необязательного объекта options.

express.Router([options])

Создаёт новый объект маршрутизатора router.

var router = express.Router([options])

Необязательный параметр options задаёт поведение маршрутизатора.

Вы можете добавить middleware и маршруты HTTP-методов (такие как get, put, post и так далее) к router, как и к приложению.

Для получения дополнительной информации см. Маршрутизатор.

express.static(root, [options])

Это встроенная функция middleware в Express. Она обслуживает статические файлы и основана на serve-static.

Аргумент root задаёт корневой каталог для обслуживания статических ресурсов. Функция определяет файл для обслуживания путём объединения req.url с предоставленным каталогом root. Если файл не найден, вместо отправки ответа 404, она вызывает next(), позволяя перейти к следующему middleware, позволяя укладывание и отступления.

В следующей таблице описаны свойства объекта options. Также см. пример ниже.

Для получения дополнительной информации, см. Отображение статических файлов в Express. и Использование middleware - Встроенные middleware.

dotfiles

Возможные значения для этого параметра:

• “allow” - Нет специального обращения к dotfiles.
• “deny” - Запретить запрос dotfile, ответить 403, затем вызвать next().
• “ignore” - Действовать так, как будто dotfile не существует, ответить 404, затем вызвать next().

ПРИМЕЧАНИЕ: По умолчанию файлы в каталогах, начинающихся с точки, не будут игнорироваться.

fallthrough

Когда этот параметр true, ошибки клиента, такие как неправильный запрос или запрос к несуществующему файлу, приведут к тому, что этот middleware просто вызовет next(), чтобы вызвать следующий middleware в стеке. Когда значение false, эти ошибки (даже 404), вызовут next(err).

Установите этот параметр в true, чтобы сопоставить несколько физических каталогов с одним веб-адресом или для маршрутов, заполняющих несуществующие файлы.

Используйте false если вы установили этот middleware в пути, предназначенном строго для одного каталога файловой системы, что позволяет избежать краткосрочных 404 для снижения накладных расходов. Этот middleware также ответит на все методы.

setHeaders

Для этого параметра укажите функцию для установки пользовательских заголовков ответа. Изменения заголовков должны происходить синхронно.

Подпись функции:

fn(res, path, stat)

Аргументы:

• res, объект response.
• path, путь к файлу, который отправляется.
• stat, объект stat отправляемого файла.

Пример использования express.static

Вот пример использования функции middleware 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))

express.text([options])

Это встроенная функция middleware в Express. Она анализирует входящие запросы в виде строки и основана на body-parser.

Возвращает middleware, который анализирует все тела как строку и рассматривает только запросы, где заголовок Content-Type соответствует параметру type. Этот анализатор принимает любой кодировку Unicode тела и поддерживает автоматическое раскрытие кодировок gzip и deflate.

Новая строка body, содержащая обработанные данные, заполняется в объекте request после middleware (т.е. req.body), или пустым объектом ({}) если не было тела для анализа, заголовок Content-Type не совпал или произошла ошибка.

Следующая таблица описывает свойства необязательного объекта options.

express.urlencoded([options])

Это встроенная функция middleware в Express. Она анализирует входящие запросы с кодировкой urlencoded и основана на body-parser.

Возвращает middleware, который анализирует только тела с кодировкой urlencoded и рассматривает только запросы, где заголовок Content-Type соответствует параметру type. Этот анализатор принимает только кодировку UTF-8 тела и поддерживает автоматическое раскрытие кодировок gzip и deflate.

Новый объект body , содержащий обработанные данные, заполняется в объекте request после middleware (т.е. req.body), или пустым объектом ({}) если не было тела для анализа, заголовок Content-Type не совпал или произошла ошибка. Этот объект будет содержать пары ключ-значение, где значение может быть строкой или массивом (если extended равно false) или любым типом (если extended равно true).

Следующая таблица описывает свойства необязательного объекта options.

Приложение

Объект app традиционно обозначает приложение Express. Он создаётся вызовом функции верхнего уровня express() , экспортируемой модулем Express:

var express = require('express')
var app = express()

app.get('/', function (req, res) {
  res.send('hello world')
})

app.listen(3000)

Объект app имеет методы для

• Маршрутизации HTTP-запросов; например, см. app.METHOD и app.param.
• Настройки middleware; см. app.route.
• Рендеринга HTML-представлений; см. app.render.
• Регистрации движка шаблонов; см. app.engine.

Он также имеет настройки (свойства), которые влияют на поведение приложения; для получения дополнительной информации, см. Настройки приложения.

Свойства

app.locals

Объект app.locals содержит свойства, которые являются локальными переменными внутри приложения и будут доступны в шаблонах, рендеренных с помощью res.render.

console.dir(app.locals.title)
// => 'My App'

console.dir(app.locals.email)
// => 'me@myapp.com'

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

Вы можете получать доступ к локальным переменным в шаблонах, рендеренных внутри приложения. Это полезно для предоставления функций-помощников в шаблонах, а также данных на уровне приложения. Локальные переменные доступны в middleware через req.app.locals (см. req.app)

app.locals.title = 'My App'
app.locals.strftime = require('strftime')
app.locals.email = 'me@myapp.com'

app.mountpath

Свойство app.mountpath содержит один или несколько шаблонов путей, на которых был смонтирован дочерний приложени.

var express = require('express')

var app = express() // the main app
var admin = express() // the sub app

admin.get('/', function (req, res) {
  console.log(admin.mountpath) // /admin
  res.send('Admin Homepage')
})

app.use('/admin', admin) // mount the sub app

Это аналогично свойству baseUrl объекта req, за исключением того, что req.baseUrl возвращает сопоставленный путь URL, а не сопоставленные шаблоны.

Если дочернее приложение смонтировано на нескольких шаблонах путей, app.mountpath возвращает список шаблонов, на которых оно смонтировано, как показано в следующем примере.

var admin = express()

admin.get('/', function (req, res) {
  console.dir(admin.mountpath) // [ '/adm*n', '/manager' ]
  res.send('Admin Homepage')
})

var secret = express()
secret.get('/', function (req, res) {
  console.log(secret.mountpath) // /secr*t
  res.send('Admin Secret')
})

admin.use('/secr*t', secret) // load the 'secret' router on '/secr*t', on the 'admin' sub app
app.use(['/adm*n', '/manager'], admin) // load the 'admin' router on '/adm*n' and '/manager', on the parent app

События

app.on('mount', callback(parent))

Событие mount срабатывает в дочернем приложении, когда оно смонтировано на родительском приложении. Родительское приложение передаётся в функцию обратного вызова.

var admin = express()

admin.on('mount', function (parent) {
  console.log('Admin Mounted')
  console.log(parent) // refers to the parent app
})

admin.get('/', function (req, res) {
  res.send('Admin Homepage')
})

app.use('/admin', admin)

Методы

app.all(path, callback [, callback ...])

Этот метод похож на стандартные методы app.METHOD(), но он соответствует всем HTTP-глаголам.

Аргументы

Примеры

Следующий обратный вызов выполняется для запросов на /secret независимо от того, используете ли вы GET, POST, PUT, DELETE или любой другой метод HTTP-запроса:

app.all('/secret', function (req, res, next) {
  console.log('Accessing the secret section ...')
  next() // pass control to the next handler
})

Метод app.all() полезен для сопоставления «глобальной» логики для определённых префиксов путей или произвольных совпадений. Например, если вы поместите следующее в начало всех других определений маршрутов, все маршруты от этого момента будут требовать аутентификации и автоматически загружать пользователя. Имейте в виду, что эти функции обратного вызова не обязательно должны быть конечными точками: loadUser может выполнить задачу, а затем вызвать next() для продолжения сопоставления последующих маршрутов.

app.all('*', requireAuthentication, loadUser)

Или эквивалентно:

app.all('*', requireAuthentication)
app.all('*', loadUser)

Другой пример — это список разрешенных «глобальных» функциональных возможностей. Пример аналогичен предыдущим, но он ограничивает только пути, начинающиеся с «/api»:

app.all('/api/*', requireAuthentication)

app.delete(path, callback [, callback ...])

Маршрутизирует HTTP-запросы DELETE на указанный путь с указанными функциями обратного вызова. Для получения дополнительной информации см. руководство по маршрутизации.

Аргументы

Пример

app.delete('/', function (req, res) {
  res.send('DELETE request to homepage')
})

app.disable(name)

Устанавливает булеву настройку name в значение false, где name — одно из свойств из таблицы настроек приложения. Вызов app.set('foo', false) для булевого свойства эквивалентен вызову app.disable('foo').

Например:

app.disable('trust proxy')
app.get('trust proxy')
// => false

app.disabled(name)

Возвращает true, если булева настройка name отключена (false), где name — одно из свойств из таблицы настроек приложения.

app.disabled('trust proxy')
// => true

app.enable('trust proxy')
app.disabled('trust proxy')
// => false

app.enable(name)

Устанавливает булеву настройку name в значение true, где name — одно из свойств из таблицы настроек приложения. Вызов app.set('foo', true) для булевого свойства эквивалентен вызову app.enable('foo').

app.enable('trust proxy')
app.get('trust proxy')
// => true

app.enabled(name)

Возвращает true, если настройка name включена (true), где name — одно из свойств из таблицы настроек приложения.

app.enabled('trust proxy')
// => false

app.enable('trust proxy')
app.enabled('trust proxy')
// => true

app.engine(ext, callback)

Регистрирует данный движок шаблонов callback как ext.

По умолчанию Express будет использовать движок, основанный на расширении файла. Например, если вы пытаетесь рендерить файл “foo.pug”, Express внутренне вызывает следующее и кеширует require() в последующих вызовах для повышения производительности.

app.engine('pug', require('pug').__express)

Используйте этот метод для движков шаблонов, которые не предоставляют .__express по умолчанию, или если вы хотите «сопоставить» другое расширение с движком шаблонов.

Например, чтобы сопоставить движок шаблонов EJS с файлами с расширением ".html":

app.engine('html', require('ejs').renderFile)

В этом случае, EJS предоставляет метод .renderFile(), имеющий ту же сигнатуру, что и ожидается от Express: (path, options, callback), хотя обратите внимание, что он алиасирует этот метод как ejs.__express внутри, поэтому если вы используете расширения ".ejs", вам ничего делать не нужно.

Некоторые движки шаблонов не следуют этой конвенции. Библиотека consolidate.js сопоставляет движки шаблонов Node с этой конвенцией, чтобы они работали без проблем с Express.

var engines = require('consolidate')
app.engine('haml', engines.haml)
app.engine('html', engines.hogan)

app.get(name)

Возвращает значение настройки приложения name, где name — одна из строк в таблице настроек приложения. Например:

app.get('title')
// => undefined

app.set('title', 'My Site')
app.get('title')
// => "My Site"

app.get(path, callback [, callback ...])

Маршрутизирует запросы HTTP GET на указанный путь с указанными функциями обратного вызова.

Аргументы

Для получения дополнительной информации см. руководство по маршрутизации.

Пример

app.get('/', function (req, res) {
  res.send('GET request to homepage')
})

app.listen(path, [callback])

Запускает UNIX-сокет и прослушивает подключения по заданному пути. Этот метод идентичен методу Node’s http.Server.listen().

var express = require('express')
var app = express()
app.listen('/tmp/sock')

app.listen([port[, host[, backlog]]][, callback])

Связывает и прослушивает подключения на указанном хосте и порту. Этот метод идентичен методу Node’s http.Server.listen().

Если порт опущен или равен 0, операционная система назначит произвольный свободный порт, что полезно в случаях автоматизированных задач (тестов и т.д.).

var express = require('express')
var app = express()
app.listen(3000)

Возвращаемый app методом express() — это, по сути, JavaScript Function, разработанный для передачи в HTTP-серверы Node в качестве обратного вызова для обработки запросов. Это упрощает предоставление как HTTP-, так и HTTPS-версий приложения с одним кодовым основанием, так как приложение не наследуется от них (это просто обратный вызов):

var express = require('express')
var https = require('https')
var http = require('http')
var app = express()

http.createServer(app).listen(80)
https.createServer(options, app).listen(443)

Метод app.listen() возвращает объект http.Server и (для HTTP) является удобным методом для следующего:

app.listen = function () {
  var server = http.createServer(this)
  return server.listen.apply(server, arguments)
}

app.METHOD(path, callback [, callback ...])

Маршрутизирует HTTP-запрос, где METHOD — это HTTP-метод запроса, например GET, PUT, POST и так далее, в нижнем регистре. Таким образом, фактические методы — app.get(), app.post(), app.put(), и так далее. Полный список см. в разделе Методы маршрутизации ниже.

Аргументы

Методы маршрутизации

Express поддерживает следующие методы маршрутизации, соответствующие методам HTTP с одинаковыми именами:

В документации API явно указаны только наиболее популярные HTTP-методы app.get(), app.post(), app.put(), и app.delete(). Однако остальные указанные выше методы работают точно так же.

Для маршрутизации методов, которые переводятся в недопустимые имена переменных JavaScript, используйте нотацию с квадратными скобками. Например, app['m-search']('/', function ....

Метод app.all() не происходит от какого-либо HTTP-метода и загружает промежуточное звено по указанному пути для всех HTTP-методов запросов. Для получения дополнительной информации см. app.all.

Для получения дополнительной информации о маршрутизации см. руководство по маршрутизации.

app.param([name], callback)

Добавляет триггеры обратного вызова к параметрам маршрута, где name — имя параметра или массив имён, а callback — функция обратного вызова. Параметрами функции обратного вызова являются объект запроса, объект ответа, следующее промежуточное звено, значение параметра и имя параметра в указанном порядке.

Если name — массив, триггер callback регистрируется для каждого объявленного параметра в порядке объявления. Кроме того, для каждого объявленного параметра, кроме последнего, вызов next внутри обратного вызова вызовет обратный вызов для следующего объявленного параметра. Для последнего параметра вызов next вызовет следующее промежуточное звено для обрабатываемого в данный момент маршрута, точно так же, как если бы name была просто строкой.

Например, когда :user присутствует в пути маршрута, вы можете сопоставить логику загрузки пользователя, чтобы автоматически предоставить req.user маршруту или выполнить валидацию входных данных параметра.

app.param('user', function (req, res, next, id) {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, function (err, user) {
    if (err) {
      next(err)
    } else if (user) {
      req.user = user
      next()
    } else {
      next(new Error('failed to load user'))
    }
  })
})

Функции обратного вызова параметров локальны для маршрутизатора, в котором они определены. Они не наследуются приложениями или маршрутизаторами, которые были подключены. Следовательно, обратные вызовы параметров, определённые на app, будут вызваны только параметрами маршрута, определёнными на маршрутах app.

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

app.param('id', function (req, res, next, id) {
  console.log('CALLED ONLY ONCE')
  next()
})

app.get('/user/:id', function (req, res, next) {
  console.log('although this matches')
  next()
})

app.get('/user/:id', function (req, res) {
  console.log('and this matches too')
  res.end()
})

В GET /user/42, выводится следующее:

CALLED ONLY ONCE
although this matches
and this matches too

app.param(['id', 'page'], function (req, res, next, value) {
  console.log('CALLED ONLY ONCE with', value)
  next()
})

app.get('/user/:id/:page', function (req, res, next) {
  console.log('although this matches')
  next()
})

app.get('/user/:id/:page', function (req, res) {
  console.log('and this matches too')
  res.end()
})

В GET /user/42/3, выводится следующее:

CALLED ONLY ONCE with 42
CALLED ONLY ONCE with 3
although this matches
and this matches too

Поведение метода app.param(name, callback) может быть полностью изменено путём передачи только функции в app.param(). Эта функция является пользовательской реализацией того, как должно вести себя app.param(name, callback) — она принимает два параметра и должна вернуть промежуточное звено.

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

Возвращаемое функцией промежуточное звено определяет поведение при захвате URL-параметра.

В этом примере сигнатура app.param(name, callback) изменена на app.param(name, accessId). Теперь app.param() будет принимать имя и число вместо имени и функции обратного вызова.

var express = require('express')
var app = express()

// customizing the behavior of app.param()
app.param(function (param, option) {
  return function (req, res, next, val) {
    if (val === option) {
      next()
    } else {
      next('route')
    }
  }
})

// using the customized app.param()
app.param('id', 1337)

// route to trigger the capture
app.get('/user/:id', function (req, res) {
  res.send('OK')
})

app.listen(3000, function () {
  console.log('Ready')
})

В этом примере сигнатура app.param(name, callback) остаётся такой же, но вместо функции обратного вызова промежуточного звена определена пользовательская функция проверки типа данных для валидации типа данных идентификатора пользователя.

app.param(function (param, validator) {
  return function (req, res, next, val) {
    if (validator(val)) {
      next()
    } else {
      next('route')
    }
  }
})

app.param('id', function (candidate) {
  return !isNaN(parseFloat(candidate)) && isFinite(candidate)
})

// captures '1-a_6' but not '543-azser-sder'
router.get('/[0-9]+-[[\\w]]*', function (req, res, next) { next() })

// captures '1-a_6' and '543-az(ser"-sder' but not '5-a s'
router.get('/[0-9]+-[[\\S]]*', function (req, res, next) { next() })

// captures all (equivalent to '.*')
router.get('[[\\s\\S]]*', function (req, res, next) { next() })

app.path()

Возвращает канонический путь приложения, строку.

var app = express()
var blog = express()
var blogAdmin = express()

app.use('/blog', blog)
blog.use('/admin', blogAdmin)

console.dir(app.path()) // ''
console.dir(blog.path()) // '/blog'
console.dir(blogAdmin.path()) // '/blog/admin'

Поведение этого метода может стать очень сложным в сложных случаях с подключенными приложениями: обычно лучше использовать req.baseUrl для получения канонического пути приложения.

app.post(path, callback [, callback ...])

Маршрутизирует запросы HTTP POST на указанный путь с указанными функциями обратного вызова. Дополнительную информацию см. в руководстве по маршрутизации.

Аргументы

Пример

app.post('/', function (req, res) {
  res.send('POST request to homepage')
})

app.put(path, callback [, callback ...])

Маршрутизирует запросы HTTP PUT на указанный путь с указанными функциями обратного вызова.

Аргументы

Пример

app.put('/', function (req, res) {
  res.send('PUT request to homepage')
})

app.render(view, [locals], callback)

Возвращает отрендеренный HTML представления с помощью функции callback. Принимает необязательный параметр, который представляет собой объект, содержащий локальные переменные для представления. Похож на res.render(), за исключением того, что сам не может отправить отрендеренное представление клиенту.

app.render('email', function (err, html) {
  // ...
})

app.render('email', { name: 'Tobi' }, function (err, html) {
  // ...
})

app.route(path)

Возвращает экземпляр отдельного маршрута, который затем можно использовать для обработки HTTP-глаголов с необязательным промежуточным ПО. Используйте app.route() для предотвращения дублирования имён маршрутов (и, следовательно, ошибок из-за опечаток).

var app = express()

app.route('/events')
  .all(function (req, res, next) {
    // runs for all HTTP verbs first
    // think of it as route specific middleware!
  })
  .get(function (req, res, next) {
    res.json({})
  })
  .post(function (req, res, next) {
    // maybe add a new event...
  })

app.set(name, value)

Присваивает настройку name значению value. Вы можете сохранить любое значение, которое вам нужно, но определённые имена могут быть использованы для настройки поведения сервера. Эти специальные имена перечислены в таблице настроек приложения.

Вызов app.set('foo', true) для булевого свойства эквивалентен вызову app.enable('foo'). Аналогично, вызов app.set('foo', false) для булевого свойства эквивалентен вызову app.disable('foo').

Получить значение настройки можно с помощью app.get().

app.set('title', 'My Site')
app.get('title') // "My Site"

Настройки приложения

В следующей таблице перечислены настройки приложения.

Обратите внимание, что подприложения:

• Не унаследуют значение настроек, имеющих значение по умолчанию. Вы должны установить значение в подприложении.
• Унаследуют значение настроек без значения по умолчанию; это явно отмечено в таблице ниже.

Исключения: подприложения унаследуют значение trust proxy, даже несмотря на то, что оно имеет значение по умолчанию (для совместимости с прошлыми версиями); подприложения не унаследуют значение view cache в производстве (когда NODE_ENV равно “производство”).

app.set('trust proxy', 'loopback')

app.set('trust proxy', 'loopback, 123.123.123.123')

app.set('trust proxy', 'loopback, linklocal, uniquelocal')

app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal'])

app.set('trust proxy', function (ip) {
  if (ip === '127.0.0.1' || ip === '123.123.123.123') return true // trusted IPs
  else return false
})

app.set('etag', function (body, encoding) {
  return generateHash(body, encoding) // consider the function is defined
})

app.use([path,] callback [, callback...])

Подключает указанную функцию middleware или функции по указанному пути: функция middleware выполняется, когда начало запрошенного пути соответствует path.

Аргументы

Описание

Маршрут будет соответствовать любому пути, который следует сразу за его путем с символом “/”. Например: app.use('/apple', ...) будет соответствовать “/apple”, “/apple/images”, “/apple/images/news” и так далее.

Так как path по умолчанию равно “/”, middleware, подключенный без пути, будет выполняться для каждого запроса к приложению.
Например, эта функция middleware будет выполняться для каждого запроса к приложению:

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

Функции middleware выполняются последовательно, поэтому порядок включения middleware важен.

// this middleware will not allow the request to go beyond it
app.use(function (req, res, next) {
  res.send('Hello World')
})

// requests will never reach this route
app.get('/', function (req, res) {
  res.send('Welcome')
})

Обработка ошибок middleware

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

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

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

Примеры путей

В следующей таблице приведены некоторые простые примеры допустимых значений path для монтирования middleware.

app.use('/abcd', function (req, res, next) {
  next()
})

app.use('/abc?d', function (req, res, next) {
  next()
})

app.use('/ab+cd', function (req, res, next) {
  next()
})

app.use('/ab*cd', function (req, res, next) {
  next()
})

app.use('/a(bc)?d', function (req, res, next) {
  next()
})

app.use(/\/abc|\/xyz/, function (req, res, next) {
  next()
})

app.use(['/abcd', '/xyza', /\/lmn|\/pqr/], function (req, res, next) {
  next()
})

Примеры функций обратного вызова middleware

В следующей таблице приведены некоторые простые примеры функций middleware, которые можно использовать в качестве аргумента callback к app.use(), app.METHOD(), и app.all(). Хотя примеры предназначены для app.use(), они также являются допустимыми для app.use(), app.METHOD(), и app.all().

app.use(function (req, res, next) {
  next()
})

var router = express.Router()
router.get('/', function (req, res, next) {
  next()
})
app.use(router)

var subApp = express()
subApp.get('/', function (req, res, next) {
  next()
})
app.use(subApp)

var r1 = express.Router()
r1.get('/', function (req, res, next) {
  next()
})

var r2 = express.Router()
r2.get('/', function (req, res, next) {
  next()
})

app.use(r1, r2)

var r1 = express.Router()
r1.get('/', function (req, res, next) {
  next()
})

var r2 = express.Router()
r2.get('/', function (req, res, next) {
  next()
})

app.use([r1, r2])

function mw1 (req, res, next) { next() }
function mw2 (req, res, next) { next() }

var r1 = express.Router()
r1.get('/', function (req, res, next) { next() })

var r2 = express.Router()
r2.get('/', function (req, res, next) { next() })

var subApp = express()
subApp.get('/', function (req, res, next) { next() })

app.use(mw1, [mw2, r1, r2], subApp)

Ниже приведены примеры использования middleware express.static в приложении Express.

Представление статического содержимого для приложения из каталога “public” в каталоге приложения:

// GET /style.css etc
app.use(express.static(path.join(__dirname, 'public')))

Монтирование middleware по пути “/static” для представления статического содержимого только в том случае, если путь запроса начинается с “/static”:

// GET /static/style.css etc.
app.use('/static', express.static(path.join(__dirname, 'public')))

Отключение регистрации для запросов статического содержимого путем загрузки middleware для регистрации после middleware для статического содержимого:

app.use(express.static(path.join(__dirname, 'public')))
app.use(logger())

Представление статических файлов из нескольких каталогов, но отдавая предпочтение “./public” перед другими:

app.use(express.static(path.join(__dirname, 'public')))
app.use(express.static(path.join(__dirname, 'files')))
app.use(express.static(path.join(__dirname, 'uploads')))

Запрос

Объект req представляет HTTP-запрос и имеет свойства для строки запроса, параметров, тела, HTTP-заголовков и так далее. В этом документе и по соглашению, объект всегда упоминается как req (а HTTP-ответ – как res), но его фактическое имя определяется параметрами функции обратного вызова, в которой вы работаете.

Например:

app.get('/user/:id', function (req, res) {
  res.send('user ' + req.params.id)
})

Но вы можете использовать и такое:

app.get('/user/:id', function (request, response) {
  response.send('user ' + request.params.id)
})

Объект req – это улучшенная версия собственного объекта запроса Node и поддерживает все встроенные поля и методы.

Свойства

req.app

Это свойство содержит ссылку на экземпляр приложения Express, использующего middleware.

Если вы следуете шаблону, в котором вы создаёте модуль, который просто экспортирует функцию middleware и require() её в вашем главном файле, то middleware может получить доступ к экземпляру Express через req.app

Например:

// index.js
app.get('/viewdirectory', require('./mymiddleware.js'))

// mymiddleware.js
module.exports = function (req, res) {
  res.send('The views directory is ' + req.app.get('views'))
}

req.baseUrl

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

Свойство req.baseUrl аналогично свойству mountpath объекта app, за исключением того, что app.mountpath возвращает сопоставленные шаблоны путей.

Например:

var greet = express.Router()

greet.get('/jp', function (req, res) {
  console.log(req.baseUrl) // /greet
  res.send('Konichiwa!')
})

app.use('/greet', greet) // load the router on '/greet'

Даже если вы используете шаблон пути или набор шаблонов путей для загрузки маршрутизатора, свойство baseUrl возвращает соответствующую строку, а не шаблон(ы). В следующем примере маршрутизатор greet загружен по двум шаблонам путей.

app.use(['/gre+t', '/hel{2}o'], greet) // load the router on '/gre+t' and '/hel{2}o'

Когда запрос отправляется на /greet/jp, req.baseUrl равно “/greet”. Когда запрос отправляется на /hello/jp, req.baseUrl равно “/hello”.

req.body

Содержит пары ключ-значение данных, отправленных в теле запроса. По умолчанию он undefined, и заполняется при использовании middleware для разбора тела, таких как express.json() или express.urlencoded().

Следующий пример показывает, как использовать middleware для разбора тела для заполнения req.body.

var express = require('express')

var app = express()

app.use(express.json()) // for parsing application/json
app.use(express.urlencoded({ extended: true })) // for parsing application/x-www-form-urlencoded

app.post('/profile', function (req, res, next) {
  console.log(req.body)
  res.json(req.body)
})

req.cookies

При использовании middleware cookie-parser это свойство является объектом, содержащим cookies, отправленные запросом. Если запрос не содержит cookies, по умолчанию оно {}.

// Cookie: name=tj
console.dir(req.cookies.name)
// => 'tj'

Если cookie подписан, нужно использовать req.signedCookies.

Для получения дополнительной информации, проблем или вопросов, обратитесь к cookie-parser.

req.fresh

Когда ответ всё ещё «свежий» в кэше клиента, возвращается true, в противном случае возвращается false, чтобы указать, что кэш клиента устарел, и должен быть отправлен полный ответ.

Когда клиент отправляет заголовок запроса Cache-Control: no-cache, чтобы указать запрос на полную перезагрузку, этот модуль вернёт false, чтобы сделать обработку таких запросов прозрачной.

Дополнительные сведения о работе проверки кэша можно найти в спецификации кэширования HTTP/1.1.

console.dir(req.fresh)
// => true

req.hostname

Содержит имя хоста, полученное из заголовка Host HTTP.

Когда настройка trust proxy не оценивается как false, это свойство вместо этого получит значение из заголовка X-Forwarded-Host.

Этот заголовок может быть задан клиентом или прокси-сервером.

Если в запросе присутствует более одного заголовка X-Forwarded-Host, используется значение первого заголовка. Это включает в себя единственный заголовок с разделителями-запятыми, в котором используется первое значение.

// Host: "example.com:3000"
console.dir(req.hostname)
// => 'example.com'

req.ip

Содержит удалённый IP-адрес запроса.

Когда настройка trust proxy не оценивается как false, значение этого свойства определяется из самого левого элемента в заголовке X-Forwarded-For. Этот заголовок может быть установлен клиентом или прокси-сервером.

console.dir(req.ip)
// => '127.0.0.1'

req.ips

Когда настройка trust proxy не оценивается как false, это свойство содержит массив IP-адресов, указанных в заголовке запроса X-Forwarded-For. В противном случае оно содержит пустой массив. Этот заголовок может быть установлен клиентом или прокси-сервером.

Например, если X-Forwarded-For равно client, proxy1, proxy2, req.ips будет ["client", "proxy1", "proxy2"], где proxy2 – это самый удалённый.

req.method

Содержит строку, соответствующую методу HTTP запроса: GET, POST, PUT, и так далее.

req.originalUrl

Это свойство очень похоже на req.url; однако, оно сохраняет исходный URL запроса, позволяя вам свободно переписывать req.url для внутренних целей маршрутизации. Например, функция «монтирования» app.use() перепишет req.url для удаления точки монтирования.

// GET /search?q=something
console.dir(req.originalUrl)
// => '/search?q=something'

req.originalUrl доступно как в middleware, так и в объектах маршрутизатора и представляет собой комбинацию req.baseUrl и req.url. Рассмотрим следующий пример:

app.use('/admin', function (req, res, next) { // GET 'http://www.example.com/admin/new?sort=desc'
  console.dir(req.originalUrl) // '/admin/new?sort=desc'
  console.dir(req.baseUrl) // '/admin'
  console.dir(req.path) // '/new'
  next()
})

req.params

Это свойство является объектом, содержащим свойства, сопоставленные с именованными параметрами маршрута. Например, если у вас есть маршрут /user/:name, то свойство «имя» доступно как req.params.name. Этот объект по умолчанию {}.

// GET /user/tj
console.dir(req.params.name)
// => 'tj'

При использовании регулярного выражения для определения маршрута, группы захвата предоставляются в массиве, используя req.params[n], где n - это n^-я группа захвата. Это правило применяется к неявно заданным совпадениям с подстановочными знаками в строковых маршрутах, таких как /file/*:

// GET /file/javascripts/jquery.js
console.dir(req.params[0])
// => 'javascripts/jquery.js'

Если вам нужно внести изменения в ключ в req.params, используйте обработчик app.param. Изменения применяются только к параметрам, уже определённым в пути маршрута.

Любые изменения, внесённые в объект req.params в обработчике или маршруте, будут сброшены.

req.path

Содержит часть пути URL-адреса запроса.

// example.com/users?sort=desc
console.dir(req.path)
// => '/users'

req.protocol

Содержит строку протокола запроса: либо http или (для запросов TLS) https.

Когда настройка trust proxy не равна false, это свойство будет использовать значение поля заголовка X-Forwarded-Proto , если оно присутствует. Этот заголовок может быть задан клиентом или прокси-сервером.

console.dir(req.protocol)
// => 'http'

req.query

Это свойство представляет собой объект, содержащий свойство для каждого параметра строки запроса в маршруте. При отключённом парсере параметров запроса, это пустой объект {}, в противном случае это результат конфигурированного парсера параметров.

Значение этого свойства может быть настроено с помощью настройки парсера запросов, чтобы соответствовать потребностям вашего приложения. Очень популярным парсером строк запроса является модуль qs, который используется по умолчанию. Модуль qs очень настраиваемый с множеством настроек, и может быть желательно использовать различные настройки, отличные от стандартных, для заполнения req.query:

var qs = require('qs')
app.setting('query parser', function (str) {
  return qs.parse(str, { /* custom options */ })
})

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

req.res

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

req.route

Содержит текущий сопоставленный маршрут, строку. Например:

app.get('/user/:id?', function userIdHandler (req, res) {
  console.log(req.route)
  res.send('GET')
})

Пример вывода из предыдущего фрагмента:

{ path: '/user/:id?',
  stack:
   [ { handle: [Function: userIdHandler],
       name: 'userIdHandler',
       params: undefined,
       path: undefined,
       keys: [],
       regexp: /^\/?$/i,
       method: 'get' } ],
  methods: { get: true } }

req.secure

Логическое свойство, равное true, если установлено TLS-соединение. Эквивалентно:

console.dir(req.protocol === 'https')
// => true

req.signedCookies

При использовании обработчика cookie-parser это свойство содержит подписанные файлы cookie, отправленные запросом, неподписанные и готовые к использованию. Подписанные файлы cookie находятся в отдельном объекте, чтобы показать намерение разработчика; в противном случае вредоносная атака может быть размещена на значениях req.cookie (которые легко подделать). Обратите внимание, что подписание cookie не делает его «скрытым» или зашифрованным; а просто предотвращает подделку (потому что секрет, используемый для подписи, является закрытым).

Если подписанные файлы cookie не отправлены, свойство по умолчанию {}.

// Cookie: user=tobi.CP7AWaXDfAKIRfH49dQzKJx7sKzzSoPq7/AcBBRVwlI3
console.dir(req.signedCookies.user)
// => 'tobi'

Для получения дополнительной информации, вопросов или проблем, обратитесь к cookie-parser.

req.stale

Указывает, является ли запрос «просроченным», и является противоположностью req.fresh. Для получения дополнительной информации см. req.fresh.

console.dir(req.stale)
// => true

req.subdomains

Массив поддоменов в имени домена запроса.

// Host: "tobi.ferrets.example.com"
console.dir(req.subdomains)
// => ['ferrets', 'tobi']

Свойство приложения subdomain offset, которое по умолчанию равно 2, используется для определения начала сегментов поддомена. Чтобы изменить это поведение, измените его значение с помощью app.set.

req.xhr

Логическое свойство, равное true , если поле заголовка запроса X-Requested-With равно «XMLHttpRequest», что указывает, что запрос был инициирован библиотекой клиента, такой как jQuery.

console.dir(req.xhr)
// => true

Методы

req.accepts(types)

Проверяет, являются ли указанные типы контента приемлемыми, на основе поля заголовка HTTP запроса Accept. Метод возвращает наилучшее совпадение, или, если ни один из указанных типов контента не приемлем, возвращает false (в этом случае приложение должно ответить 406 "Not Acceptable").

Значение type может быть одной строкой MIME-типа (например, «application/json»), именем расширения, таким как «json», запятой-разделенным списком или массивом. Для списка или массива метод возвращает наилучшее совпадение (если таковое имеется).

// Accept: text/html
req.accepts('html')
// => "html"

// Accept: text/*, application/json
req.accepts('html')
// => "html"
req.accepts('text/html')
// => "text/html"
req.accepts(['json', 'text'])
// => "json"
req.accepts('application/json')
// => "application/json"

// Accept: text/*, application/json
req.accepts('image/png')
req.accepts('png')
// => false

// Accept: text/*;q=.5, application/json
req.accepts(['html', 'json'])
// => "json"

Для получения дополнительной информации, или если у вас есть проблемы или вопросы, обратитесь к accepts.

req.acceptsCharsets(charset [, ...])

Возвращает первый принятый набор символов из указанных наборов символов, основываясь на поле заголовка HTTP запроса Accept-Charset. Если ни один из указанных наборов символов не принят, возвращает false.

Для получения дополнительной информации, или если у вас есть проблемы или вопросы, обратитесь к accepts.

req.acceptsEncodings(encoding [, ...])

Возвращает первое принятое кодирование из указанных кодирований, основываясь на поле заголовка HTTP запроса Accept-Encoding. Если ни одно из указанных кодирований не принято, возвращает false.

Для получения дополнительной информации, или если у вас есть проблемы или вопросы, обратитесь к accepts.

req.acceptsLanguages(lang [, ...])

Возвращает первый принятый язык из указанных языков, основываясь на поле заголовка HTTP запроса Accept-Language. Если ни один из указанных языков не принят, возвращает false.

Для получения дополнительной информации, или если у вас есть проблемы или вопросы, обратитесь к accepts.

req.get(field)

Возвращает указанное поле заголовка HTTP запроса (нечувствительное к регистру совпадение). Поля Referrer и Referer взаимозаменяемы.

req.get('Content-Type')
// => "text/plain"

req.get('content-type')
// => "text/plain"

req.get('Something')
// => undefined

Алиас req.header(field).

req.is(type)

Возвращает соответствующий тип содержимого, если поле заголовка HTTP запроса «Content-Type» соответствует MIME-типу, указанному параметром type. Если у запроса нет тела, возвращает null. В противном случае возвращает false.

// With Content-Type: text/html; charset=utf-8
req.is('html')
// => 'html'
req.is('text/html')
// => 'text/html'
req.is('text/*')
// => 'text/*'

// When Content-Type is application/json
req.is('json')
// => 'json'
req.is('application/json')
// => 'application/json'
req.is('application/*')
// => 'application/*'

req.is('html')
// => false

Для получения дополнительной информации, или если у вас есть проблемы или вопросы, обратитесь к type-is.

req.param(name [, defaultValue])

Возвращает значение параметра name при его наличии.

// ?name=tobi
req.param('name')
// => "tobi"

// POST name=tobi
req.param('name')
// => "tobi"

// /user/tobi for /user/:name
req.param('name')
// => "tobi"

Поиск выполняется в следующем порядке:

• req.params
• req.body
• req.query

Можно указать defaultValue для установки значения по умолчанию, если параметр не найден ни в одном из объектов запроса.

req.range(size[, options])

Парсер заголовка Range.

Параметр size — максимальный размер ресурса.

Параметр options — объект, который может содержать следующие свойства.

Будет возвращён массив диапазонов или отрицательные числа, указывающие на ошибку при разборе.

• -2 указывает на некорректный заголовок
• -1 указывает на недостижимый диапазон

// parse header from request
var range = req.range(1000)

// the type of the range
if (range.type === 'bytes') {
  // the ranges
  range.forEach(function (r) {
    // do something with r.start and r.end
  })
}

Ответ

Объект res представляет HTTP-ответ, отправляемый приложением Express при получении HTTP-запроса.

В этом документе и по умолчанию объект всегда обозначается как res (а HTTP-запрос обозначается как req) но его фактическое имя определяется параметрами функции обратного вызова, в которой вы работаете.

Например:

app.get('/user/:id', function (req, res) {
  res.send('user ' + req.params.id)
})

Но вы можете использовать и:

app.get('/user/:id', function (request, response) {
  response.send('user ' + request.params.id)
})

Объект res — расширенная версия собственного объекта ответа Node.js и поддерживает все встроенные поля и методы.

Свойства

res.app

Это свойство содержит ссылку на экземпляр приложения Express, использующего обработчик.

res.app идентично свойству req.app в объекте запроса.

res.headersSent

Логическое свойство, которое указывает, отправило ли приложение HTTP-заголовки для ответа.

app.get('/', function (req, res) {
  console.dir(res.headersSent) // false
  res.send('OK')
  console.dir(res.headersSent) // true
})

res.locals

Используйте это свойство для установки переменных, доступных в шаблонах, рендеренных с помощью res.render. Переменные, установленные в res.locals, доступны в рамках одного цикла запроса-ответа и не будут совмещены между запросами.

Для сохранения локальных переменных для использования в рендеринге шаблонов между запросами, используйте app.locals вместо этого.

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

app.use(function (req, res, next) {
  // Make `user` and `authenticated` available in templates
  res.locals.user = req.user
  res.locals.authenticated = !req.user.anonymous
  next()
})

Методы

res.append(field [, value])

Добавляет указанное поле value к заголовку HTTP-ответа field. Если заголовок ещё не задан, он создаёт заголовок с указанным значением. Параметр value может быть строкой или массивом.

Примечание: вызов res.set() после res.append() сбросит ранее установленное значение заголовка.

res.append('Link', ['<http://localhost/>', '<http://localhost:3000/>'])
res.append('Set-Cookie', 'foo=bar; Path=/; HttpOnly')
res.append('Warning', '199 Miscellaneous warning')

res.attachment([filename])

Устанавливает поле заголовка HTTP-ответа Content-Disposition в «attachment». Если передан filename, то устанавливает Content-Type на основе расширения файла через res.type(), и устанавливает параметр Content-Disposition «filename=».

res.attachment()
// Content-Disposition: attachment

res.attachment('path/to/logo.png')
// Content-Disposition: attachment; filename="logo.png"
// Content-Type: image/png

res.cookie(name, value [, options])

Устанавливает cookie name со значением value. Параметр value может быть строкой или объектом, преобразованным в JSON.

Параметр options — это объект, который может иметь следующие свойства.

Например:

res.cookie('name', 'tobi', { domain: '.example.com', path: '/admin', secure: true })
res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true })

Можно установить несколько cookie в одном ответе, вызвав res.cookie несколько раз, например:

res
  .status(201)
  .cookie('access_token', 'Bearer ' + token, {
    expires: new Date(Date.now() + 8 * 3600000) // cookie will be removed after 8 hours
  })
  .cookie('test', 'test')
  .redirect(301, '/admin')

Параметр encode позволяет выбрать функцию для кодирования значения cookie. Не поддерживает асинхронные функции.

Пример использования: необходимо установить cookie для всего домена другого сайта в вашей организации. Этот другой сайт (не под вашим управлением) не использует URI-кодированные значения cookie.

// Default encoding
res.cookie('some_cross_domain_cookie', 'http://mysubdomain.example.com', { domain: 'example.com' })
// Result: 'some_cross_domain_cookie=http%3A%2F%2Fmysubdomain.example.com; Domain=example.com; Path=/'

// Custom encoding
res.cookie('some_cross_domain_cookie', 'http://mysubdomain.example.com', { domain: 'example.com', encode: String })
// Result: 'some_cross_domain_cookie=http://mysubdomain.example.com; Domain=example.com; Path=/;'

Параметр maxAge — это удобный параметр для установки «expires» относительно текущего времени в миллисекундах. Следующее эквивалентно второму примеру выше.

res.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true })

Можно передать объект как параметр value; он затем сериализуется как JSON и парсится bodyParser() middleware.

res.cookie('cart', { items: [1, 2, 3] })
res.cookie('cart', { items: [1, 2, 3] }, { maxAge: 900000 })

При использовании middleware cookie-parser, этот метод также поддерживает подписанные cookie. Просто включите параметр signed со значением true. Тогда res.cookie() будет использовать секрет, переданный cookieParser(secret), для подписи значения.

res.cookie('name', 'tobi', { signed: true })

Позже вы можете получить доступ к этому значению через объект req.signedCookie.

res.clearCookie(name [, options])

Очищает cookie, указанную параметром name. Для получения подробной информации об объекте options, см. res.cookie().

res.cookie('name', 'tobi', { path: '/admin' })
res.clearCookie('name', { path: '/admin' })

res.download(path [, filename] [, options] [, fn])

Передаёт файл по адресу path как «attachment». Обычно браузеры будут запрашивать у пользователя загрузку. По умолчанию параметр заголовка Content-Disposition «filename=» определяется из аргумента path, но может быть переопределён параметром filename. Если path — относительный путь, он будет основан на текущей рабочей директории процесса или параметре root, если он указан.

Следующая таблица содержит подробную информацию о параметре options.

Метод вызывает функцию обратного вызова fn(err) при завершении передачи или возникновении ошибки. Если функция обратного вызова указана и возникает ошибка, функция обратного вызова должна явно обработать процесс ответа, либо завершив цикл запроса-ответа, либо передав управление следующему маршруту.

res.download('/report-12345.pdf')

res.download('/report-12345.pdf', 'report.pdf')

res.download('/report-12345.pdf', 'report.pdf', function (err) {
  if (err) {
    // Handle error, but keep in mind the response may be partially-sent
    // so check res.headersSent
  } else {
    // decrement a download credit, etc.
  }
})

res.end([data] [, encoding])

Завершает процесс ответа. Этот метод фактически взят из ядра Node.js, а именно из метода response.end() метода http.ServerResponse.

Используется для быстрого завершения ответа без каких-либо данных. Если необходимо ответить данными, используйте методы, такие как res.send() и res.json().

res.end()
res.status(404).end()

res.format(object)

Выполняет переговорный процесс по заголовку Accept HTTP запроса, если он присутствует. Использует req.accepts() для выбора обработчика запроса на основе допустимых типов, упорядоченных по их качественным значениям. Если заголовок не указан, вызывается первая функция обратного вызова. Если соответствие не найдено, сервер отвечает 406 «Неприемлемо» или вызывает функцию обратного вызова default.

Заголовок ответа Content-Type устанавливается, когда выбирается функция обратного вызова. Однако вы можете изменить это в рамках функции обратного вызова, используя такие методы, как res.set() или res.type().

Следующий пример ответит { "message": "hey" } при заданном заголовке Accept «application/json» или «*/json» (однако, если это «*/*», то ответом будет «hey»).

res.format({
  'text/plain': function () {
    res.send('hey')
  },

  'text/html': function () {
    res.send('<p>hey</p>')
  },

  'application/json': function () {
    res.send({ message: 'hey' })
  },

  default: function () {
    // log the request and respond with 406
    res.status(406).send('Not Acceptable')
  }
})

В дополнение к канонизированным MIME-типам вы также можете использовать имена расширений, сопоставленные с этими типами, для немного более краткой реализации:

res.format({
  text: function () {
    res.send('hey')
  },

  html: function () {
    res.send('<p>hey</p>')
  },

  json: function () {
    res.send({ message: 'hey' })
  }
})

res.get(field)

Возвращает HTTP-заголовок ответа, указанный параметром field. Сопоставление регистронезависимое.

res.get('Content-Type')
// => "text/plain"

res.json([body])

Отправляет JSON-ответ. Этот метод отправляет ответ (с правильным типом содержимого), который является параметром, преобразованным в строку JSON с помощью JSON.stringify().

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

res.json(null)
res.json({ user: 'tobi' })
res.status(500).json({ error: 'message' })

res.jsonp([body])

Отправляет JSON-ответ с поддержкой JSONP. Этот метод идентичен res.json(), за исключением того, что он включает поддержку вызова JSONP.

res.jsonp(null)
// => callback(null)

res.jsonp({ user: 'tobi' })
// => callback({ "user": "tobi" })

res.status(500).jsonp({ error: 'message' })
// => callback({ "error": "message" })

По умолчанию имя функции обратного вызова JSONP просто callback. Переопределите это с помощью настройки имя функции обратного вызова jsonp.

Ниже приведены примеры JSONP-ответов, использующих тот же код:

// ?callback=foo
res.jsonp({ user: 'tobi' })
// => foo({ "user": "tobi" })

app.set('jsonp callback name', 'cb')

// ?cb=foo
res.status(500).jsonp({ error: 'message' })
// => foo({ "error": "message" })

res.links(links)

Объединяет links в качестве свойств параметра, чтобы заполнить поле заголовка ответа HTTP Link.

Например, следующий вызов:

res.links({
  next: 'http://api.example.com/users?page=2',
  last: 'http://api.example.com/users?page=5'
})

Даёт следующие результаты:

Link: <http://api.example.com/users?page=2>; rel="next",
      <http://api.example.com/users?page=5>; rel="last"

res.location(path)

Устанавливает заголовок ответа HTTP Location на указанный параметр path.

res.location('/foo/bar')
res.location('http://example.com')
res.location('back')

Значение path «back» имеет специальное значение, оно относится к URL, указанному в заголовке Referer запроса. Если заголовок Referer не указан, он относится к «/».

res.redirect([status,] path)

Перенаправляет на URL, полученный из указанного path, с указанным status, положительным целым числом, соответствующим коду состояния HTTP . Если не указано, status по умолчанию равно “302 «Найдено».

res.redirect('/foo/bar')
res.redirect('http://example.com')
res.redirect(301, 'http://example.com')
res.redirect('../login')

Перенаправления могут быть полными URL для перенаправления на другой сайт:

res.redirect('http://google.com')

Перенаправления могут быть относительными к корню имени хоста. Например, если приложение находится на http://example.com/admin/post/new, следующее перенаправит на URL %%%CODE_BLOCK_800%%:

res.redirect('/admin')

Перенаправления могут быть относительными к текущему URL. Например, из http://example.com/blog/admin/ (заметьте, что в конце есть слеш), следующее перенаправит на URL %%%CODE_BLOCK_803%%.

res.redirect('post/new')

Перенаправление на post/new из http://example.com/blog/admin (без слеша в конце) перенаправит на %%%CODE_BLOCK_807%%.

Если вышеуказанное поведение кажется запутанным, представьте сегменты пути как каталоги (с завершающими слешами) и файлы, и это начнёт проясняться.

Также возможны перенаправления, относительные к пути. Если вы находитесь на http://example.com/admin/post/new, следующее перенаправит на http://example.com/admin/post:

res.redirect('..')

Перенаправление по back возвращает запрос обратно к ссылке-источнику, по умолчанию /, если ссылка-источник отсутствует.

res.redirect('back')

res.render(view [, locals] [, callback])

Рендерит view и отправляет сгенерированный HTML-строку клиенту. Дополнительные параметры:

• locals, объект, свойства которого определяют локальные переменные для представления.
• callback, функция обратного вызова. Если она предоставлена, метод возвращает как возможную ошибку, так и сгенерированную строку, но не выполняет автоматическую отправку ответа. При возникновении ошибки метод вызывает next(err) внутри.

Аргумент view — это строка, представляющая путь к файлу представления для рендеринга. Это может быть абсолютный путь или путь, относительный к настройке views. Если путь не содержит расширения файла, то расширение файла определяется настройкой view engine. Если путь содержит расширение файла, Express загрузит модуль для указанного движка шаблонов (через require()) и рендерит его с помощью функции __express загруженного модуля.

Для получения дополнительной информации см. Использование движков шаблонов с Express.

ПРИМЕЧАНИЕ: Аргумент view выполняет операции с файловой системой, такие как чтение файла из диска и оценка модулей Node.js, поэтому по соображениям безопасности не должен содержать входные данные от пользователя.

// send the rendered view to the client
res.render('index')

// if a callback is specified, the rendered HTML string has to be sent explicitly
res.render('index', function (err, html) {
  res.send(html)
})

// pass a local variable to the view
res.render('user', { name: 'Tobi' }, function (err, html) {
  // ...
})

res.req

res.send([body])

Отправляет HTTP-ответ.

Параметр body может быть объектом Buffer, String, объектом, Boolean, или Array. Например:

res.send(Buffer.from('whoop'))
res.send({ some: 'json' })
res.send('<p>some html</p>')
res.status(404).send('Sorry, we cannot find that!')
res.status(500).send({ error: 'something blew up' })

Этот метод выполняет множество полезных задач для простых ответов, не связанных с потоковой передачей: например, он автоматически задаёт поле HTTP-заголовка Content-Length (если оно не определено ранее) и предоставляет автоматическую поддержку кэширования HEAD и HTTP.

Когда параметр — объект Buffer, метод устанавливает поле заголовка ответа Content-Type в «application/octet-stream», если оно не определено ранее, как показано ниже:

res.set('Content-Type', 'text/html')
res.send(Buffer.from('<p>some html</p>'))

Когда параметр — String, метод устанавливает Content-Type в «text/html»:

res.send('<p>some html</p>')

Когда параметр — Array или Object, Express отвечает с JSON-представлением:

res.send({ user: 'tobi' })
res.send([1, 2, 3])

res.sendFile(path [, options] [, fn])

Передаёт файл по заданному path. Устанавливает поле HTTP-заголовка ответа Content-Type на основе расширения имени файла. Если опция root не установлена в объекте options, path должен быть абсолютным путём к файлу.

В следующей таблице приведены подробности параметра options.

Метод вызывает функцию обратного вызова fn(err) при завершении передачи или возникновении ошибки. Если функция обратного вызова задана и возникает ошибка, функция обратного вызова должна явно обработать процесс ответа, либо завершив цикл запроса-ответа, либо передав управление следующему маршруту.

Вот пример использования res.sendFile со всеми его аргументами.

app.get('/file/:name', function (req, res, next) {
  var options = {
    root: path.join(__dirname, 'public'),
    dotfiles: 'deny',
    headers: {
      'x-timestamp': Date.now(),
      'x-sent': true
    }
  }

  var fileName = req.params.name
  res.sendFile(fileName, options, function (err) {
    if (err) {
      next(err)
    } else {
      console.log('Sent:', fileName)
    }
  })
})

Следующий пример демонстрирует использование res.sendFile для предоставления подробной поддержки передачи файлов:

app.get('/user/:uid/photos/:file', function (req, res) {
  var uid = req.params.uid
  var file = req.params.file

  req.user.mayViewFilesFrom(uid, function (yes) {
    if (yes) {
      res.sendFile('/uploads/' + uid + '/' + file)
    } else {
      res.status(403).send("Sorry! You can't see that.")
    }
  })
})

Для получения дополнительной информации или при возникновении проблем, см. send.

res.sendStatus(statusCode)

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

res.sendStatus(404)

Дополнительная информация о кодах состояния HTTP

res.set(field [, value])

Устанавливает HTTP-заголовок ответа field в значение value. Чтобы установить сразу несколько полей, передайте объект в качестве параметра.

res.set('Content-Type', 'text/plain')

res.set({
  'Content-Type': 'text/plain',
  'Content-Length': '123',
  ETag: '12345'
})

Алиас для res.header(field [, value]).

res.status(code)

Устанавливает HTTP-статус для ответа. Это алиас метода Node.js response.statusCode, поддерживающий цепочку вызовов.

res.status(403).end()
res.status(400).send('Bad Request')
res.status(404).sendFile('/absolute/path/to/404.png')

res.type(type)

Устанавливает HTTP-заголовок Content-Type на MIME-тип, определённый указанным type. Если type содержит символ «/», то устанавливает Content-Type на точное значение type, в противном случае предполагается, что это расширение файла, и MIME-тип ищется в отображении с помощью метода express.static.mime.lookup().

res.type('.html')
// => 'text/html'
res.type('html')
// => 'text/html'
res.type('json')
// => 'application/json'
res.type('application/json')
// => 'application/json'
res.type('png')
// => 'image/png'

res.vary(field)

Добавляет поле в заголовок ответа Vary, если его там ещё нет.

res.vary('User-Agent').render('docs')

Маршрутизатор

Объект router — это изолированный экземпляр middleware и маршрутов. Его можно рассматривать как «мини-приложение», способное выполнять только функции middleware и маршрутизации. Каждое приложение Express имеет встроенный маршрутизатор приложения.

Маршрутизатор ведёт себя как middleware, поэтому его можно использовать в качестве аргумента app.use() или аргумента для метода use() другого маршрутизатора.

Объект express на верхнем уровне имеет метод Router(), который создаёт новый объект router.

После создания объекта маршрутизатора можно добавить middleware и маршруты HTTP-методов (например, get, put, post, и так далее) к нему, как и к приложению. Например:

// invoked for any requests passed to this router
router.use(function (req, res, next) {
  // .. some logic here .. like any other middleware
  next()
})

// will handle any request that ends in /events
// depends on where the router is "use()'d"
router.get('/events', function (req, res, next) {
  // ..
})

Затем можно использовать маршрутизатор для определённого корневого URL, разделяя маршруты на файлы или даже мини-приложения.

// only requests to /calendar/* will be sent to our "router"
app.use('/calendar', router)

Методы

router.all(path, [callback, ...] callback)

Этот метод похож на методы router.METHOD() методов, за исключением того, что он соответствует всем HTTP-методам (глаголам).

Этот метод чрезвычайно полезен для отображения «глобальной» логики для определённых префиксов путей или произвольных соответствий. Например, если вы поместите следующий маршрут в начало всех других определений маршрутов, все маршруты с этого момента будут требовать аутентификации и автоматически загружать пользователя. Имейте в виду, что эти обратные вызовы не обязательно должны быть конечными точками; loadUser может выполнить задачу, а затем вызвать next(), чтобы продолжить сопоставление последующих маршрутов.

router.all('*', requireAuthentication, loadUser)

Или эквивалент:

router.all('*', requireAuthentication)
router.all('*', loadUser)

Ещё один пример — это «глобальная» функциональность с разрешениями. В этом примере, как и раньше, но он ограничивает только пути с префиксом «/api»:

router.all('/api/*', requireAuthentication)

router.METHOD(path, [callback, ...] callback)

Методы router.METHOD() обеспечивают функциональность маршрутизации в Express, где METHOD — это один из HTTP-методов, таких как GET, PUT, POST и так далее, в нижнем регистре. Таким образом, фактические методы — это router.get(), router.post(), router.put(), и так далее.

Вы можете указать несколько обратных вызовов, и все они обрабатываются одинаково и ведут себя как middleware, за исключением того, что эти обратные вызовы могут вызвать next('route'), чтобы обойти оставшиеся обратные вызовы маршрута. Вы можете использовать этот механизм для выполнения предварительных условий по маршруту, а затем передать управление последующим маршрутам, если нет необходимости продолжать обработку сопоставленного маршрута.

Следующий фрагмент иллюстрирует самое простое возможное определение маршрута. Express преобразует строки путей в регулярные выражения, используемые внутри для сопоставления входящих запросов. Строки запросов не учитываются при выполнении этих сопоставлений, например, «GET /» будет соответствовать следующему маршруту, как и «GET /?name=tobi».

router.get('/', function (req, res) {
  res.send('hello world')
})

Вы также можете использовать регулярные выражения — полезные, если у вас есть очень специфические ограничения, например, следующее будет соответствовать «GET /commits/71dbb9c», а также «GET /commits/71dbb9c..4c084f9».

router.get(/^\/commits\/(\w+)(?:\.\.(\w+))?$/, function (req, res) {
  var from = req.params[0]
  var to = req.params[1] || 'HEAD'
  res.send('commit range ' + from + '..' + to)
})

router.param(name, callback)

Добавляет триггеры обратного вызова к параметрам маршрута, где name — имя параметра, а callback — функция обратного вызова. Хотя name технически необязательна, использование этого метода без неё устарело начиная с Express v4.11.0 (см. ниже).

Параметрами функции обратного вызова являются:

• req, объект запроса.
• res, объект ответа.
• next, указывающий на следующую функцию middleware.
• Значение параметра name.
• Имя параметра.

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

router.param('user', function (req, res, next, id) {
  // try to get the user details from the User model and attach it to the request object
  User.find(id, function (err, user) {
    if (err) {
      next(err)
    } else if (user) {
      req.user = user
      next()
    } else {
      next(new Error('failed to load user'))
    }
  })
})

Функции обратного вызова параметров локальны для маршрутизатора, в котором они определены. Они не наследуются подключенными приложениями или маршрутизаторами. Следовательно, обратные вызовы параметров, определенные в router, будут срабатывать только для параметров маршрута, определенных в router маршрутах.

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

router.param('id', function (req, res, next, id) {
  console.log('CALLED ONLY ONCE')
  next()
})

router.get('/user/:id', function (req, res, next) {
  console.log('although this matches')
  next()
})

router.get('/user/:id', function (req, res) {
  console.log('and this matches too')
  res.end()
})

В GET /user/42, выводится следующее:

CALLED ONLY ONCE
although this matches
and this matches too

Поведение метода router.param(name, callback) можно полностью изменить, передав только функцию в router.param(). Эта функция представляет собой пользовательскую реализацию поведения router.param(name, callback) — она принимает два параметра и должна возвращать middleware.

Первый параметр этой функции — имя параметра URL, который должен быть захвачен, второй параметр может быть любым JavaScript-объектом, который может использоваться для возвращения реализации middleware.

Middleware, возвращаемая функцией, определяет поведение при захвате параметра URL.

В этом примере сигнатура router.param(name, callback) изменена на router.param(name, accessId). Вместо приема имени и обратного вызова, router.param() теперь будет принимать имя и число.

var express = require('express')
var app = express()
var router = express.Router()

// customizing the behavior of router.param()
router.param(function (param, option) {
  return function (req, res, next, val) {
    if (val === option) {
      next()
    } else {
      res.sendStatus(403)
    }
  }
})

// using the customized router.param()
router.param('id', '1337')

// route to trigger the capture
router.get('/user/:id', function (req, res) {
  res.send('OK')
})

app.use(router)

app.listen(3000, function () {
  console.log('Ready')
})

В этом примере сигнатура router.param(name, callback) остается прежней, но вместо обратной функции middleware была определена пользовательская функция проверки типа данных для валидации типа данных идентификатора пользователя.

router.param(function (param, validator) {
  return function (req, res, next, val) {
    if (validator(val)) {
      next()
    } else {
      res.sendStatus(403)
    }
  }
})

router.param('id', function (candidate) {
  return !isNaN(parseFloat(candidate)) && isFinite(candidate)
})

router.route(path)

Возвращает экземпляр отдельного маршрута, который вы затем можете использовать для обработки HTTP-глаголов с необязательным middleware. Используйте router.route() для предотвращения дублирования имен маршрутов и, таким образом, ошибок ввода.

Продолжая пример router.param() выше, следующий код демонстрирует, как использовать router.route() для указания различных обработчиков HTTP-методов.

var router = express.Router()

router.param('user_id', function (req, res, next, id) {
  // sample user, would actually fetch from DB, etc...
  req.user = {
    id: id,
    name: 'TJ'
  }
  next()
})

router.route('/users/:user_id')
  .all(function (req, res, next) {
    // runs for all HTTP verbs first
    // think of it as route specific middleware!
    next()
  })
  .get(function (req, res, next) {
    res.json(req.user)
  })
  .put(function (req, res, next) {
    // just an example of maybe updating the user
    req.user.name = req.params.name
    // save user ... etc
    res.json(req.user)
  })
  .post(function (req, res, next) {
    next(new Error('not implemented'))
  })
  .delete(function (req, res, next) {
    next(new Error('not implemented'))
  })

Этот подход повторно использует единственный /users/:user_id путь и добавляет обработчики для различных HTTP-методов.

router.use([path], [function, ...] function)

Использует указанную функцию или функции middleware с необязательным путём подключения path, который по умолчанию равен “/”.

Этот метод аналогичен app.use(). Ниже описан простой пример и пример использования. Для получения дополнительной информации см. app.use().

Middleware похожа на трубу: запросы начинаются с первой функции middleware и проходят «вниз» по стеку middleware, обрабатывая каждый сопоставленный путь.

var express = require('express')
var app = express()
var router = express.Router()

// simple logger for this router's requests
// all requests to this router will first hit this middleware
router.use(function (req, res, next) {
  console.log('%s %s %s', req.method, req.url, req.path)
  next()
})

// this will only be invoked if the path starts with /bar from the mount point
router.use('/bar', function (req, res, next) {
  // ... maybe some additional /bar logging ...
  next()
})

// always invoked
router.use(function (req, res, next) {
  res.send('Hello World')
})

app.use('/foo', router)

app.listen(3000)

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

Порядок определения middleware с router.use() очень важен. Они вызываются последовательно, поэтому порядок определяет приоритет middleware. Например, обычно логгер является первой middleware, которую вы бы использовали, чтобы каждый запрос был записан в лог.

var logger = require('morgan')
var path = require('path')

router.use(logger())
router.use(express.static(path.join(__dirname, 'public')))
router.use(function (req, res) {
  res.send('Hello')
})

Теперь предположим, что вы хотите пропустить запись запросов для статических файлов в лог, но продолжить запись в лог маршрутов и middleware, определённых после logger(). Вы просто переместите вызов express.static() в начало, до добавления middleware логгера:

router.use(express.static(path.join(__dirname, 'public')))
router.use(logger())
router.use(function (req, res) {
  res.send('Hello')
})

Другой пример — предоставление файлов из нескольких каталогов, отдавая приоритет «./public» перед другими:

router.use(express.static(path.join(__dirname, 'public')))
router.use(express.static(path.join(__dirname, 'files')))
router.use(express.static(path.join(__dirname, 'uploads')))

Метод router.use() также поддерживает именованные параметры, чтобы ваши точки подключения для других маршрутизаторов могли извлечь выгоду из предварительной загрузки с использованием именованных параметров.

ПРИМЕЧАНИЕ: Хотя эти функции middleware добавляются через определённый маршрутизатор, время их выполнения определяется путём, к которому они прикреплены (а не маршрутизатором). Поэтому middleware, добавленная через один маршрутизатор, может быть выполнена для других маршрутизаторов, если её маршруты совпадают. Например, этот код демонстрирует два разных маршрутизатора, подключенных к одному и тому же пути:

var authRouter = express.Router()
var openRouter = express.Router()

authRouter.use(require('./authenticate').basic(usersdb))

authRouter.get('/:user_id/edit', function (req, res, next) {
  // ... Edit user UI ...
})
openRouter.get('/', function (req, res, next) {
  // ... List users ...
})
openRouter.get('/:user_id', function (req, res, next) {
  // ... View user ...
})

app.use('/users', authRouter)
app.use('/users', openRouter)

Даже если middleware аутентификации была добавлена через authRouter, она будет выполняться и для маршрутов, определённых в openRouter, поскольку оба маршрутизатора были подключены к /users. Чтобы избежать этого поведения, используйте разные пути для каждого маршрутизатора.