# @apitraffic/utilities 中文文档

规范地址：https://npmcn.com/package/%40apitraffic/utilities/

版本：3\.0\.0
npm 元数据更新时间：2026-11-03T10:12:36.975Z
中文译文更新时间：2026-11-10T01:06:22.695Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40apitraffic/utilities
原文对照：https://npmcn.com/package/%40apitraffic/utilities/?lang=original
项目主页：https://www.apitraffic.io/docs/quickstart
源码仓库：https://github.com/apitraffic/platform

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

- 包体积（解压后）：1 MB，130 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：6 个
- 首次发布：2024-04-11T09:42:16.238Z
- 最新版本发布：2026-11-03T10:12:36.741Z
- 近 30 天下载量：1690（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 5 个）

## 中文简介

所有节点框架 sdks 中包含的公用事业.

## 安装

```sh
npm install @apitraffic/utilities
```

也可以使用：`pnpm add @apitraffic/utilities`、`yarn add @apitraffic/utilities`、`bun add @apitraffic/utilities`

## README

# @ api 流量/ 用户

核心公用设施库,为所有ApiTraffic Node.js框架SDK提供共享功能. 该软件包包含用于请求管理、外出拦截、数据处理和配置管理的共同设施.

## 安装

```bash
npm install @apitraffic/utilities
```

## 特征

-   **请求管理** - 集中要求跟踪和背景管理
-   **外出拦截** - 自动 `http`编号 :`https` **财务报告和审定财务报表 `fetch`** 请求拦截和监测
-   **配置管理** - 以环境变量支持进行统一配置处理
-   **数据处理** - 请求/答复机构处理和期限计算
-   **内容管理** - 请求上下文和标记系统
-   **设置管理** - 动态设置检索和缓存

## 快速启动

```javascript
const { setup, RequestManager, config } = require('@apitraffic/utilities');

// Initialize ApiTraffic utilities
await setup({
  token: 'your-api-token',
  bucket: 'your-bucket-id',
  ingestHost: 'ingest.apitraffic.io',
  apiHost: 'api.apitraffic.io',
  interceptOutbound: true,
  debug: false
});

// Create a request manager
const requestManager = new RequestManager(config);
requestManager.tag('environment', 'production');
```

## API 参考

### 设置函数

以您的配置初始化 ApiTraffic 工具 .

```javascript
const { setup } = require('@apitraffic/utilities');

await setup(options, context);
```

#### 选项

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `token` | 字符串 | 对 | 您的 ApiTraffic API 令牌 |
| `bucket` | 字符串 | 对 | 您的 ApiTraffic 桶标识 |
| `ingestHost` | 字符串 | 没有 | 指定端点主机( 默认: 来自 env) |
| `apiHost` | 字符串 | 没有 | API 端点主机( 默认: 来自 env) |
| `interceptOutbound` | 布尔 | 没有 | 启用向外请求截取( 默认: 真) |
| `captureFetch` | 布尔 | 没有 | 捕获出界 `fetch` 调用( 默认: 真) |
| `maxFetchBodyLength` | 编号 | 没有 | 每个捕获的字节上限 `fetch` 请求/答复机构(默认:524288,即512 KB) |
| `maxBodyBytes` | 编号 | 没有 | 每个被捕获的请求/响应机构的字节上限,在编辑后应用;较长的身体被切换出一个标记(默认:524288,即512 KB;env) `API_TRAFFIC_MAX_BODY_BYTES`(中文(简体) ) |
| `requestSampleRate` | 编号 | 没有 | 向 ApiTraffic 发送请求的分数( 0– 1) 。 服务器错误( 5xx) 总是发送( 默认: 1.0; env) `API_TRAFFIC_REQUEST_SAMPLE_RATE`(中文(简体) ) |
| `debug` | 布尔 | 没有 | 启用调试记录( 默认: 假) |

#### 环境变量

您也可以使用环境变量配置 :

-   `API_TRAFFIC_TOKEN` - 你的API代号
-   `API_TRAFFIC_BUCKET` - 你的桶身份证
-   `API_TRAFFIC_INGEST_HOST` - 最佳端点主机
-   `API_TRAFFIC_API_HOST` - API 端点主机
-   `API_TRAFFIC_INTERCEPT_OUTBOUND` - 启用出入境拦截
-   `API_TRAFFIC_CAPTURE_FETCH` - 捕获出入境 `fetch` 电话
-   `API_TRAFFIC_MAX_FETCH_BODY_LENGTH` - 每捕获一字节上限 `fetch` (违约:524288)
-   `API_TRAFFIC_REDACT_SENSITIVE_KEYS` - 默认的遮盖证书形状的正文密钥和查询参数(默认:真实)
-   `API_TRAFFIC_INGEST_BATCH` - 当您的账户和摄入主机提供时, 寄出的分批吞噬请求( 默认: 真实)
-   `API_TRAFFIC_INGEST_GZIP` - 当您的账户要求时, Gzip 这些批次( 默认: 真)
-   `API_TRAFFIC_DEBUG` - 启用调试模式

被压缩的批量压缩了数个被捕获的有效载荷(已经被修改) 所以压缩的好坏取决于这些有效载荷的含量 常见。 攻击者可以把所选内容输入俘获 sDK的出行请求的加密大小 摄入, 设定 `ingestGzip: false` (单位:千美元)`API_TRAFFIC_INGEST_GZIP=false`),或请求 账户的 `ingest.batch.gzip` 要关闭的旗帜, 发送批次 无所压缩.

### 内建编辑

在任何离开进程之前,证书形状名称下的值是 替换为 `[*** API REDACTED ***]`不管账户的规则怎么说 在JSON和 `application/x-www-form-urlencoded` 尸体和被俘者 URL的查询字符串(出入口). 规则旨在命名 _拿着_ 一个秘密,而不是名字 提到一个:

-   `password`, (中文(简体) ), `passwd`, (中文(简体) ), `passcode`, (中文(简体) ), `secret`, (中文(简体) ), `apikey`, (中文(简体) ), `accesskey`, (中文(简体) ), `privatekey`, (中文(简体) ), `credential`, (中文(简体) ), `signature`, (中文(简体) ), `assertion`, (中文(简体) ), `jwt` 在任何一处 名称( 忽略分隔符 : `api_key`, (中文(简体) ), `x-api-key` 财务报告和审定财务报表 `apiKey` 全部对齐);
-   结束于 `token` (单位:千美元)`access_token`, (中文(简体) ), `csrfToken`),但不能标注 光标( r)`pageToken`, (中文(简体) ), `nextToken`)或计数(`max_tokens`(三);
-   单词 `auth`, (中文(简体) ), `pass`, (中文(简体) ), `pwd`, (中文(简体) ), `otp`, (中文(简体) ), `sig`, (中文(简体) ), `mfa`, (中文(简体) ), `totp`· ; `secret_key`\- 式键和 `auth_code`\- 式码; `session`, (中文(简体) ), `sessionid`, (中文(简体) ), `sid`, (中文(简体) ), `authorization`, (中文(简体) ), `cookie`· ;
-   只有查询字符串中: `key`, (中文(简体) ), `code` 词 `pin`。 。 。 .

布尔斯, `null` 并保留空值。 机构经过编辑——仅限 蒙面值会改变, 所以没有其它关于被俘尸体的改变. 多段和XML机构没有密钥。 证书信头 (单位:千美元)`authorization`, (中文(简体) ), `cookie`, (中文(简体) ), `x-api-key`,.)总是被修改.

关闭密钥口罩 `redactSensitiveKeys: false` (或阴道) (见上文)。 SDK也尊重一个账户级别 `redaction.sensitiveKeys: false` 当仪表板提供开关时 账户规则 范围为 `request.query` 应用到抓取的 URL 查询字符串,并按键 规则适用于组成机构.

### 出境 `fetch` 捕获

出境 `http`编号 :`https` 调用(xios, got, node-fatch的 http path,...) 被捕获 通过补丁 `http.request`全球 `fetch` 从来没有经过它,它驱动 节点的内置undici直通插座——所以它有自己的钩子,安装了 与其余的出入境拦截。 A 类 `fetch` 电话报告与 与轴线相同的细节 : URL,方法,信头实际安装在线上 (从undici的) `sendHeaders` 诊断事件,所以 `host`, (中文(简体) ), `content-length` 财务报告和审定财务报表 `accept-encoding` 请求和答复 机构、状态、响应标题和时间,加内线 `http.out` 横跨 打电话的请求.

捕捉不会改变呼叫:呼叫者会得到准确的 `Response` 对象, 和身体读取从 `clone()`s. 值得了解的两个后果:

-   有效载荷上限为 `maxFetchBodyLength`, (中文(简体) ), **默认512 KB** (单位:千美元) `http` 路径的上限是 3 MB ),因为读取一个响应的复制件会连接流—— a 高高的盖子与您同时持有第二个大下载副本 拥有的。 超过盖子的尸体是被截取并标记的 升为 无论你的载荷和头室证明什么
    
    ```javascript
    await setup({ /* … */ maxFetchBodyLength: 512 * 1024 * 1024 }); // 512 MB
    ```
    
    ```bash
    API_TRAFFIC_MAX_FETCH_BODY_LENGTH=536870912
    ```
    
-   请求体是一个溪流, `FormData` 或者说 `Blob`,且非文本或 `text/event-stream` 答复,仅作为元数据列报 (单位:千美元)`bodyCaptured: false`而不是被消耗或重写.
    

设定 `captureFetch: false` (或 `API_TRAFFIC_CAPTURE_FETCH=false`离开 `globalThis.fetch` 无所未有.

钩子本身不需要比18号节点更新鲜的了(验证在 联合国 在没有全局的运行时间 `fetch` 钩子根本就没有 安装, 如果无法安装无线头事件, 信头是呼叫者 相反,报告设定.

值得了解钩子本身的两个属性:

-   随你怎么说 `globalThis.fetch` 安装时间和标记 本身,所以两次安装(或从此软件包的复制件)不会 堆栈包装和另一个库包 `fetch` 之后仍然运行在上面 这个 密码 _替换_ `globalThis.fetch` 设置后直接(而不是 把它包起来)去掉钩子,这些电话会被扣住.
-   线头通过undici请求身份(通过 `undici:request:create` ,而不是通过 URL,所以 同时提出的相同请求——包括发出不合秩序或排队的请求 在集合连接上——不能互换头集.

### 请求管理器

管理单个请求的上下文、标签和痕迹.

```javascript
const { RequestManager } = require('@apitraffic/utilities');

const manager = new RequestManager(settings);
```

#### 方法

**`tag(key, value)`** 在当前请求上下文中添加标签 .

```javascript
manager.tag('user_id', '12345');
manager.tag('environment', 'production');
```

**`removeTag(key)`** 从当前请求上下文中删除标签 .

```javascript
manager.removeTag('user_id');
```

**`trace(message)`** 在请求中添加一个跟踪消息 .

```javascript
manager.trace('Database query executed');
```

### 工具函数

**`getDuration`** 计算两个时间点之间的持续时间 .

```javascript
const { getDuration } = require('@apitraffic/utilities');

const startTime = process.hrtime();
// ... some operation
const duration = getDuration(startTime);
```

**`handleResponseBody`** 处理并处理响应体数据.

```javascript
const { handleResponseBody } = require('@apitraffic/utilities');

const processedBody = handleResponseBody(responseData, options);
```

**`sendToApiTraffic`** 将请求数据发送到 ApiTraffic 服务 .

```javascript
const { sendToApiTraffic } = require('@apitraffic/utilities');

await sendToApiTraffic(options, payload);
```

### Span 指纹帮助器

这个包是 **单一真相来源** apiTraffic 是如何变成原始的 运行到稳定状态 `fingerprint` (因此,相同的SQL/Redis/HTTP/海关 操作崩溃为一个身份 `GROUP BY fingerprint` 分析。 这个 `@apitraffic/apm` OTel大桥导入了同样的帮助,所以手动计时 同一操作的相接相接相接相接相接相接相接相接相接 指纹。 输入是 **原始内容** ——常态化/装模作样发生在内部.

```javascript
const {
  normalizeSql,       // "SELECT * FROM t WHERE id = 42" -> "SELECT * FROM t WHERE id = ?"
  maskRedisKey,       // "user:12345:profile" -> "user:{}:profile"
  fingerprintSql,     // (statement) -> "fpr_<16hex>"
  fingerprintRedis,   // (type, command, key, patterns?) -> "fpr_<16hex>"
  fingerprintHttpOut, // (method, host, pathPattern) -> "fpr_<16hex>"
  fingerprintGeneric, // (type, name) -> "fpr_<16hex>"
  fingerprintFrom,    // (parts:string) -> "fpr_<16hex>"  (low-level)
} = require('@apitraffic/utilities');
```

`maskRedisKey` 编辑 `*Redis*` 帮助者接受可选选项 `redisKeyPatterns: Array<string | RegExp>` 以覆盖内置 用于键形的可变分泌热力学,不能自行推断出.

### 配置

访问全局配置对象 :

```javascript
const { config } = require('@apitraffic/utilities');

console.log(config.apiToken);
console.log(config.bucketSid);
console.log(config.ingestHost);
```

### 内容管理

在整个应用程序中管理请求上下文 :

```javascript
const { context } = require('@apitraffic/utilities');

// Get current context
const currentContext = context.get();

// Set context data
context.set('requestId', 'req-123');
```

## 所需资源

-   节点.js 20.0.0或以上
-   有效的 ApiTraffic 账户和 API 令牌

## 依赖关系

此软件包包括以下依赖性:

-   `@apitraffic/data-redaction` - 数据编辑公用事业
-   `@apitraffic/javascript-helpers` - JavaScript 帮助函数
-   `@faker-js/faker` - 数据生成公用事业
-   `ably` - 实时通讯
-   `axios` - HTTP 客户端
-   `ksuid` - 独特的ID生成
-   `pako` - 数据压缩
-   `systeminformation` - 系统信息收集

## 捕捉到的东西

框架包按客户收到时报告每个入境请求. 当答复是: **承诺** 当其第一个字节被交接到套接字(`onCommit`)——不是当它 完成,对于一个大响应来说,只有客户端读取了它. 这个 捕捉在字节被写入之后运行,所以它永远不会延迟回复, 和丢出(无效的标题值或状态代码)的写入 无:以下的错误反应是报告的内容.

**请求机构** 意思是每个框架都是一样的: 应用程序在响应时有它——包括更改其中间软件、钩子 或处理器在答复之前, 或没有处理器在答复之后。 通常这样 承诺 如果一个图层将字节背过应用程序 电话: `compression` 或者说 `express-session` 安装在 SDK 之后, 一个自动同步 快捷化 `onSend` 钩子,哈皮的gzip —— 单是请求,当 应用程序开始响应( e)`onCommit`是因为 `start`),这个捕捉步骤 运行在响应的字节之前, 只在路径上。 价格低廉:a 已宣布其请求超过 `maxRedactBodyBytes` (单位:千美元)`Content-Length`由占位符替换而无需序列化,以及 任何其他被解析出的尸体 由本地序列器序列化 并定居到 确切地说,这是有限度的相机所造作的(记号), 缓冲器),当有效载荷准备时,离开响应路径.

| 软件包 | 请求机构 | 没看见 |
| --- | --- | --- |
| `@apitraffic/express` | `req.body` | 更改 `res.send()` 编号 : `res.end()` |
| `@apitraffic/fastify` | `request.body` | 更改 `reply.send()` (和在 `onResponse` 钩子) |
| `@apitraffic/koa` | `ctx.request.body` | 写入回复后的更改 |
| `@apitraffic/hapi` | `request.payload` | 答复一经转发(和 `onPostResponse` 延长) |

**反应机构** 是客户端发送的: 在快递上,有效载荷 改为 `reply.raw` - 申请结束后 `onSend` 钩子(一个能擦去 字段)——或对于流体或内容编码体,有效载荷 当它到达SDK的 `onSend`。一个内容编码的(gzip)机构永远不会 在任意框架上作为压缩字节报告.

答复完成时记录现状和时间(`499` 为客户服务 先断开的 尸体的巢穴有256个以上的深层——被剖析,或 JSON 文本框架为字符串, 当账户编辑规则会 解析——或无法被读取或被编辑的被发送为 `[body not captured: …]` 占位符和在 `bodyNotCaptured` 送货统计。 无法完成编辑的请求 即使没有它的躯体,它也绝不被派去 `droppedUnredactable`。 。 。 .

## 交货和代理

每个抓获的请求都作为JSON送去 `POST`编制和发送 关闭响应路径( 在 `setImmediate`,在答复之后 在SDK本身的活性剂上,有限定的货币,a 小重试队列和一个断路器。 使用节点的插图 `http`编号 :`https` 直接说 何时 `HTTP_PROXY` 编号 : `HTTPS_PROXY` 编号 : `ALL_PROXY` (或它们) `npm_config_*` 表格)适用于摄入的 URL 协议,这些帖子通过 而不是像以前一样,它的代理支持(`NO_PROXY`, CONNECT 地道 hTTPS)仍然适用. 代理变量最多每10个重读一次 秒数。 SDK自己的呼号(摄取,设置,主机遥测,嵌入符) 从未被记录为申请的外传电话.

## 处理错误

公用事业包括全面处理错误:

```javascript
try {
  await setup({
    token: 'invalid-token',
    bucket: 'invalid-bucket'
  });
} catch (error) {
  console.error('Setup failed:', error.message);
}
```

常见错误 :

-   缺少 API 令牌或桶ID
-   无效的节点.js版本( < 18.0.0)
-   网络连接问题
-   无效的配置参数

## 调试模式

启用调试模式以查看详细记录 :

```javascript
await setup({
  token: 'your-token',
  bucket: 'your-bucket',
  debug: true
});
```

或通过环境变量:

```bash
export API_TRAFFIC_DEBUG=true
```

## 许可证

麻省理工学院许可证 - 详情见LICENSE文件.

## 支助

支助和文件,访问 [ApiTraffic.io (英语)](https://apitraffic.io/) 或联系人 [sdk@ apitraffic.io (英语)](mailto:sdk@apitraffic.io)。 。 。 .

## 常见问题

### @apitraffic/utilities 是什么？

所有节点框架 sdks 中包含的公用事业\.

### 如何安装 @apitraffic/utilities？

在项目目录运行 npm install @apitraffic/utilities，或使用 pnpm add / yarn add / bun add。

### @apitraffic/utilities 支持 TypeScript 吗？

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

### @apitraffic/utilities 支持 ESM 还是 CommonJS？

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

### @apitraffic/utilities 需要什么版本的 Node\.js？

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

### @apitraffic/utilities 可以商用吗？

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

### @apitraffic/utilities 的下载量有多少？

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

### @apitraffic/utilities 还在维护吗？

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