# @fibery/correlation-id 中文文档

规范地址：https://npmcn.com/package/%40fibery/correlation-id/

版本：5\.0\.1
npm 元数据更新时间：2026-07-24T12:22:09.112Z
中文译文更新时间：2026-11-14T16:45:28.927Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40fibery/correlation-id
原文对照：https://npmcn.com/package/%40fibery/correlation-id/?lang=original
项目主页：https://gitlab.com/fibery/correlation-id#readme
源码仓库：https://gitlab.com/fibery/correlation-id

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

- 包体积（解压后）：17.7 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.4
- 运行依赖：0 个
- 首次发布：2020-12-01T10:15:41.692Z
- 最新版本发布：2024-01-15T11:44:41.080Z
- 近 30 天下载量：2782（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 0 个）

## 中文简介

基于 async 本地存储的关联 id 帮助器

## 安装

```sh
npm install @fibery/correlation-id
```

也可以使用：`pnpm add @fibery/correlation-id`、`yarn add @fibery/correlation-id`、`bun add @fibery/correlation-id`

## README

# 关联度

## 如何使用

创建关联 id 实例

```javascript
import {createCorrelationId} from '@vizydrop/correlation-id';
const correlationId = createCorrelationId();
```

与 `@fibery/vizydrop-logger`

```javascript
const {createLogger} = require(`@fibery/vizydrop-logger`);

const logger = createLogger({
    correlationId: {
        enabled: true,
        getCorrelationId: () => correlationId.correlator.getId(),
        emptyValue: `nocorrelation`,
    },
});
```

注册中间软件。 支助 `koa` 财务报告和审定财务报表 `express`

```javascript
// koa
app.use(correlationId.koaMiddleware);
// express
app.use(correlationId.expressMiddleware);
```

增强请求, 因此每个请求将包含关联 id http header .

```javascript
const request = require(`request`);
const correlatedRequest = correlationId.enhanceRequest(request);
correlatedRequest.get(`http://anotherservice:10020/data`);
```

增强 http 代理服务器, 因此每个代理请求将包含关联 id http header .

```javascript
const httpProxy = require(`http-proxy`);
const proxy = httpProxy.createProxyServer({
    target: `http://anotherservice:10020/`,
});
correlationId.enhanceHttpProxy(proxy);
```

运行工作。 工作通常不会完成 `express/koa` 中间软件的关联性 id 应该手动生成.

```javascript
function jobTask() {}

function runJob() {
    correlationId.correlator.withId(correlator.generateDefaultId(), () => {
        jobTask();
    });
}
```

## 设置

自定义设置可以作为对象传递到 `createCorrelationId` 函数.

-   `generateDefaultId` - 函数,该函数应返回新的相关性 ID。 默认 [`crypto.randomUUID`](https://nodejs.org/api/crypto.html#cryptorandomuuidoptions) 已使用.

## 相关标识 API

-   `expressMiddleware` - 表示在关联范围内运行下个中间软件的中间软件 id async hook
-   `koaMiddleware` - 运行关联范围内下个中间软件的可口中间软件
-   `enhanceHttpRequest` - 接收请求并返回默认添加关联性 id 头的新请求实例
-   `enhanceHttpProxy` - 默认添加关联 id 头的附加收听器
-   `correlator.getId()` - 返回当前相关性 id
-   `correlator.withId(id, fn)` - 运行函数和所有后继函数,并指定相关性 id
-   `correlator.bind()` - 将所提供的功能与当前执行上下文绑定在一起。 其实现在它是一个简单的化名 对AsyncResource。 绑定 [https://nodejs.org/api/async context.html#整合-asyncresources- with-eventemitter (中文(简体) )](https://nodejs.org/api/async_context.html#integrating-asyncresource-with-eventemitter)
-   `correlator.generateId()` - 生成新的关联 id

## 5.0.0后已知问题

自兹 `bindEmitter` 方法被取消了,我们没有绑定 `req` 在快取和可口中间软件中 可能有一些边缘情况 关联识别丢失. 根据 [https://github.com/nodejs/node/issues/33723 页面存档备份,存于互联网档案馆](https://github.com/nodejs/node/issues/33723) 不建议绑定整个发射体,因为在不同上下文中执行可能是有意的,因此包件应该保持正确的同步上下文。 它实际上被固定在许多包 像快递.js,身体-parser, [完成时](https://github.com/jshttp/on-finished),收紧等. 在大多数情况下,如果这仍然是个问题,这就可以解决了 `correlator.bind` (见 [https://nodejs.org/api/async context.html#整合-asyncresources- with-eventemitter (中文(简体) )](https://nodejs.org/api/async_context.html#integrating-asyncresource-with-eventemitter)) (中文(简体) ). 以下例子说明如何为已死的koa-morgan包工作:

```
<!-- WAS -->
app.use(morgan(
    `:method :status :url (:res[content-length] bytes) :response-time ms`,
    {
        stream: {
            write: (text) => logger.info(text.trim()), // no correlation id here, context is lost
        },
        immediate: false,
    },
));

<!-- Should become -->
app.use(async (ctx, next) => {
    await morgan(
        `:method :status :url (:res[content-length] bytes) :response-time ms`,
        {
            stream: {
                write: correlator.bind((text) => logger.info(text.trim())), // correlation-id is here as we bound the callback to current async context
            },
            immediate: false,
        },
    )(ctx, next);
});
```

## 已知问题 4.3.0.

-   工作不顺利 `bluebird.promisifyAll`. 替代办法是明确使用本地承诺进行混合

```javascript
const redis = require(`redis`);
const util = require(`util`);

const client = redis.createClient();

client.setAsync = util.promisify(client.set).bind(client);
client.getAsync = util.promisify(client.get).bind(client);
```

-   工作不顺利 `mongoose` 召回电话。 另一种解决办法是使用混合函数.

```javascript
const mongoose = require(`mongooose`);
mongoose.Promise = global.Promise;

EntityModel.find({name: `name`}).then((value) => {
    // do something
});
```

## 常见问题

### @fibery/correlation-id 是什么？

基于 async 本地存储的关联 id 帮助器

### 如何安装 @fibery/correlation-id？

在项目目录运行 npm install @fibery/correlation-id，或使用 pnpm add / yarn add / bun add。

### @fibery/correlation-id 支持 TypeScript 吗？

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

### @fibery/correlation-id 支持 ESM 还是 CommonJS？

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

### @fibery/correlation-id 需要什么版本的 Node\.js？

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

### @fibery/correlation-id 可以商用吗？

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

### @fibery/correlation-id 的下载量有多少？

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

### @fibery/correlation-id 还在维护吗？

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