翻译此页面

cookie-parser middleware

v1.4.7GitHubChangelognpm

解析 Cookie 请求头，并以 Cookie 名称为键生成对象挂载至 req.cookies。 你也可传入 secret 字符串开启签名 Cookie 支持，该参数会赋值给 req.secret，供其他中间件使用。

安装

Terminal window
npm install cookie-parser

Note

cookie-parser 自身不附带 TypeScript 类型定义文件。 If you use TypeScript, also install the community-maintained types from DefinitelyTyped as a development dependency:

Terminal window
npm install --save-dev @types/cookie-parser

API

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

cookieParser(secret, options)

使用传入的 secret 与 options 创建全新的 Cookie 解析中间件函数。

  • secret：用于签名 Cookie 的字符串或数组。 该参数为可选参数，若未指定，则不会解析签名 Cookie。 若传入字符串，则将其作为密钥。 若传入数组，会按顺序使用数组内每个密钥尝试解密签名 Cookie。
  • options：作为第二个参数传入 cookie.parse 的配置对象。 更多详情请查看 cookie。
    • decode：用于解码 Cookie 值的函数

该中间件会解析请求头中的Cookie，并将 Cookie 数据挂载为req.cookies属性；若传入了secret密钥，则同时挂载为req.signedCookies属性。 这些属性是键值对，代表 Cookie 名称与对应 Cookie 值。

当配置secret密钥时，该模块会对所有签名Cookie值进行解签与校验，并将对应的键值对从req.cookies转移至req.signedCookies中。 签名 Cookie 是值以s:作为前缀的 Cookie。 签名校验失败的签名 Cookie，其值会为false，而非被篡改后的内容。

此外，该模块支持特殊的“JSON Cookie”。 这类 Cookie 的值以 j: 作为前缀。 当识别到这类值时，会将其经JSON.parse解析后的结果对外暴露。 若解析失败，则保留原始值。

cookieParser.JSONCookie(str)

将 Cookie 值解析为 JSON Cookie。 如果是 JSON Cookie，将返回解析后的 JSON 值；否则返回传入的原始值。

cookieParser.JSONCookies(cookies)

传入一个对象后，该方法会遍历对象所有键，并对每个值调用JSONCookie，用解析后的值替换原有值。 该方法返回传入的原对象。

cookieParser.signedCookie(str, secret)

将 Cookie 值解析为签名 Cookie。 若为签名 Cookie 且签名校验通过，则返回解析后的未签名值。 若该值未经过签名，则返回原始值。 若该值已签名但签名校验不通过，则返回false。

secret 参数可以为字符串或数组。 若传入字符串，则将其用作密钥。 若传入数组，则会按顺序使用数组内每一个密钥尝试对Cookie解签。

cookieParser.signedCookies(cookies, secret)

传入一个对象时，该方法会遍历所有键，并检测每个值是否为签名 Cookie。 如果是签名 Cookie 且签名校验有效，则从原对象中删除该键，并将其添加到返回的新对象中。

secret 参数可以为字符串或数组。 若传入字符串，则将其用作密钥。 若传入数组，则会按顺序使用数组内每一个密钥尝试对Cookie解签。

示例

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


var app = express();
app.use(cookieParser());


app.get('/', function (req, res) {
  // Cookies that have not been signed
  console.log('Cookies: ', req.cookies);


  // Cookies that have been signed
  console.log('Signed Cookies: ', req.signedCookies);
});


app.listen(8080);


// curl command that sends an HTTP request with two cookies
// curl http://127.0.0.1:8080 --cookie "Cho=Kim;Greet=Hello"

License

MIT