Express

express()

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

const express = require('express')
const app = express()

Методы

express.json([options])

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

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

После выполнения промежуточного ПО на объекте request заполняется новый объект body с обработанными данными (то есть req.body) или undefined, если тело запроса отсутствовало, заголовок Content-Type не соответствовал условию или произошла ошибка.

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

express.raw([options])

Это встроенная функция промежуточного ПО в Express. Она преобразует данные входящих запросов в Buffer и основана на body-parser.

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

После выполнения промежуточного ПО на объекте request заполняется новый body Buffer с обработанными данными (то есть req.body) или undefined, если тело запроса отсутствовало, заголовок Content-Type не соответствовал условию или произошла ошибка.

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

express.Router([options])

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

const router = express.Router([options])

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

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

Дополнительные сведения см. в разделе Маршрутизатор.

express.static(root, [options])

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

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

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

Дополнительные сведения см. в разделах Обслуживание статических файлов в Express и Использование промежуточного ПО — встроенное промежуточное ПО.

dotfiles

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

• «allow» — файлы dotfiles обрабатываются без особых правил.
• «deny» — запрос к файлу dotfile отклоняется; отправляется ответ 403, после чего вызывается next().
• «ignore» — файл dotfile считается несуществующим; отправляется ответ 404, после чего вызывается next().

fallthrough

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

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

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

setHeaders

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

Сигнатура функции:

fn(res, path, stat)

Аргументы:

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

Пример express.static

Ниже приведён пример использования промежуточного ПО express.static с подробным объектом параметров:

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

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

express.text([options])

Это встроенная функция промежуточного ПО в Express. Она преобразует данные входящих запросов в строку и основана на body-parser.

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

После выполнения промежуточного ПО на объекте request заполняется новая строка body с обработанными данными (то есть req.body) или undefined, если тело запроса отсутствовало, заголовок Content-Type не соответствовал условию или произошла ошибка.

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

express.urlencoded([options])

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

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

После выполнения промежуточного ПО на объекте request заполняется новый объект body с обработанными данными (то есть req.body) или undefined, если тело запроса отсутствовало, заголовок Content-Type не соответствовал условию или произошла ошибка. Этот объект содержит пары «ключ — значение», где значением может быть строка или массив (если extended — false) либо значение любого типа (если extended — true).

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

Приложение

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

const express = require('express')
const app = express()

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

app.listen(3000)

Объект app предоставляет методы для

• маршрутизации HTTP-запросов; см., например, app.METHOD и app.param;
• настройки промежуточного ПО; см. 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, действующих только в течение обработки запроса.

Локальные переменные доступны в шаблонах, отрендеренных в приложении. Это удобно для предоставления шаблонам вспомогательных функций и данных уровня приложения. Локальные переменные доступны в промежуточном ПО через 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 содержит один или несколько шаблонов путей, по которым подключено дочернее приложение.

const express = require('express')

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

admin.get('/', (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 возвращает список шаблонов, по которым оно подключено, как показано в следующем примере.

const admin = express()

admin.get('/', (req, res) => {
  console.log(admin.mountpath) // [ '/adm{*splat}n', '/manager' ]
  res.send('Admin Homepage')
})

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

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

app.router

Встроенный экземпляр маршрутизатора приложения. Он создаётся при первом обращении к нему.

const express = require('express')
const app = express()
const router = app.router

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

app.listen(3000)

К router можно добавлять промежуточное ПО и маршруты для HTTP-методов, как и к приложению.

Дополнительные сведения см. в разделе Маршрутизатор.

События

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

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

const admin = express()

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

admin.get('/', (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', (req, res, next) => {
  console.log('Accessing the secret section ...')
  next() // pass control to the next handler
})

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

app.all('{*splat}', requireAuthentication, loadUser)

Или эквивалентный вариант:

app.all('{*splat}', requireAuthentication)
app.all('{*splat}', loadUser)

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

app.all('/api/{*splat}', requireAuthentication)

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

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

Аргументы