「翻译」express-session 中间件_greenlihui的专栏文章_微信文章

前言：最近在使用 express-session 中间件，查看使用的时候有些参数不是很清楚就花了一点时间把文档翻译了一下。

其中常用设置中令人迷糊的是 resave 和 saveUnintialized 属性，关于这两个属性，引用来自 CNODE 社区更通熟易懂的解释：

resave : 是指每次请求都重新设置 session cookie，假设你的 cookie 是 10 分钟过期，每次请求都会再设置 10 分钟。
saveUninitialized : 是指无论有没有 session cookie ，每次请求都设置个 session cookie ，默认给个标示为 connect.sid。

以下为正文 ：

Installation

这是一个通过 npm registry 可用的 Node.js 模块。使用以下 npm install 命令来完成安装。

$ npm install express-session
复制代码

API

var session = require('express-session');
复制代码

sessions(options)

使用给定选项创建一个 session 中间件。

注意：只有 session ID 是保存在 cookie 中，Session 数据本身并不是。Session 数据是存在服务端。

注意：从版本 1.5.0 起，本模块不再需要 cookie-parser 中间件来运行。本模块现在直接在 req/res 上读写 cookies。当本模块和 cookie-parser 的 secret 不一致时，使用 cookie-parser 可能会导致问题。

警告：默认的服务端 session 存储，MemoryStore，特意没有为生产环境而设计。在大多数情况下，它可能会导致内存泄漏，不会扩展超过单个进程，本是用于调试和开发。

对于存储列表，请查看兼容的 session 存储

Options

express-session 在 options 对象中接收以下参数

cookie

session ID cookie 的设置对象。默认值为 { path: '/', httpOnly: true, secure: false, maxAge: null } .

下列参数可选设置放入 cookie 对象。

cookie.domain

为 Set-Cookie 属性指定 domain。默认情况下，没有设置 domain，并且大多数客户端会将 cookie 视为仅应用于当前 domain。

cookie.expires

为 Set-Cookie 属性中的 Expires 指定 Date 对象。默认情况下，没有设置 expires，大多数客户端会将视这个为 "非持久化 cookie" 并且在像退出浏览器应用的场景下删除该 cookie。

注意：如果 options 对象中同时设置了 expires 和 maxAge，那么将被用到的是在对象中最后一个被定义的属性。

注意：expires 选项不应该被直接设置；而应该只使用 maxAge 选项。

cookie.httpOnly

为 Set-Cookie 属性中的 HttpOnly 指定 boolean 值。当为真值，HttpOnly 属性被设置，否则不被设置。默认情况下，HttpOnly 属性是被设置的。

注意：设置该值为 true 的时候要小心，因为服从协议的客户端不会允许 JavaScript 在 document.cookie 中查看 cookie。

cookie.maxAge

指定当计算 Set-Cookie 属性中的 Expires 时使用的 number （毫秒）值。这是通过获取当前服务器时间并将 maxAge 毫秒数加入其中计算 Expires 日期时间来完成的。默认情况下没有设置 maxAge。

注意：如果 options 对象中同时设置了 expires 和 maxAge，那么将被用到的是在对象中最后一个被定义的属性。

cookie.path

为 Set-Cookie 属性指定 Path 值。默认情况下该值被设为 '/' ，也就是 domain 下的根路径。

cookie.sameSite

为 Set-Cookie 属性中的 SameSite 指定 boolean 或者 string 值。其中，

true 会将 SameSite 属性设为 Strict 以实现严格的相同站点强制。
false 不会 SameSite 属性。
'lax' 会将 SameSite 属性设置为 Lax 以实现宽松的相同站点强制。
'strict' 会将 SameSite 属性设置为 Strict 以实现严格的相同站点强制。

关于不同的强制级别的更多信息可以在细则中找到 tools.ietf.org/html/draft-…

注意：这是一个还未被完全标准化的属性并且将来可能发生变化。这意味着许多客户端可能忽略这条属性直到它们完全理解它为止。

cookie.secure

为 Set-Cookie 属性中的 Secure 指定 boolean 值。当为真时，Secure 属性被设置否则没有设置。默认情况下 Secure 属性没有被设置。

注意：当设置该值为 true 的时候请小心，因为如果浏览器没有建立 HTTPS 连接服从协议的客户端将不会发送 cookie 返回给服务端。

请注意 secure: true 是推荐选项。然而，它需要启用 HTTPS 的网站，也就是 HTTPS 是 secure cookies 所必须的。如果 secure 被设置而你通过 HTTP 访问你的站点，cookie 将不会被设置。如果你在代理后使用 node.js 并且设置 secure: true ，你需要在 express 中设置 "trust proxy"：

var app = express()
app.set('trust proxy', 1) // trust first proxy
app.use(session({
  secret: 'keyboard cat',
  resave: false,
  saveUninitialized: true,
  cookie: { secure: true }
}))
复制代码

为了在生产环境中使用 secure cookies，同时允许在开发环境中测试，下列是在 express 中基于 NODE_ENV 启用此设置的示例：

var app = express()
var sess = {
  secret: 'keyboard cat',
  cookie: {}
}
 
if (app.get('env') === 'production') {
  app.set('trust proxy', 1) // trust first proxy
  sess.cookie.secure = true // serve secure cookies
}
 
app.use(session(sess))
复制代码

cookie.secure 选项也可以被设置成特殊值 "auto" 来让这个设置自动和确定的连接的安全性相匹配。如果站点可以同时用做 HTTP 和 HTTPS 请小心使用这个设置，因为一旦 cookie 的 HTTPS 属性被设置，cookie 不会再对 HTTP 可见。当 Express 的 "trust proxy" 被正确设置来简化开发和生产配置的时候，这非常有用。

genid

调用来生成一个新的 session ID 的函数。提供一个返回 string 类型并将被用来作为 session ID 的函数。当生成 ID 的时候如果你想用一些附加到 req 的值，该函数已给定 req 作为第一个参数。

默认值是一个使用 uid-safe 库来生成 ID 的函数。

注意：请小心生成唯一的 ID 以便你的 sessions 不会产生冲突。

app.use(session({
  genid: function(req) {
    return genuuid() // use UUIDs for session IDs
  },
  secret: 'keyboard cat'
}))
复制代码

name

设置在 response 中（和从 request 中读取）的 session ID 的 cookie 的 name。

默认值为 "connect.sid" 。

注意：如果你有多个运行在相同 hostname（只是名字，也就是 localhost 或者 127.0.0.1；不同的协议(scheme) 和端口(port) 不命名不同的主机名）上的应用，那么你需要将 session cookie 彼此分开。最简单的方法是每个应用设置不同的 name。

proxy

当设置 secure cookies 的时候相信反向代理（通过 "X-Forwarded-Proto" 头）。

默认值为 undefined 。

true 表示 "X-Forwarded-Proto" 头将会被使用。
false 表示只有存在直接的 TLS/SSL 连接时才会忽略所有头并认为连接是安全的。
undefined 表示从 express 中使用 "trust proxy"。

resave

即使 session 在请求期间从未被修改过也强制 session 保存回 session 存储（store）。根据你的存储这可能是必须的，但是这也可能创造竞争条件当客户端发送两个并行请求到你的服务端并且其中一个请求 A 对 session 作出的更改可能会在另一个请求 B 结束时被覆盖即使请求 B 没有做任何更改（这个行为取决于你用的 session 存储）。

默认值为 true，但是不推荐使用默认值，因为默认值将来会被更改。请研究此项设置并选择适合你的用例的选项。一般来讲，你会想选择 false。

该如何知道该设置对我的 session 存储来讲是不是必须的呢？最好的方法是检查你的存储看它是否实现了 touch 方法。如果它实现了，那你可以安全地设置 resave 为 false。如果它没有实现 touch 方法而且你的 store 在存储的 sessions 中设定的 expiration 日期，那么你可能需要设置 resave: false 。

rolling

强制在每次响应的时候设置一个 session 标志符 cookie。expiration 重新被设置为初始的 maxAge，重置 expiration 倒计时。

默认值为 false。

注意：当该选项被设置为 true 但是 saveUninitialized 选项被设置为 false，则不会在具有未初始化的 session 响应中设置 cookie。

「翻译」express-session 中间件

正文