![NPM Version][npm-version-image] ![NPM Downloads][npm-downloads-image] ![Build Status][ci-image] ![Test Coverage][coveralls-image]
Промежуточное ПО для разбора тела запроса в Node.js.
Разбирает входящие тела запросов в промежуточном ПО перед вашими обработчиками, доступными под свойством req.body
.
Примечание: так как форма req.body
основана на вводе, контролируемом пользователем, все свойства и значения в этом объекте ненадежны и должны быть проверены перед доверием. Например, req.body.foo.toString()
может завершиться неудачей по нескольким причинам, например, свойство foo
может отсутствовать или не быть строкой, а toString
может не быть функцией, а строкой или другим вводом пользователя.
Узнайте о строении HTTP-транзакции в Node.js.
Этот модуль не обрабатывает multipart тела из-за их сложной и обычно большой природы. Для multipart тел вас могут заинтересовать следующие модули:
Этот модуль предоставляет следующие парсеры:
Другие парсеры тела, которые могут вас заинтересовать:
Установка
$ npm install body-parser
API
var bodyParser = require('body-parser')
Объект bodyParser
предоставляет различные фабрики для создания промежуточного ПО. Все промежуточные ПО будут заполнять свойство req.body
разобранным телом, когда заголовок запроса Content-Type
соответствует опции type
, или пустым объектом ({}
), если не было тела для разбора, Content-Type
не был совпаден или произошла ошибка.
Различные ошибки, возвращаемые этим модулем, описаны в разделе ошибок.
bodyParser.json([options])
Возвращает промежуточное ПО, которое разбирает только json
и только смотрит на запросы, где заголовок Content-Type
соответствует опции type
. Этот парсер принимает любое Unicode кодирование тела и поддерживает автоматическое разжатие gzip
и deflate
кодировок.
Новый объект body
, содержащий разобранные данные, заполняется в объекте request
после промежуточного ПО (т.е. req.body
).
Опции
Функция json
принимает необязательный объект options
, который может содержать любые из следующих ключей:
inflate
Когда установлено в true
, сжатые (сжатые) тела будут разжаты; когда false
, сжатые тела отклоняются. По умолчанию true
.
limit
Управляет максимальным размером тела запроса. Если это число, то значение указывает количество байтов; если это строка, значение передается в библиотеку bytes для разбора. По умолчанию '100kb'
.
reviver
Опция reviver
передается напрямую в JSON.parse
в качестве второго аргумента. Вы можете найти больше информации об этом аргументе в документации MDN о JSON.parse.
strict
Когда установлено в true
, будет принимать только массивы и объекты; когда false
, будет принимать все, что принимает JSON.parse
. По умолчанию true
.
type
Опция type
используется для определения, какой тип медиа будет разбирать промежуточное ПО. Эта опция может быть строкой, массивом строк или функцией. Если не функция, опция type
передается напрямую в библиотеку type-is и может быть именем расширения (например, json
), MIME-типом (например, application/json
) или MIME-типом с подстановочным знаком (например, */*
или */json
). Если функция, опция type
вызывается как fn(req)
и запрос разбирается, если он возвращает истинное значение. По умолчанию application/json
.
verify
Опция verify
, если предоставлена, вызывается как verify(req, res, buf, encoding)
, где buf
- это Buffer
необработанного тела запроса, а encoding
- это кодировка запроса. Разбор может быть прерван выбросом ошибки.
bodyParser.raw([options])
Возвращает промежуточное ПО, которое разбирает все тела как Buffer
и только смотрит на запросы, где заголовок Content-Type
соответствует опции type
. Этот парсер поддерживает автоматическое разжатие gzip
и deflate
кодировок.
Новый объект body
, содержащий разобранные данные, заполняется в объекте request
после промежуточного ПО (т.е. req.body
). Это будет объект Buffer
тела.
Опции
Функция raw
принимает необязательный объект options
, который может содержать любые из следующих ключей:
inflate
Когда установлено в true
, сжатые (сжатые) тела будут разжаты; когда false
, сжатые тела отклоняются. По умолчанию true
.
limit
Управляет максимальным размером тела запроса. Если это число, то значение указывает количество байтов; если это строка, значение передается в библиотеку bytes для разбора. По умолчанию '100kb'
.
type
Опция type
используется для определения, какой тип медиа будет разбирать промежуточное ПО. Эта опция может быть строкой, массивом строк или функцией. Если не функция, опция type
передается напрямую в библиотеку type-is и может быть именем расширения (например, bin
), MIME-типом (например, application/octet-stream
) или MIME-типом с подстановочным знаком (например, */*
или application/*
). Если функция, опция type
вызывается как fn(req)
и запрос разбирается, если он возвращает истинное значение. По умолчанию application/octet-stream
.
verify
Опция verify
, если предоставлена, вызывается как verify(req, res, buf, encoding)
, где buf
- это Buffer
необработанного тела запроса, а encoding
- это кодировка запроса. Разбор может быть прерван выбросом ошибки.
bodyParser.text([options])
Возвращает промежуточное ПО, которое разбирает все тела как строку и только смотрит на запросы, где заголовок Content-Type
соответствует опции type
. Этот парсер поддерживает автоматическое разжатие gzip
и deflate
кодировок.
Новая строка body
, содержащая разобранные данные, заполняется в объекте request
после промежуточного ПО (т.е. req.body
). Это будет строка тела.
Опции
Функция text
принимает необязательный объект options
, который может содержать любые из следующих ключей:
defaultCharset
Укажите кодировку по умолчанию для текстового содержимого, если кодировка не указана в заголовке Content-Type
запроса. По умолчанию utf-8
.
inflate
Когда установлено в true
, сжатые (сжатые) тела будут разжаты; когда false
, сжатые тела отклоняются. По умолчанию true
.
limit
Управляет максимальным размером тела запроса. Если это число, то значение указывает количество байтов; если это строка, значение передается в библиотеку bytes для разбора. По умолчанию '100kb'
.
type
Опция type
используется для определения, какой тип медиа будет разбирать промежуточное ПО. Эта опция может быть строкой, массивом строк или функцией. Если не функция, опция type
передается напрямую в библиотеку type-is и может быть именем расширения (например, txt
), MIME-типом (например, text/plain
) или MIME-типом с подстановочным знаком (например, */*
или text/*
). Если функция, опция type
вызывается как fn(req)
и запрос разбирается, если он возвращает истинное значение. По умолчанию text/plain
.
verify
Опция verify
, если предоставлена, вызывается как verify(req, res, buf, encoding)
, где buf
- это Buffer
необработанного тела запроса, а encoding
- это кодировка запроса. Разбор может быть прерван выбросом ошибки.
bodyParser.urlencoded([options])
Возвращает промежуточное ПО, которое разбирает только urlencoded
тела и только смотрит на запросы, где заголовок Content-Type
соответствует опции type
. Этот парсер принимает только кодировку тела UTF-8 и поддерживает автоматическое разжатие gzip
и deflate
кодировок.
Новый объект body
, содержащий разобранные данные, заполняется в объекте request
после промежуточного ПО (т.е. req.body
). Этот объект будет содержать пары ключ-значение, где значение может быть строкой или массивом (когда extended
установлено в false
), или любым типом (когда extended
установлено в true
).
Опции
Функция urlencoded
принимает необязательный объект options
, который может содержать любые из следующих ключей:
extended
Опция extended
позволяет выбирать между разбором URL-кодированных данных с помощью библиотеки querystring
(когда false
) или библиотеки qs
(когда true
). "Расширенный" синтаксис позволяет кодировать богатые объекты и массивы в URL-кодированный формат, обеспечивая JSON-подобный опыт с URL-кодированным. Для получения дополнительной информации, пожалуйста, см. библиотеку qs.
По умолчанию true
, но использование значения по умолчанию устарело. Пожалуйста, исследуйте разницу между qs
и querystring
и выберите соответствующую настройку.
inflate
Когда установлено в true
, сжатые (сжатые) тела будут разжаты; когда false
, сжатые тела отклоняются. По умолчанию true
.
limit
Управляет максимальным размером тела запроса. Если это число, то значение указывает количество байтов; если это строка, значение передается в библиотеку bytes для разбора. По умолчанию '100kb'
.
parameterLimit
Опция parameterLimit
управляет максимальным количеством параметров, которые разрешены в URL-кодированных данных. Если запрос содержит больше параметров, чем это значение, клиенту будет возвращен код 413. По умолчанию 1000
.
type
Опция type
используется для определения, какой тип медиа будет разбирать промежуточное ПО. Эта опция может быть строкой, массивом строк или функцией. Если не функция, опция type
передается напрямую в библиотеку type-is и может быть именем расширения (например, urlencoded
), MIME-типом (например, application/x-www-form-urlencoded
) или MIME-типом с подстановочным знаком (например, /
или */x-www-form-urlencoded
). Если функция, опция type
вызывается как fn(req)
и запрос разбирается, если он возвращает истинное значение. По умолчанию application/x-www-form-urlencoded
.
verify
Опция verify
, если предоставлена, вызывается как verify(req, res, buf, encoding)
, где buf
- это Buffer
необработанного тела запроса, а encoding
- это кодировка запроса. Разбор может быть прерван выбросом ошибки.
Ошибки
Промежуточные ПО, предоставляемые этим модулем, создают ошибки с использованием модуля http-errors. Ошибки обычно имеют свойство status
/statusCode
, содержащее предложенный HTTP-код ответа, свойство expose
для определения, должно ли свойство message
отображаться клиенту, свойство type
для определения типа ошибки без сопоставления с message
, и свойство body
, содержащее прочитанное тело, если доступно.
Ниже приведены распространенные ошибки, создаваемые этим модулем, хотя любая ошибка может возникнуть по разным причинам.
content encoding unsupported
Эта ошибка возникает, когда запрос имел заголовок Content-Encoding
, содержащий кодировку, но опция "inflation" была установлена в false
. Свойство status
установлено в 415
, свойство type
установлено в 'encoding.unsupported'
, и свойство charset
будет установлено в неподдерживаемую кодировку.
entity parse failed
Эта ошибка возникает, когда запрос содержал сущность, которую не удалось разобрать промежуточному ПО. Свойство status
установлено в 400
, свойство type
установлено в 'entity.parse.failed'
, и свойство body
установлено в значение сущности, которую не удалось разобрать.
entity verify failed
Эта ошибка возникает, когда запрос содержал сущность, которую не удалось проверить с помощью определенной опции verify
. Свойство status
установлено в 403
, свойство type
установлено в 'entity.verify.failed'
, и свойство body
установлено в значение сущности, которую не удалось проверить.
request aborted
Эта ошибка возникает, когда запрос был прерван клиентом до завершения чтения тела. Свойство received
будет установлено в количество байтов, полученных до прерывания запроса, и свойство expected
установлено в количество ожидаемых байтов. Свойство status
установлено в 400
, и свойство type
установлено в 'request.aborted'
.
request entity too large
Эта ошибка возникает, когда размер тела запроса превышает опцию "limit". Свойство limit
будет установлено в байтовый лимит, а свойство length
будет установлено в длину тела запроса. Свойство status
установлено в 413
, и свойство type
установлено в 'entity.too.large'
.
request size did not match content length
Эта ошибка возникает, когда длина запроса не совпадает с длиной из заголовка Content-Length
. Это обычно происходит, когда запрос неправильно сформирован, обычно когда заголовок Content-Length
был рассчитан на основе символов вместо байтов. Свойство status
установлено в 400
, и свойство type
установлено в 'request.size.invalid'
.
stream encoding should not be set
Эта ошибка возникает, когда что-то вызвало метод req.setEncoding
до этого промежуточного ПО. Этот модуль работает напрямую с байтами, и вы не можете вызывать req.setEncoding
, используя этот модуль. Свойство status
установлено в 500
, и свойство type
установлено в 'stream.encoding.set'
.
stream is not readable
Эта ошибка возникает, когда запрос больше не читаем, когда это промежуточное ПО пытается его прочитать. Это обычно означает, что что-то другое, кроме промежуточного ПО из этого модуля, уже прочитало тело запроса, и промежуточное ПО также было настроено на чтение того же запроса. Свойство status
установлено в 500
, и свойство type
установлено в 'stream.not.readable'
.
too many parameters
Эта ошибка возникает, когда содержимое запроса превышает настроенный parameterLimit
для парсера urlencoded
. Свойство status
установлено в 413
, и свойство type
установлено в 'parameters.too.many'
.
unsupported charset "BOGUS"
Эта ошибка возникает, когда запрос имел параметр кодировки в заголовке Content-Type
, но модуль iconv-lite
не поддерживает его ИЛИ парсер не поддерживает его. Кодировка содержится в сообщении, а также в свойстве charset
. Свойство status
установлено в 415
, свойство type
установлено в 'charset.unsupported'
, и свойство charset
установлено в неподдерживаемую кодировку.
unsupported content encoding "bogus"
Эта ошибка возникает, когда запрос имел заголовок Content-Encoding
, содержащий неподдерживаемую кодировку. Кодировка содержится в сообщении, а также в свойстве encoding
. Свойство status
установлено в 415
, свойство type
установлено в 'encoding.unsupported'
, и свойство encoding
установлено в неподдерживаемую кодировку.
Примеры
Express/Connect верхнего уровня общий
Этот пример демонстрирует добавление общего JSON и URL-кодированного парсера в качестве промежуточного ПО верхнего уровня, которое будет разбирать тела всех входящих запросов. Это самая простая настройка.
var express = require('express') var bodyParser = require('body-parser')
var app = express()
// разбор application/x-www-form-urlencoded app.use(bodyParser.urlencoded({ extended: false }))
// разбор application/json app.use(bodyParser.json())
app.use(function (req, res) { res.setHeader('Content-Type', 'text/plain') res.write('вы отправили:\n') res.end(JSON.stringify(req.body, null, 2)) })
Маршруты Express, специфичные для маршрутов
Этот пример демонстрирует добавление парсеров тела специально для маршрутов, которые в них нуждаются. В общем, это наиболее рекомендуемый способ использования body-parser с Express.
var express = require('express') var bodyParser = require('body-parser')
var app = express()
// создание парсера application/json var jsonParser = bodyParser.json()
// создание парсера application/x-www-form-urlencoded var urlencodedParser = bodyParser.urlencoded({ extended: false })
// POST /login получает URL-кодированные тела app.post('/login', urlencodedParser, function (req, res) { res.send('добро пожаловать, ' + req.body.username) })
// POST /api/users получает JSON тела app.post('/api/users', jsonParser, function (req, res) { // создание пользователя в req.body })
Изменение принимаемого типа для парсеров
Все парсеры принимают опцию type
, которая позволяет изменить Content-Type
, который будет разбирать промежуточное ПО.
var express = require('express') var bodyParser = require('body-parser')
var app = express()
// разбор различных пользовательских типов JSON как JSON app.use(bodyParser.json({ type: 'application/*+json' }))
// разбор некоторого пользовательского объекта в Buffer app.use(bodyParser.raw({ type: 'application/vnd.custom-type' }))
// разбор HTML тела в строку app.use(bodyParser.text({ type: 'text/html' }))
Лицензия