# @bbc/http-transport-cache 中文文档

规范地址：https://npmcn.com/package/%40bbc/http-transport-cache/

版本：6\.0\.1
npm 元数据更新时间：2026-10-23T16:09:20.946Z
中文译文更新时间：2026-11-07T19:03:51.172Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：17.6 kB，14 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=24
- 运行依赖：4 个
- peer 依赖：@bbc/http-transport ^5\.0\.0
- 首次发布：2017-09-05T13:24:27.510Z
- 最新版本发布：2026-10-15T15:06:58.571Z
- 近 30 天下载量：3218（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：61（近 12 个月 2 个）

## 中文简介

缓存中间软件

## 安装

```sh
npm install @bbc/http-transport-cache
```

也可以使用：`pnpm add @bbc/http-transport-cache`、`yarn add @bbc/http-transport-cache`、`bun add @bbc/http-transport-cache`

## README

[![NPM downloads](https://img.shields.io/npm/dm/@bbc/http-transport-cache.svg?style=flat)](https://npmjs.org/package/@bbc/http-transport-cache) ![npm](https://img.shields.io/npm/v/@bbc/http-transport-cache.svg) ![license](https://img.shields.io/badge/license-MIT-blue.svg) ![github-issues](https://img.shields.io/github/issues/bbc/http-transport-cache.svg) ![stars](https://img.shields.io/github/stars/bbc/http-transport-cache.svg) ![forks](https://img.shields.io/github/forks/bbc/http-transport-cache.svg)

# HTTP 传输缓存

HTTP 光谱兼容缓存层 `http-transport`。 。 。 .

## 安装

```
pnpm install --save http-transport-cache
```

## 使用量

根据最大年龄配置响应缓存 :

```js
const cache = require('@bbc/http-transport-cache');
const Catbox = require('@hapi/catbox');
const HttpTransport = require('@bbc/http-transport');

const catbox = new Catbox.Client(new Memory());

const url = 'http://example.com/';

const client = HttpTransport.createBuilder()
      .use(cache.maxAge(catbox))
      .createClient();

      const body = await client.get(url)
        .asBody();

      console.log(body);
```

配置 stale- if- error :

```js
const cache = require('@bbc/http-transport-cache');
const Catbox = require('catbox');
const HttpTransport = require('@bbc/http-transport');

const catbox = new Catbox.Client(new Memory());

const url = 'http://example.com/';

const client = HttpTransport.createClient()
      .use(cache.staleIfError(catbox))
      .createClient();

      const body = await client.get(url)
        .asBody();

      console.log(body);
```

倾听事件 :

```JS
const { events, maxAge } = require('@bbc/http-transport-cache');

const stats = require('@ibl/stats');
const Catbox = require('catbox');
const HttpTransport = require('@bbc/http-transport');

const catbox = new Catbox.Client(new Memory());

const url = 'http://example.com/';

const client = HttpTransport.createBuilder()
  .use(cache.maxAge(catbox, {
    name: `theservice`,
  }))
  .createClient();

events.on(`cache.theservice.read_time`, (ctx) => {
  stats.timing(`timingstat.read_time`, ctx.duration);
});
```

## 特征

| 特性 | 说明 |
| --- | --- |
| 警告 | 缓存的响应只包含简化 `http-transport` 请求和响应,以避免浪费缓存空间. |
| 最大年龄 | 答复在 `max-age` 指令,并在提出请求之前使用. |
| 如果出错, 设置 | 为了确保即使在出错时也能提供弹性服务,http响应可以包括: `cache-control` 调用指令 `stale-if-error` 也就是说,当服务出错时, 我们可以使用缓存回复。 要做到这一点, 单独保存一个响应blob, 用于 stale 期间, 在错误时, 这个响应会与保存在其中任何高端的正体一起使用 `max-age` 或者说 `stale-if-error`。 。 。 . |
| 无存储 | 若为 `no-store` 指令在响应中存在, 它不会在任何地方被存储 / 缓存 . |
| 私营 | 若为 `private` 指令存在于响应中, 它不会被共享缓存存储 。 该响应将只存储在专供单一用户使用的私人缓存中. |

### 活动

-   击出
-   错过
-   错误
-   超时
-   暂停
-   读取时间( t)
-   写入时间( t)
-   连接错误

## 中间软件选项

两者 `maxage` 财务报告和审定财务报表 `staleIfError` 接受选项对象.

| 财产 | 类型 | 模块 | 说明 |
| --- | --- | --- | --- |
| `ignoreCacheErrors` | 布尔 | 最大年龄, 如果错误 | `cache.maxAge` 当此属性为 `true`设置此属性为 `cache.staleIfError` 将重新删除原始错误( 不是缓存查找错误 ). `ignoreCacheErrors` 实值 `false` 默认. |
| `timeout` | 整数 | 最大年龄 | 在指定数 ms 后暂停缓存搜索 。 默认情况下, 不指定超时 . |
| `connectionTimeout` | 整数 | 最大年龄, 如果错误 | 取消在指定数 ms后连接缓存的尝试 。 默认情况下, 不指定超时 . |
| `includeCacheStatusInCtx` | 布尔 | 最大年龄, 如果错误 | 现时a `cacheStatus` 阵列 - 记录所有缓存事件, 将设置在 `context` 用于其他插件. `includeCacheStatusInCtx` 实值 `false` 默认. |

## 缓存版本

缓存阴道存储于 `config.json`中,这不同于 `package.json`。缓存版本用于缓存密钥中,旨在减少缓存破碎现象,即该库的多个不同版本可能用于单个产业.

缓存版本 **必须** 如果对存储在缓存中的数据作出与现有版本不相容的修改,则会递增。 否则不应改变.

## 缓存密钥结构

缓存使用 `catbox` 以提供一个简单的可插接接口,它支持将缓存和ID分割开来,因此使用下列部分:

-   http-transport:{version}: reswer -- -- 缓存通话的基本响应 `max-age` 仅在响应的 URL 上显示值键.
-   http- transport:{version}:staleResponse - 调用缓存的 Stale响应 `stale-if-error` 值仅在响应的 URL 上键入.

此外,缓存密钥可以通过通过一个 `varyOn` 选项. `varyOn` 应当包含一系列请求头名称,缓存中应另作改动;对于一些用例,向同一端点提出的请求,但对某些信头有不同值的请求,会引发不同的响应,因此不能共享相同的缓存响应,例如.`accept-language`通过让 `http-transport-cache` 将会构建一个特殊的缓存密钥, 其中也将包含上述信头及其值 .

示例

我们做一个 `GET` 请求访问以下 URL : `www.example.com/some-cacheable-path`。 。 。 .

我们不同了 `accept-language` 财务报告和审定财务报表 `accept`。这些信头将存在于请求中。 我们过去 `varyOn` (各种请求头,我们不同)与其他选项一起配置插件.

```js
const opts = {
  timeout: 2000,
  varyOn: [
    'accept-language',
    'accept'
  ]
};
```

在第一个请求中 `accept-language` 实值 `en` 财务报告和审定财务报表 `accept` 实值 `application/json`。由此产生的关键是:

-   获取:www.example.com/some-cacheble-path:accept-language=en,accept=应用/json

在第二项请求中 `accept-language` 实值 `fr` 财务报告和审定财务报表 `accept` 实值 `text/html`。由此产生的关键是:

-   获取:www.example.com/some-cacheable-path:accept-language=fr,accept=text/html 页面存档备份,存于互联网档案馆

这样可以避免商店中的数据误读过度.

## 测试

```
pnpm test
```

为生成测试覆盖报告:

```
pnpm run coverage
```

## 常见问题

### @bbc/http-transport-cache 是什么？

缓存中间软件

### 如何安装 @bbc/http-transport-cache？

在项目目录运行 npm install @bbc/http-transport-cache，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@bbc/http-transport（^5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bbc/http-transport-cache 支持 TypeScript 吗？

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

### @bbc/http-transport-cache 支持 ESM 还是 CommonJS？

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

### @bbc/http-transport-cache 需要什么版本的 Node\.js？

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

### @bbc/http-transport-cache 可以商用吗？

@bbc/http-transport-cache 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @bbc/http-transport-cache 的下载量有多少？

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

### @bbc/http-transport-cache 还在维护吗？

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