# @12-apps/request-scope 中文文档

规范地址：https://npmcn.com/package/%4012-apps/request-scope/

版本：2\.1\.0
npm 元数据更新时间：2026-08-25T00:29:36.076Z
中文译文更新时间：2026-11-05T20:08:10.716Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%4012-apps/request-scope
原文对照：https://npmcn.com/package/%4012-apps/request-scope/?lang=original
项目主页：https://github.com/12-apps/shared-packages#readme
源码仓库：https://github.com/12-apps/shared-packages

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

- 包体积（解压后）：40.2 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：0 个
- peer 依赖：hono \>=4\.0\.0
- 首次发布：2026-08-15T11:44:41.893Z
- 最新版本发布：2026-08-25T00:29:35.763Z
- 近 30 天下载量：31988（2026-10-04 至 2026-11-02，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

通用的、便携式的 AMBIENT 请求范围,供服务于网络标准请求/响应的主机使用。 无框架核心(一个 Async LocalStorage 备份的每个请求商店,一个对齐的cookie read/write codec, 队列的cookie 写作被排入向外的响应,以及

## 安装

```sh
npm install @12-apps/request-scope
```

也可以使用：`pnpm add @12-apps/request-scope`、`yarn add @12-apps/request-scope`、`bun add @12-apps/request-scope`

## README

# `@12-apps/request-scope`

符合网络标准的主机的环境要求范围 `Request`编号 :`Response`: 读取从任何地点收到的信头和饼干 调用链条,从代码中排出一个没有手头回复的 cookie 写入,以及 两者都合并到 答案的路上.

零运行时间依赖关系. `node:async_hooks` 没有别的了.

* * *

## 问题解决

网络标准处理器需要 `Request` 返回 a `Response`。这是一个 干净的合约,直到一瞬间 某某某某某某称十二深要知道 他们正在打电话——一辆由饼干按键的推车,一个同意门,一个冒名顶替 标记,一个即将到来的持有人。 有两条出路:

1.  **线索 `Request` 通过每一个中间的签名.** 这转动了 将细节传送到域层的参数中,它是病毒: 新的 cookie 读取器会更改十几个函数签名及其测试.
2.  **环境访问器**由一个明确的商店支持.

这个包裹是第二个,商店是重点. `AsyncLocalStorage` 实值 容易接触,容易犯错误——店铺身份横跨一热 重新装入, 无法写入的写出半个, 重定向标题 拒绝 `Set-Cookie`这些是值得分享的.

## 三个切入点

| 导入 | 对于 |
| --- | --- |
| `@12-apps/request-scope` | 无框架核心——商店、编码器、响应帮助器 |
| `@12-apps/request-scope/hono` | hono 中间软件`hono` 是一个 **选项** 端点) |
| `@12-apps/request-scope/next-compat` | `cookies()` 编号 : `headers()` 与 `next/headers`形状,用于从 App 路由器迁移到主机 |

```ts
import { requestScope } from '@12-apps/request-scope/hono';

app.use('*', requestScope());
```

这就是整条线。 然后,在下游任何地方:

```ts
import { requireRequestScope, writeCookie } from '@12-apps/request-scope';

const scope = requireRequestScope();
const cartId = scope.values.get('cart');
writeCookie(scope, 'cart', nextId, { httpOnly: true, sameSite: 'lax', path: '/' });
```

发送自己的路由表而不是编组中间软件使用的主机 单打表格:

```ts
import { serveWithRequestScope } from '@12-apps/request-scope';

const response = await serveWithRequestScope(request, () => handler(request));
```

* * *

## 四个决定值得了解

### 将饼干船当作一个物体来读写一半

`createCookieCodec()` 手还原 `serialize`, (中文(简体) ), `serializeDeletion` 财务报告和审定财务报表 `parse` 一起来 饼干层唯一可能出错的方法就是不同意 本身 —— %-decode 与序列器配对的解析器 编码所有用它测试过的东西, 并指定第一个值 包含一个分隔符。 将双对绑在一个对象上删除调用站点 它可以进口一半.

### 编码是一个 knob, 它的默认是安全方向

RFC 6265禁止 `;`, (中文(简体) ), `,`,以数值表示空白和控件字符,所以 百分数编码是正确的,是默认的。 但有一个主机通过这个包 已经有饼干坐在浏览器中, 由它以前使用过的东西来写 .

两种模式在推出期间相会,只有一个方向存活下来:

-   (单位:千美元) **原始内容** 数值 **解码** 帕塞尔很好.. `decodeURIComponent` 任何没有身份的 `%` 在那座乐园里,有不义的逃亡者 回到原案文,而不是抛出;
-   a 一个 **编码** 数值改为a **原始内容** 读者是 主机的旧部署代码, 此软件包无法到达 .

这么说吧 `createCookieCodec({ encode: false })` 对已有原始主机已存在 饼干,旗子翻来翻去... ... ......

### `requireRequestScope()` 故意抛出

代码读取可选证书——无记名信头,冒名饼干 将存取器包入 `try` 并视一掷为 _"没有来袭" 请求,所以没有证书"_返回 `undefined` 会崩溃的 输入与 _"没有这种饼干的要求"_,这些需要 不同的处理方式:一个是背景工作,另一个是匿名访客.

`currentRequestScope()` 是非抛出形式, 对于合法代码 在请求内外运行.

### 重定向得到重建而不是禁止

`Response.redirect()` 指定返回一个 **不可改变** 标题列表,所以 附录a `Set-Cookie` 投在地上, 清除饼干时重定向为 完全普通(OAuth召回 放弃它的状态饼干),所以更确切地说 而不是禁止内置的——一条规则是下一个处理器重新发现为500个—— `applyResponseCookies` 当其标题拒绝写入时重建响应.

`redirectResponse()` 另一半是:通过建造者建造的转向架, 所以它的头部可以变形 默认为 **307 (简体中文)**,而不是302号 `Response.redirect()` 给出,因为 307 保留了方法—— 重定向添加 给一个非 GET 处理器的处理器, 后来表现为写入而不是默默地降级 {\\fn黑体\\fs20\\shad2\\2aH82\\3aH20\\4aH33\\fscx95\\3cH592001\\be1}继续追踪尸体的失落.

* * *

## 霍诺适配器和 `c.res`

值得浮出水面 因为它在被咬之前是隐形的 浩诺 `c.res` **设置** 重现了前次反应中的标题及其 `set-cookie` 分支为:

```js
const cookies = this.#res.headers.getSetCookie();  // the OLD list
_res.headers.delete('set-cookie');                 // wipes the NEW list
for (const cookie of cookies) _res.headers.append('set-cookie', cookie);
```

因此通过转让合并 **丢入** 中间软件排队的饼干.. 确切地说,只有操作者自己写一个,就是这样 二者必须生存 适配器附着在原地,然后掉回 只能为不可改变的反应分配任务,而这种反应不能通过建筑 携带 `Set-Cookie` 属于自己的。 两半都由测试所支撑.

## 挂载顺序

挂起中间软件 **在此之前** 任何读取 cookie 或页眉的东西 环境上 上面注册的路线在范围外及其接通者 抛出——这是意图失败:大声地,在第一次要求下,而不是 默默缺席.

## 与另一个同时存在 `AsyncLocalStorage`

这家店是开着的 `globalThis` 所以一个重新评价模块的 dev 服务器 无法制造第二个无法避免的封锁。 这个 因为同样的原因,它生活在密钥下是可塑的 `@12-apps/audit` 制造 其演员存储密钥可配置:一个已经拥有内部的主持人 请求范围模块,由呼叫站点导入,需要两个模块一个 存储.

```ts
import { declareRequestScopeKey } from '@12-apps/request-scope';

declareRequestScopeKey('__myHostRequestStore'); // at wiring time, once
```

两家持不同意见的商店不会大出声地倒闭——接入者看一个商店一文不值 曾经进入和扔出 "在请求范围" 从一个完美的内部 普通请求。 在商店存在后再拨号 被拒绝而不是 默默地荣耀.

注意: `@12-apps/audit` 是一个 **不同** 范围a 不同寿命:携带 _谁是演员_,这个携带 _来了_。 。 。 . 它们由同一个适配器打开,否则对每个都无话可说 其他费用.

* * *

见 [`ADOPTING.md`](https://npmcn.com/package/%4012-apps/request-scope/ADOPTING.md) 为整合游戏本.

## 常见问题

### @12-apps/request-scope 是什么？

通用的、便携式的 AMBIENT 请求范围,供服务于网络标准请求/响应的主机使用。 无框架核心\(一个 Async LocalStorage 备份的每个请求商店,一个对齐的cookie read/write codec, 队列的cookie 写作被排入向外的响应,以及

### 如何安装 @12-apps/request-scope？

在项目目录运行 npm install @12-apps/request-scope，或使用 pnpm add / yarn add / bun add。

### @12-apps/request-scope 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/12-apps\_\_request-scope 是否存在。

### @12-apps/request-scope 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @12-apps/request-scope 需要什么版本的 Node\.js？

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

### @12-apps/request-scope 可以商用吗？

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

### @12-apps/request-scope 的下载量有多少？

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

### @12-apps/request-scope 还在维护吗？

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