# @companieshouse/node-session-handler 中文文档

规范地址：https://npmcn.com/package/%40companieshouse/node-session-handler/

版本：5\.2\.23
npm 元数据更新时间：2026-11-02T13:47:08.373Z
中文译文更新时间：2026-11-10T13:26:14.003Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40companieshouse/node-session-handler
原文对照：https://npmcn.com/package/%40companieshouse/node-session-handler/?lang=original
项目主页：https://github.com/companieshouse/node-session-handler#readme
源码仓库：https://github.com/companieshouse/node-session-handler

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：67.6 kB，66 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：5 个
- 首次发布：2020-09-25T16:35:27.021Z
- 最新版本发布：2026-11-02T13:47:08.154Z
- 近 30 天下载量：2432（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 16 个）

## 中文简介

公司大厦节点会务经理

## 安装

```sh
npm install @companieshouse/node-session-handler
```

也可以使用：`pnpm add @companieshouse/node-session-handler`、`yarn add @companieshouse/node-session-handler`、`bun add @companieshouse/node-session-handler`

## README

# 节点会议处理器

模块提供了处理公司众议院会议的方式.

模块提供以下文物:

-   `Session` 反映会议结构,包括 " 单一标志 " 的要素
-   `SessionStore` 负责从 / 到数据库读取和写入会话数据, 负责数据编码/ 解码
-   `SessionMiddleware` 以请求 cookie 为基础, 提供简单使用 express.js 中间软件读取会话

## 兼容的节点.js 版本

这个软件包已经升级,与Node v24兼容. 目前,它与v20和v18是相容的后向兼容,但相容性主要是v24的要求,因为所有的CH节点服务都在被升级到v24的过程中.

## 先决条件

模块要求 `request.cookies` 以 cookie 名称键入对象的地图。 通过使用 [饼干派瑟](https://www.npmjs.com/package/cookie-parser) 模块.

短期 `npm install cookie-parser` 命令以安装依赖性,并在应用程序中添加以下 snipt 来应用 cookie 剖析中间软件 :

```$typescript
import * as cookieParser from 'cookie-parser'
...
app.use(cookieParser())
```

注意: Cookie 解析必须在请求传递到会话中间软件之前进行.

## 怎样用

要将本模块作为依赖性,请将以下部分添加到 `package.json`数字 :

```$json
"@companieshouse/node-session-handler": "~4.1.0"
```

### 会议

会话课是围绕原始会话的包装 `data: ISession` (签字后从账户取出).

为了保持 `ISession` 类型一致,我们添加了一个额外的字段,叫做 `extra_data` (单位:千美元)`SessionKey.ExtraData`在会话中存储应用程序可能需要的任何数据,使会话本身可以扩展.

该类提供这些方法:

-   `get<T = ISessionValue>(key: SessionKey): T | undefined` - 允许检索在 `SessionKey` 代表所有可能类型但无法从会话中取回的enum
-   `getExtraData<T>(key: string): T | undefined` - 允许检索应用程序所覆盖的会话数据
-   `setExtraData<T>(key: string, val: T): void` - 允许修改应用程序使用的会话数据,替换现有值(如果有的话)
-   `deleteExtraData(key: string): boolean` - 从应用程序所覆盖的会话数据中删除密钥(如果存在)
-   `verify = (): void` - 确保会话有效,即包含正确的字段,而且不会过期

### 会话

会话存储提供了加载方式 `SessionStore.load`存储 `SessionStore.store` 删除 `SessionStore.delete` 来自数据库的会话,而不担心数据编码或解码.

所有上述方法都以 `Cookie` 类,具有会话ID和签名的组合。 使用这种参数类型有助于确保只为已核实的会话标识符进行数据库操作.

### 会话中软件

会话中间软件为express.js应用程序提供了方便的集成点. 中间软件有:

1.  从请求 HTTP 信头读取 cookie 值
2.  如果 cookie 有的话, 验证 cookie 签名
3.  如果存在的话, 使用已校验的 cookie 从存储中装入会话
4.  请求范围内已核实的会话
5.  如果会话数据改变, 则在请求结束时存储会话

Express.js希望引入会话处理的应用程序应当以下列方式注册中间软件: 1

```$javascript

const sessionStore = new SessionStore(new Redis(`redis://${process.env.CACHE_SERVER}`))
const middleware = SessionMiddleware({
    cookieName: process.env.COOKIE_NAME,
    cookieDomain: process.env.COOKIE_DOMAIN,
    cookieSecureFlag: process.env.COOKIE_SECURE_ONLY,
    cookieTimeToLiveInSeconds: process.env.DEFAULT_SESSION_EXPIRATION,
    cookieSecret: process.env.COOKIE_SECRET
}, sessionStore)

app.use(middleware)
```

这样的程序就可以通过 `request.session` 只要我们.. `__SID` cookie 设定为校正值 .

还有一个选项是,在没有登录信息的情况下无法认证会话。 在这种情况下,只要请求中找不到有效的会话,中间软件就会产生空会话.

用于支持未认证的会话 `true` 作为中件厂函数的最后一个参数,例如:. `SessionMiddleware(config, sessionStore, true)`。 。 。 .

### 保证会议Cookie 中枢软件

方便快捷的中间软件功能,确保请求包含 如果不是会话 ID Cookie 并强制重定向 。 如果随后 中间软件需要 Cookie 出现在请求中 .

应当与 `SessionMiddleware` 并被安置在它的后面 在中间软件函数链中.

应采用下列方式:

```javascript
// Create CookieConfig as required
const cookieConfig = { ... };

// Create sessionMiddleware using same cookie config, refer to previous section
// for explicit instructions
const sessionMiddleware = ...;
const ensureSessionCookiePresentMiddleware =
    EnsureSessionCookiePresentMiddleware({
        // Ensure use the same cookie name as session, spreading cookie config
        // will accomplish this
        ...cookieConfig,
        // Supply values for redirectHeaderName and redirectHeaderValue
        // to customise the header which is used to validate the redirected
        // request. (Defaults to name: `x-redirection-count` value: `1`)
        redirectHeaderName: "not-redirect",
        redirectHeaderValue: "not-true",
    })

app.use(sessionMiddleware)
app.use(ensureSessionCookiePresentMiddleware)
```

## 发展

模块需要可以通过 `npm install` 命令.

### 定点测试

代码是用 `ts-lint` 可通过 `npm run lint` 命令.

测试可依次通过 `npm test` 命令.

## 常见问题

### @companieshouse/node-session-handler 是什么？

公司大厦节点会务经理

### 如何安装 @companieshouse/node-session-handler？

在项目目录运行 npm install @companieshouse/node-session-handler，或使用 pnpm add / yarn add / bun add。

### @companieshouse/node-session-handler 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @companieshouse/node-session-handler 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @companieshouse/node-session-handler 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @companieshouse/node-session-handler 可以商用吗？

@companieshouse/node-session-handler 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @companieshouse/node-session-handler 的下载量有多少？

根据 npm 官方下载统计，@companieshouse/node-session-handler 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,432 次，日均约 81 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @companieshouse/node-session-handler 还在维护吗？

最新版本 5\.2\.23 发布于 2026/11/02（8 天前）；至今共发布 42 个版本，其中过去 12 个月发布了 16 个；首次发布于 2020/09/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。