翻译 express-session README.md

2 年 ago
科, 雅
4 minutes

这是 Github 上 expressjs/session 的 README.md 的日文翻译。我创建了这篇文章以帮助理解，因为它是在测试容器集群配置时的重要元素。

安装

这是一个在npm注册表中可用的Node.js模块。安装可以使用npm install命令来进行。

$ npm install express-session

API (Application Programming Interface) means 应用程序编程接口 in Chinese.

var session = require('express-session')

会话（选项）

express-session接受options对象中的这些属性。

饼干

会话ID Cookie的设置对象。默认值为{路径：’/’，仅限HTTP：真，加密：假，最大年龄：null}。可以在此对象中设置的选项如下。

饼干域名

设置域(Set-Cookie)属性的值。默认情况下，没有设置域。大多数客户端只考虑在当前域中应用的Cookie。

饼干过期

在Set-Cookie属性的值中指定一个Date对象以设置过期时间。默认情况下，没有设置过期时间。大多数客户端将其视为“非永久性Cookie”，并在满足关闭Web浏览器应用程序等条件时将其删除。

（注意）如果在选项中同时设置了expires和maxAge，将使用对象中定义的最后一个选项。
（注意）请勿直接设置过期选项。请使用maxAge选项来代替。

cookie的httpOnly特性

如果设置为 true，则指定了 HttpOnly Set-Cookie 属性。此时，将设置 HttpOnly 属性。否则，将不设置。默认情况下，HttpOnly 属性已经设置。

设置这个为true后，需要注意的是客户端的JavaScript将无法看到document.cookie中的cookie。

cookie的最大有效时间

在计算Expires Set-Cookie属性时使用的数值（以毫秒为单位）进行指定。这通过获取当前服务器时间并将maxAge毫秒添加到计算Expires datetime的值来实现。默认情况下，未设置最大经过时间。

（注意）如果在选项中同时设置了 expires 和 maxAge，将使用对象中定义的最后一个选项。

饼干路径

指定传递给 Cookie 的值。默认情况下，它被设置为域名的根路径 ‘/’。

饼干的同站点

请将布尔值或字符串指定为SameSite Set-Cookie属性的值。

    • trueを指定すると、SameSite属性は厳密に同じサイト強制に対してStrictに設定されます。

 

    • falseはSameSite属性を設定しません。

 

    • ‘lax’は、Laxと同じサイト強制用にSameSite属性をLaxに設定します。

 

    • ‘none’は、明示的なクロスサイトクッキーのためにSameSite属性をNoneに設定します。

 

    ‘strict’は、SameSite属性を厳密に同じサイト強制に対してStrictに設定します。

有关不同实施级别的详细信息，请参考规范 https://tools.ietf.org/html/draft-west-first-party-cookies-07#section-4.1.1。

（注）这个属性目前尚未完全标准化，将来可能会有变动。这也意味着在许多客户端能够理解之前，可能会忽略该属性。

cookie.secure 只需要一个中文选项： cookie.安全

请指定 Secure Set-Cookie 属性的布尔值。如果为 true，则设置 Secure 属性。否则，不设置 Secure 属性。默认情况下，Secure 属性未设置。

当将其设置为true时，如果浏览器没有HTTPS连接，则符合要求的客户端在将来不会将cookie发送回服务器，请注意。

推荐使用 secure:true。但是，需要有支持https的网站。也就是说，安全的Cookie需要使用HTTPS。如果设置了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 }
}))

如果想要允许在开发测试中使用安全Cookie，可以根据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，则将无法通过HTTP显示。因此在使用此设置时要注意。这在Express中的“信任代理”设置正确配置以简化开发和生产环境设置时非常方便。

通用识别号

为了生成新的会话ID而调用的函数。它提供了一个返回用作会话ID的字符串的函数。如果您想在生成ID时使用附加在req上的值，则可将req作为第一个参数传入该函数。

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

请注意生成唯一的ID以避免会话冲突。

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

名字

从请求中读取的要设置为响应的会话ID的cookie名称。

默认值为 ‘connect.sid’。

（注）如果有多个应用程序在相同的主机名下运行（名称为localhost或127.0.0.1，并且没有使用不同的方案和端口指定不同的主机名），则需要将会话Cookie互相分离。最简单的方法是为每个应用程序设置不同的名称。

代理

在设置安全cookie时，请信任反向代理（通过“X-Forwarded-Proto”头部）。

默认值是未定义的。

    • true “X-Forwarded-Proto”ヘッダーが使用されます。

 

    • false 直接のTLS / SSL接続がある場合のみ、すべてのヘッダーが無視され、接続は安全であるとみなされます。

 

    undefined expressで “trust proxy”設定を使用してください。

重存

即使会话未在要求中更改，也会强制将会话保存到会话存储中。尽管可能依赖于您的会话存储，但如果客户端对您的服务器发起两个并发请求，并且一次请求中对会话进行的更改在没有进行更改的情况下被其他请求覆盖（此行为也取决于所使用的会话存储）。

默认值为true，但不推荐使用默认值。请检查此设置并选择适合您的用例。通常情况下，您可能会选择false。

我要如何知道这是否需要在我的会话存储中？
最好的方式是检查是否实现了touch方法。如果是的话，您可以安全地设置resave：false。如果未实现touch方法，并且会话在存储中已设置了过期时间，则可能需要resave：true。

滚动

强制在所有响应中设置会话标识符Cookie。有效期将重置为原来的最大时间，并且有效期的倒计时会被重置。

默认值为 false。

即使设置了此选项为true，如果saveUninitialized选项设置为false，则会话未初始化的响应不会设置cookie。

保存未初始化

強制保存「未初始化」的会话到会话存储中。只有当会话是新建的且没有被更改时才会进行初始化。选择false可以帮助实现登录会话、减少服务器存储使用量，或在设置Cookie之前获取必要的法律许可。选择false将帮助客户端处理没有会话的多个并发请求的竞争条件。

默认值为true，但现在不推荐使用默认值。请检查此设置并选择适合您的用例的选项。

如果在使用PassportJS時搭配使用了Session，那么Passport會在用戶驗證後將一個空的Passport對象添加到Session中以供使用。這個對象將被視為Session的變化並進行保存。這個問題已在PassportJS 0.3.0中修正。

秘密

必须选择

这是用于为会话ID Cookie签名的秘密。它可以是一个单一的秘密字符串，也可以是多个秘密字符串的数组。如果提供了一个秘密字符串的数组，那么只有第一个元素将用于会话ID Cookie的签名，而在验证请求的签名时，将考虑所有元素。

商店

会话存储实例默认为新的MemoryStore实例。

未设置

通过删除或将req.session设置为null等方式来取消设置，并控制结果。

默认值为’keep’。

    • ‘destroy’セッションは、応答が終了すると破棄（削除）されます。

 

    ‘keep’ストア内のセッションは保持されますが、要求中に行われた変更は無視され、保存されません。

会话

要存储或访问会话数据，您可以使用请求属性req.session。通常，这会以JSON的形式存储在存储中，所以嵌套对象通常没问题。例如，以下是一个用户特定的视图计数器。

// Use the session middleware
app.use(session({ secret: 'keyboard cat', cookie: { maxAge: 60000 }}))

// Access the session as req.session
app.get('/', function(req, res, next) {
  var sess = req.session
  if (sess.views) {
    sess.views++
    res.setHeader('Content-Type', 'text/html')
    res.write('<p>views: ' + sess.views + '</p>')
    res.write('<p>expires in: ' + (sess.cookie.maxAge / 1000) + 's</p>')
    res.end()
  } else {
    sess.views = 1
    res.end('welcome to the session demo. refresh!')
  }
})

会话.再生(callback)

要重新生成会话，只需调用方法。完成后，将使用req.session初始化新的SID和Session实例，并调用回调。

req.session.regenerate(function(err) {
  // will have a new session here
})

销毁当前会话 (Session.destroy(callback))

将会销毁会话并取消 req.session 属性的设置。完成后将会调用回调函数。

req.session.destroy(function(err) {
  // cannot access session here
})

会话重新加载(callback)

从会话存储中重新加载会话数据，并重新设置req.session对象。完成后，将调用回调函数。

req.session.reload(function(err) {
  // session updated
})

保存会话 (Session.save) ，执行回调函数 (callback)

将会话保存到会话存储器中，并将会话存储器中的内容替换为内存中的内容（但是，会话存储器可能会执行其他操作。有关准确的操作，请参考会话存储器的文档）。

如果会话数据已更改，那么此方法将自动在HTTP响应的末尾被调用（但此行为可以通过中间件构造函数的多个选项进行更改）。因此，通常情况下不需要调用此方法。

调用这个方法可能会很方便。比如，对于长寿命请求或者WebSocket等情况。

req.session.save(function(err) {
  // session saved
})

触摸会话()

更新.maxAge属性。通常情况下，会话中间件负责此操作，不需要手动调用。

请请求会话的 ID。

每个会话都有一个独有的ID与之关联。这个属性是req.sessionID的别名，无法更改。它被添加以使得可以从会话对象中访问会话ID。

req.session.cookie 请求的会话 cookie

每个 session 都带有独特的 Cookie 对象，这样可以根据访问者更改 session Cookie。例如，将 req.session.cookie.expires 设置为 false，可以使 cookie 仅在用户代理之间保留。

饼干最长有效期

或者，req.session.cookie.maxAge以毫秒为单位返回剩余的时间。您也可以重新分配新值并适当调整expires属性。以下是本质上相等的。

var hour = 3600000
req.session.cookie.expires = new Date(Date.now() + hour)
req.session.cookie.maxAge = hour

例如，假设maxAge的值被设置为60000（1分钟），当经过30秒后，直到当前请求完成之前，将返回30000。当调用req.session.touch()时，将重置req.session.maxAge的值。

req.session.cookie.maxAge // => 30000

请求的会话ID。

要获取已加载会话的ID，需要访问请求属性req.sessionID。这是一个只读的值，当会话被加载/创建时被设置。

会话存储的实现

所有的会话存储都必须实现EventEmitter并实现特定的方法。以下是必需的、推荐的和可选的方法列表。

    • Required methods は、このモジュールが常にストアで呼び出すメソッドです。

 

    • Recommended methods は、利用可能であれば、このモジュールが店舗で呼び出す方法です。

 

    Optional methods は、このモジュールがまったく呼び出さないメソッドですが、ユーザーに均一なストアを提示するのに役立ちます。

实现示例中会展示connect-redis仓库。

store.all(callback) -> 商店中的所有(callback)

随意

这个选项的方法用于作为一个数组获取会话存储中的所有会话。回调函数应当被调用为回调函数（错误，会话）。

store.clear(callback) 可以被简洁地翻译为 “清除存储”，并且可以在回调函数中完成。

随意

此选项的方法用于从会话存储中删除所有会话。回调函数应在存储被清除时被调用为回调（错误）。

使用callback函数计算store的长度。

随意

这个选项的方法被用来获取会话存储中所有会话的数量。回调函数应该被称为回调（错误、长度）。

获取存储的内容（sid，回调函数）

必须 (bì xū)

使用此必要方法可以通过指定会话ID（sid）从存储库中获取会话。 回调应该被调用为回调（错误、会话）。

如果找到了会话参数，则必须是会话。否则，如果找不到会话（或没有错误），则为null或未定义。如果error.code === ‘ENOENT’的回调（null，null）的操作方式，则会创建一个特殊情况。

在存储中设置sid、session，并执行回调函数（callback）。

必须

这个必要方法用于通过指定会话ID（sid）和会话（session）对象将会话UPSERT到会话存储中。一旦会话被设置到会话存储中，回调将作为回调（错误）被调用。（UPSERT操作是如果对象不存在则添加，存在则更新。）

储存.触摸(sid, 会话, 回调)

建议

通过指定会话ID（sid）和会话（session）对象，该推荐方法用于让给定的会话“触摸”。“触摸”后，应该将回调作为错误回调调用。

这主要是用于当会话商店自动删除空闲会话时，通过使用该方法来通知商店指定的会话仍处于活动状态，并潜在地重置空闲计时器。

可互換的会话存储

请提交一个请求 (PR)，以添加与该模块兼容的会话存储实现。

★ Aerospike会话存储 使用Aerospike的会话存储。

★ cassandra-store 是一个基于 Apache Cassandra 的会话存储。

★ 集群存储是一个用于在进程内或嵌入式存储中使用的包装器，例如SQLite（通过knex）、leveldb、文件或内存，与节点集群一起使用（适用于树莓派2和其他多核嵌入式设备）。

★ connect-azuretables — 一个基于Azure表存储的会话存储库。

连接云安系统存储 – 基于IBM Cloudant的会话存储。

★ connect-couchbase 是一个基于Couchbase的会话存储。

★ 连接数据缓存：基于IBM Bluemix数据缓存的会话存储。

★ connect-db2 是一个使用 ibm_db 模块构建的基于 IBM DB2 的会话存储库。

• 通过 DynamoDB 实现的会话存储模块 connect-dynamodb。

★ 连接-loki 一个基于Loki.js的会话存储。

★ connect-ml 是基于 MarkLogic Server 的会话存储。

★ connect-mssql 是一个基于 SQL Server 的会话存储插件。

★ MonetDB为基础的会话存储。

★ connect-mongo 是一个基于 MongoDB 的会话存储库。

★ connect-mongodb-session 是由 MongoDB 构建和维护的基于轻量级 MongoDB 的会话存储。

★ connect-pg-simple 一个基于PostgreSQL的会话存储器。

★ 连接-Redis 是一个基于 Redis 的会话存储。

★ 连接 – 基于memcached的会话存储。

将memjs作为memcached客户端使用的基于memcached的会话存储连接程序。

连接-会话-块 A session store使用Knex.js，它是PostgreSQL、MySQL、MariaDB、SQLite3和Oracle的SQL查询构建器。

★ connect-session-sequelize 是一个使用 Sequelize.js 的会话存储，它是一个用于 PostgreSQL、MySQL、SQLite 和 MSSQL 的 Node.js/io.js ORM。

★ 使用 node-mysql 模块通过原生的 MySQL 进行存储的会话存储。

★ 使用 node-oracledb 模块通过本地 Oracle 数据库的会话存储。

★ express-sessions: 一个同时支持MongoDB和Redis的会话存储。

★ connect-sqlite3是一个基于TJ的connect-redis库建立的SQLite3会话存储模块。

★ documentdb-session 是用于Microsoft Azure的DocumentDB NoSQL数据库服务的会话存储。

★ 使用 NeDB 作为基础的会话存储。

★ express-session-cache-manager 是一个实现了 cache-manager 接口的存储库，支持多种存储类型。

★ express-session-level 是一个基于 LevelDB 的会话存储库。

★ 表达-etcd 一个基于 etcd 的会话存储。

★ fortune-session是一个基于Fortune.js的会话存储库。支持Fortune支持的所有后端（MongoDB，Redis，Postgres，NeDB）。

★ 使用Hazelcast节点客户端构建的基于Hazelcast的会话存储器。

★ LevelDB-based session store
使用LevelDB作为基础的会话存储

★ medea-session-store 一个基于Medea的会话存储。

★ mssql-session-store 基于 SQL Server 的会话存储。

★ nedb-session-store 是一个可选的基于 NeDB 的（可以是内存中的或者文件持久化的）会话存储工具。

★ sequelstore-connect 是使用 Sequelize.js 的会话存储。

★ session-file-store 是基于文件系统的会话存储。

★ session-rethinkdb 基于 RethinkDB 的会话存储。

可以看下面的例子。

使用`express-session`来存储用户页面浏览的简单示例。

var express = require('express')
var parseurl = require('parseurl')
var session = require('express-session')

var app = express()

app.use(session({
  secret: 'keyboard cat',
  resave: false,
  saveUninitialized: true
}))

app.use(function (req, res, next) {
  var views = req.session.views

  if (!views) {
    views = req.session.views = {}
  }

  // get the url pathname
  var pathname = parseurl(req).pathname

  // count the views
  views[pathname] = (views[pathname] || 0) + 1

  next()
})

app.get('/foo', function (req, res, next) {
  res.send('you viewed this page ' + req.session.views['/foo'] + ' times')
})

app.get('/bar', function (req, res, next) {
  res.send('you viewed this page ' + req.session.views['/bar'] + ' times')
})

许可证

麻省理工学院

bannerAds