# axios-dedupe-adapter 中文文档

规范地址：https://npmcn.com/package/axios-dedupe-adapter/

版本：0\.1\.0
npm 元数据更新时间：2026-11-03T02:30:20.698Z
中文译文更新时间：2026-11-03T04:43:26.012Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/axios-dedupe-adapter
原文对照：https://npmcn.com/package/axios-dedupe-adapter/?lang=original

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

- 包体积（解压后）：18.9 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=14
- 运行依赖：0 个
- peer 依赖：axios \>=0\.21
- 首次发布：2026-11-03T02:27:10.907Z
- 最新版本发布：2026-11-03T02:30:20.537Z
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

用于并发请求重复数据删除（动态合并）的Axios适配器，具有可选的TTL结果缓存。零运行时依赖项。

## 安装

```sh
npm install axios-dedupe-adapter
```

也可以使用：`pnpm add axios-dedupe-adapter`、`yarn add axios-dedupe-adapter`、`bun add axios-dedupe-adapter`

## README

# axios-dedupe-adapter

> Axios 适配器：并发请求合并（in-flight dedupe）+ 可选 TTL 结果缓存。零运行时依赖。

## 特性

-   **零运行时依赖** — 仅依赖 axios（peer），npm 装下来 0KB 额外体积
-   **三种行为模式**：
    -   默认（`isMerge` 未设置）：完全透明，和原生 axios 行为一致
    -   仅合并（`isMerge: true, cacheTime: 0`）：并发同请求共享一个 Promise，完成立即释放
    -   合并 + 缓存（`isMerge: true, cacheTime: N`）：请求完成后结果保留 N 秒
-   **边界安全**：
    -   AbortController 的 `signal` 请求**不会被合并**（取消语义不会错乱）
    -   `FormData` / `Blob` / `ArrayBuffer` / 循环引用对象**不会被错误合并**
    -   JSON 字符串与对象在拦截器阶段 / adapter 阶段算出的 key 保持一致

## 安装

```bash
npm install axios-dedupe-adapter
# 或
pnpm add axios-dedupe-adapter
# 或
yarn add axios-dedupe-adapter
```

## 使用

```js
import axios from 'axios'
import { createDedupeAdapter } from 'axios-dedupe-adapter'

const instance = axios.create({ baseURL: '/api' })

// 挂载适配器
instance.defaults.adapter = createDedupeAdapter(instance)

// ============ 每个请求单独控制行为 ============

// 普通请求（默认不合并，零副作用）
instance.get('/users')

// 并发同请求合并：只发一次 HTTP，两个调用方共享同一个 Promise
instance.get('/shared', { isMerge: true })
instance.get('/shared', { isMerge: true }) // ← 不发新请求

// 合并 + 缓存 10 秒：10 秒内后续请求直接返回缓存结果
instance.get('/config', { isMerge: true, cacheTime: 10 })
```

### 运行时清除缓存

```js
import { clearCache } from 'axios-dedupe-adapter'

// 所有进行中请求和结果缓存（含定时器）全部释放
clearCache()
// 场景：用户登出、主题切换、退出某租户
```

### 挂到实例上方便调用

```js
import { createDedupeAdapter, clearCache, generateRequestKey } from 'axios-dedupe-adapter'

instance.defaults.adapter = createDedupeAdapter(instance)
instance.clearCache = clearCache
instance.generateRequestKey = generateRequestKey
```

## 设计说明

### 并发合并 vs 结果缓存

两者独立但可组合：

| `isMerge` | `cacheTime` | 行为 |
| --- | --- | --- |
| 未设置 / `false` | 忽略 | 每次发新请求（默认，零副作用） |
| `true` | `0` | 只合并 in-flight 请求，完成立即释放 |
| `true` | `> 0` | 合并 + 请求完成后缓存 N 秒 |

### 为什么 signal 请求不合并

```js
const ctrl = new AbortController()
instance.get('/resource', { signal: ctrl.signal, isMerge: true })
```

如果这个请求被合并，它会共享**第一个**请求的 Promise 和 signal。当你 `ctrl.abort()` 时，实际上会把**所有在途的共享请求**一起取消 —— 这违反了使用者对 AbortController 的直觉（一个 controller 只控制自己的请求）。因此实现里显式跳过带 `signal` 的请求。

### 为什么 FormData 不自动合并

`JSON.stringify(new FormData()) === '{}'`，这意味着两个不同内容的表单（比如上传文件 A 和文件 B）会算出同一个 key。实现里手动把 FormData 展开成 `name=value&name=value` 的形式，遇到非 string 值（File / Blob）直接降级为唯一 key，保证安全。

### 拦截器 / adapter 两阶段 key 对齐

axios 请求生命周期中，`config.data` 可能在拦截器阶段是对象、在 adapter 阶段被 `transformRequest` 序列化成 JSON 字符串。如果 key 只 `JSON.stringify(value)`，这两个阶段会算出不同 key，导致缓存永远命不中。`normalizePart()` 对字符串形式的 JSON 做了 `parse → stringify` 归一化，保证两个阶段结果一致。

## API

### `generateRequestKey(config)` → `string`

从 axios config 生成唯一 key。同 `(url, method, params, data)` 的请求得到相同 key。可用于自定义逻辑（比如自己写 abort controller 的缓存 key）。

### `createDedupeAdapter(axios)` → `Function`

创建适配器函数，赋值给 `axios.defaults.adapter`。

### `clearCache()` → `void`

清空全部缓存条目（含 in-flight + 结果缓存 + 定时器）。**不会取消正在进行中的底层 HTTP 请求**，只是释放本地 Map。

## 注意事项

-   `isMerge` 默认关闭，不影响现有请求行为
-   `signal` 请求不会被合并
-   `FormData` 含非 string 值、二进制、循环引用对象会退化为唯一 key（不会被错误合并，但**也不会享受到合并/缓存的好处**）
-   `clearCache()` 不取消正在进行的 HTTP 请求，只清空本地缓存

## License

MIT

## 常见问题

### axios-dedupe-adapter 是什么？

用于并发请求重复数据删除（动态合并）的Axios适配器，具有可选的TTL结果缓存。零运行时依赖项。

### 如何安装 axios-dedupe-adapter？

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

### axios-dedupe-adapter 支持 TypeScript 吗？

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

### axios-dedupe-adapter 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### axios-dedupe-adapter 需要什么版本的 Node\.js？

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

### axios-dedupe-adapter 可以商用吗？

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

### axios-dedupe-adapter 还在维护吗？

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