thinkjs 使用 think-session-cookie:用 Cookie 存储 Session 的完整配置与源码原理
thinkjs 使用 think-session-cookie:用 Cookie 存储 Session 的完整配置与源码原理
导读
think-session-cookie 是 ThinkJS 3.x 官方维护的 Session 存储适配器,它将全部会话数据直接序列化后写入浏览器 Cookie,服务端无需任何持久化存储,适合无状态、分布式部署场景。本文围绕 think-session-cookie/README.md 展开:先给出安装与 src/config/adapter.js 的完整配置,再逐项解析 Cookie 参数(name、maxAge、encrypt、keys 等)的真实含义,随后结合 index.js 与 think-session 的源码,讲清会话数据读写、自动续期、加密与签名机制的底层实现。读完你既能完成开箱即用的配置,也能理解 Cookie Session 与其他存储型 Session(file、redis)在实现上的本质差异。
一、安装
在项目根目录执行:
npm install think-session-cookie
该包以 think-session(^1.1.4)为 peerDependency,因此使用前需确保项目中已安装 think-session 扩展。包的入口为 index.js,导出的 CookieSession 类实现了 ThinkJS Session 适配器约定的 get / set / delete 接口,并声明了 CookieSession.onlyCookie = true 这一关键标识(见下文“源码原理”)。
二、配置:在 adapter.js 中注册 cookie 类型
ThinkJS 的 Session 功能由 think-session 扩展提供,它在 context 和 controller 上挂载 session 方法,而实际存取方式由适配器决定。要启用 Cookie Session,在项目配置文件 src/config/adapter.js 中注册即可:
const cookie = require('think-session-cookie');
exports.session = {
type: 'cookie',
common: {
cookie: {
name: 'thinkjs',
autoUpdate: false, //auto update cookie when maxAge is set
//maxAge: '',
//expires: '',
path: '/', //a string indicating the path of the cookie
//domain: '',
//secure: false,
//keys: [],
httpOnly: true,
sameSite: false,
signed: false,
overwrite: false
}
},
cookie: {
handle: cookie,
cookie: {
encrypt: false //encrypt cookie data
}
}
}
2.1 配置结构说明
type: 'cookie':声明默认使用的适配器类型,即下方cookie这一项配置;common.cookie:对所有类型(cookie、file、redis 等)生效的公共 Cookie 选项,负责定义 Cookie 的写入行为;cookie.handle:指向think-session-cookie导出的适配器类,决定 Session 数据如何序列化与还原;cookie.cookie:仅在type为cookie时生效的类型级选项,此处用于设置encrypt加密开关。
ThinkJS 的加载器会把 common 中的字段合并进每个类型项(见 think-loader/loader/config.js 的 formatAdapter 实现),因此 common 与 cookie 项中的同名配置会被合并,类型级配置优先级更高。此外,src/config/adapter.js 还可以按环境拆分为 src/config/adapter.development.js、src/config/adapter.production.js 分别覆盖。
2.2 参考:think-demo 的完整示例
仓库中的 think-demo/src/config/adapter/session.js 给出了一个同时配置 cookie / file 两种类型的真实样例,其中 Cookie Session 部分开启了加密:
module.exports = {
type: 'mysql',
common: {
cookie: {
name: 'test',
keys: ['werwer', 'werwer'],
signed: true
}
},
cookie: {
handle: cookieSession,
cookie: {
maxAge: 1009990 * 1000,
keys: ['welefen', 'suredy'],
encrypt: true
}
},
file: {
handle: fileSession,
sessionPath: path.join(think.ROOT_PATH, 'runtime/session')
}
}
可以看到:common.cookie 里设置 Cookie 名、签名 keys 与 signed,cookie.cookie 里再叠加 maxAge 与 encrypt。注意 common 的 keys 会在合并后被类型级 keys 覆盖。
三、参数速查表
结合 think-session/lib/session.js 中定义的默认值与 README 注释,各参数含义如下:
| 参数 | 默认值 | 说明 |
|---|---|---|
name |
'thinkjs' |
Cookie 名称,浏览器端可见,可改为 'sid'、'token' 等 |
maxAge |
由 session 配置决定(默认 1 天) | Cookie 有效期(毫秒),写入 Expires/Max-Age,同时作为 Session 数据的过期基准 |
expires |
空 | 指定绝对过期时间,与 maxAge 二选一 |
path |
'/' |
Cookie 生效路径,/ 表示全站生效 |
domain |
空 | Cookie 生效域名,跨子域共享时设置 |
secure |
false |
仅 HTTPS 传输时发送 |
keys |
[] |
用于签名或加密的密钥数组 |
httpOnly |
true |
禁止脚本读取,防 XSS 窃取 |
sameSite |
false |
跨站请求携带策略 |
signed |
false |
是否对 Cookie 进行 HMAC 签名防篡改 |
overwrite |
false(构造时强制为 true) |
同 Cookie 名是否覆盖写入 |
encrypt |
false |
是否对 Cookie 内的 Session 数据做 AES 加密(类型级选项) |
autoUpdate |
false |
设置 maxAge 时是否随请求自动续期 |
注意:
autoUpdate是 README 中标注的配置写法;源码层面实际依据cookieOptions.autoUpdateRate(默认0.5,见 think-session/lib/session.js)在有效期剩余比例低于该值时触发自动续期,二者是同一机制在不同配置层的体现。
四、在 Controller 中使用 Session
注册完成后,即可在控制器或上下文中通过 this.session(...) 读写:
// set session
await this.session('name', 'value');
// get session
let value = await this.session('name');
// get all session data
let data = await this.session();
// delete session data
await this.session(null);
think-demo 的 session.js 展示了同一项目内切换存储类型的用法——第三个参数传 {type: 'cookie'} 即可对单次调用指定 Cookie 存储:
// set session with cookie type
await this.session('num2', '3', {type: 'cookie'});
// get session with cookie type
let data = await this.session('num2', undefined, {type: 'cookie'});
五、源码原理:CookieSession 如何工作
5.1 整体结构
think-session-cookie 的 index.js 实现了一个约百行的 CookieSession 类,核心职责为:构造时从 Cookie 还原 Session 数据(initSessionData)、读写单条数据(get / set)、整体删除(delete),并对外暴露 CookieSession.onlyCookie = true 标识。
5.2 与 think-session 的协作方式
think-session 的 Session.getSessionInstance() 在实例化前会检查 Handle.onlyCookie:
- 为
true(Cookie Session 场景):不在 Cookie 中存放 Session ID,直接把options、ctx、cookieOptions交给CookieSession构造,所有数据随 Cookie 往返; - 为
false(file / redis 等场景):先生成一个 UUID 写入 Cookie 作为 sessionId,再以该 id 为键去后端存储读写。
这正是 Cookie Session 的本质——无服务端存储、无 Session ID,数据自包含于 Cookie,因此天然适合水平扩展,但也意味着 Cookie 体积随数据增长,且数据暴露在客户端,敏感信息必须加密。
5.3 数据序列化格式与还原
set 时(index.js)将数据封装为 JSON:
let data = JSON.stringify({
maxAge: this.maxAge,
expire: Date.now() + this.maxAge,
data: this.data
});
initSessionData 构造时(index.js)从 this.ctx.cookie(name) 读出字符串并 JSON.parse,恢复 data、maxAge、expire 三个字段,同时将 fresh 置为 false 表示已有存量数据。若 JSON 解析失败(Cookie 被篡改或损坏)则静默回退为空对象 {}。
5.4 自动续期(autoUpdate)
get 方法中实现了滑动续期逻辑(index.js):
if (this.maxAge && this.expire && !this.fresh && this.cookieOptions.autoUpdateRate) {
const rate = (this.expire - Date.now()) / this.maxAge;
if (rate < this.cookieOptions.autoUpdateRate) {
this.set();
}
}
即:当已存在的会话剩余有效期占比低于 autoUpdateRate(默认 0.5,即剩余时间不足一半)时,调用 set() 重新写入,把 expire 顺延到 Date.now() + maxAge,实现“活跃用户不掉线”。
5.5 加密(encrypt)与签名(signed)
- signed:交由 ThinkJS 底层 Cookie 处理(
cookieOptions.signed),对 Cookie 值附加 HMAC 签名,防止被篡改但不加密,内容仍可读; - encrypt:由本包自带的 keygrip.js 实现。开启后,构造器会校验
cookieOptions.keys必须是非空数组,否则抛出.keys required and must be an array when encrypt is set(对应测试见 test/index.js),并强制关闭signed、创建Keygrip实例。写入时:
if (this.keygrip) {
data = this.keygrip.encrypt(data).toString('base64');
}
即先对 JSON 做 aes-256-cbc 加密,再 Base64 编码后写入 Cookie;读取时反向 Buffer.from(data, 'base64') 后解密还原。Keygrip 支持多 keys,解密时逐个尝试(keygrip.js),便于密钥轮换:旧 key 仍可解密存量 Cookie,新 key 写入新 Cookie。
建议:Cookie 中只放低敏数据(如用户 id、昵称)时可不加密;若存放权限、余额等敏感信息,务必开启
encrypt: true并配置强随机keys。
5.6 删除会话
delete(index.js)仅在 fresh === false(确实存在存量会话)时执行:调用 ctx.cookie(name, null, cookieOptions) 清除浏览器 Cookie,并清空内部 data。测试用例(test/index.js)同时覆盖了“清除成功”与“fresh 为 true 时不动作”两种分支。
六、可验证的运行闭环
仓库测试 test/index.js 使用 Node 内置 test runner 验证了如下行为,可作为理解实现的依据:
- 构造时
encrypt开启但缺少 keys 或 keys 非数组 → 抛错; - 从 Cookie 字符串还原
{data, maxAge, expire}→fresh为false; set后get能取回原值(含加密模式);encrypt模式下写入的数据经Keygrip加密、Base64 编码,读取时还原一致;delete清除 Cookie 后get返回undefined。
本地运行测试命令(仓库 package.json 已声明):
cd packages/think-session-cookie && npm test
七、适用场景与注意事项
适用:无状态服务、多实例/分布式部署(无需共享 Session 存储)、登录态轻量、跨服务传递身份信息。
注意:
- 体积:Session 数据整体写入 Cookie,单次请求头携带,数据量大时拖慢请求、易超 Cookie 4KB 上限;
- 安全:未加密时数据明文可见,务必配合
signed或encrypt;生产环境建议secure: true强制 HTTPS; - 过期:Session 的有效期跟随 Cookie 的
maxAge,与think-session默认的 1 天maxAge(think-session/lib/session.js)保持一致,需要更长/更短可在common.cookie中调整; - 依赖:需同时安装
think-session与think-session-cookie,二者是适配器与调度核心的关系,缺一不可。
若需要存储较大数据或服务端可控失效,建议改用同仓库的 think-session-file 或 think-session-redis,配置方式与本文完全同构——仅替换 handle 与对应参数即可。