thinkjs 使用 think-session-cookie:用 Cookie 存储 Session 的完整配置与源码原理

原创2026-10-14 13:02:131,843 阅读
文章标签:后端Web框架

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 存储)、登录态轻量、跨服务传递身份信息。

注意:

  1. 体积:Session 数据整体写入 Cookie,单次请求头携带,数据量大时拖慢请求、易超 Cookie 4KB 上限;
  2. 安全:未加密时数据明文可见,务必配合 signed 或 encrypt;生产环境建议 secure: true 强制 HTTPS;
  3. 过期:Session 的有效期跟随 Cookie 的 maxAge,与 think-session 默认的 1 天 maxAge(think-session/lib/session.js)保持一致,需要更长/更短可在 common.cookie 中调整;
  4. 依赖:需同时安装 think-session 与 think-session-cookie,二者是适配器与调度核心的关系,缺一不可。

若需要存储较大数据或服务端可控失效,建议改用同仓库的 think-session-file 或 think-session-redis,配置方式与本文完全同构——仅替换 handle 与对应参数即可。

登录后查看全文
thinkjs