# @blueground/async-mdc 中文文档

规范地址：https://npmcn.com/package/%40blueground/async-mdc/

版本：1\.0\.2
npm 元数据更新时间：2025-09-05T16:20:49.085Z
中文译文更新时间：2026-11-08T08:29:34.572Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：18.7 kB，17 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- 首次发布：2025-09-05T16:20:48.363Z
- 最新版本发布：2025-09-05T16:20:48.718Z
- 近 30 天下载量：8078（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

Async hooks基于Mapped诊断背景,灵感来自SLF4J的MDC. 通常与伐木库一起用于丰富木材.

## 安装

```sh
npm install @blueground/async-mdc
```

也可以使用：`pnpm add @blueground/async-mdc`、`yarn add @blueground/async-mdc`、`bun add @blueground/async-mdc`

## README

# Async 磁共振

为Node.js应用程序使用Aync钩实施轻量级,型号安全的Mapped诊断上下文(MDC). 这个库为管理跨同步操作的上下文数据提供了一个干净的方法,使它能完美地用于请求追踪,记录,并在整个呼叫链中保持应用状态.

## 特征

-   🚀 **无依赖** - 在Node.js本土建造 `AsyncLocalStorage`
-   🔒 **类型安全** - 配备自定义存储界面的完整类型脚本支持
-   🛡️ **安全作业** - 所有业务的投放和非投放变体
-   🔄 **锁定集成** - 与皮诺、布尼扬、温斯顿和其他伐木工无缝合作

## 安装

```sh
$ npm i --save @bluegroundltd/async-mdc     # NPM
$ yarn add --save @bluegroundltd/async-mdc  # Yarn
$ bun add --save @bluegroundltd/async-mdc   # Bun
$ pnpm add --save @bluegroundltd/async-mdc  # PNPM
```

## 基本用途

```typescript
// mdc.ts
import {MDC} from '@bluegroundltd/async-mdc';
export {MDC};

// You can define your own MDC store or use the default Record<string, any>
export interface MDCStore extends Record<string, unknown> {
  correlationId: string;
  user: {
    userId: string;
    email: string;
  };
  ip: string;
  meta?: {
    foo?: string;
    bar?: string;
  };
}

export const mdc = new MDC<MDCStore>();

// middleware.ts
import {mdc} from 'mdc.js';
app.get((req, res, next) => {
  mdc.set('user', req.session.user);
  next();
});

// service.ts
function foo() {
  // access user
  const user = mdc.safeGet('user');
}
```

## API 密码

### 新建 MDC( \[存储\] ): MDC

```typescript
import {MDC} from '@bluegroundltd/async-mdc';
export {MDC};

// You can define your own MDC store or use the default Record<string, any>
export interface MDCStore extends Record<string, unknown> {
  color: string;
  height?: number;
}

const mdc = new MDC<MDCStore>();

// or define your own storage
const asl = new AsyncLocalStorage<MDCStore>();
const mdc = new MDC<MDCStore>(asl);
```

### 获取( 键, \[默认值\])

获取与之相关的值 `key`。 。 。 .

`get` 如果下方为 [本地同步组件](https://nodejs.org/api/async_context.html#class-asynclocalstorage) 未初始化

```typescript
mdc.get('color');
mdc.get('color', 'black');
```

### 安全获取( 密钥, \[默认值\])

获取与之相关的值 `key`。 。 。 .

`safeGet` 永不掷出并返回 `undefined` 或者说 `defaultValue` 如果给定则

```typescript
mdc.safeGet('color');
mdc.safeGet('color', 'black');
```

### 设置( 键, 值)

在此 mdc 中添加或更新一个带有指定密钥和值的条目.

`set` 如果下方为 [本地同步组件](https://nodejs.org/api/async_context.html#class-asynclocalstorage) 未初始化

```typescript
mdc.set('color', 'white');
```

### 安全设置( 键, 值)

在此 mdc 中添加或更新一个带有指定密钥和值的条目.

`safeSet` 永远不要抛出和行为 作为一个 noop 代替

```typescript
mdc.safeSet('color', 'white');
```

### 获取 CopyOfsStore (): 存储

`getCopyOfStore` 返回 aync 上下文存储的浅色副本

```typescript
mdc.getCopyOfStore();
```

### 清除( c)

通过去除商店的所有密钥来清除商店

```typescript
mdc.clear();
```

### 运行( store: store, callback : () QQ R, ... args): R

基层机构的代表 [aync 本地服务器](https://nodejs.org/api/async_context.html#asynclocalstoragerunstore-callback-args)

## 用于伐木机

### 皮诺

[https://github.com/pinojs/pino (英语)](https://github.com/pinojs/pino)

```typescript
// logger.ts
import {pino} from 'pino';
import {MDC} from '@bluegroundltd/async-mdc';

// Import from another module e.g. mdc.js
import {mdc} from 'mdc.js';
// Or create and export from here
export const mdc = new MDC();

// Enrich every log message with bindings from the MDC store
// @see {@link https://github.com/pinojs/pino/blob/main/docs/api.md#mixin-function}
function mixin() {
  return mdc.getCopyOfStore();
}

export const logger = pino({
  mixin
});
```

### 邦扬

[https://github.com/trentm/node-bunyan 页面存档备份,存于互联网档案馆](https://github.com/trentm/node-bunyan)

```typescript
// logger.ts
import bunyan from 'bunyan';
import {MDC} from '@bluegroundltd/async-mdc';

// Import from another module e.g. mdc.js
import {mdc} from 'mdc.js';
// Or create and export from here
export const mdc = new MDC();

const logger = bunyan.createLogger({
  name: 'myapp',
  mdc,
  serializers: {
    ...bunyan.stdSerializers,
    mdc(_mdc) {
      return _mdc.getCopyOfStore();
    }
  }
});
```

### 温斯顿 3.x

[https://github.com/winstonjs/winston (英语)](https://github.com/winstonjs/winston)

```typescript
// logger.ts
import winston from 'winston';
import {MDC} from '@bluegroundltd/async-mdc';

// Import from another module e.g. mdc.js
import {mdc} from 'mdc.js';
// Or create and export from here
export const mdc = new MDC();

const mdcFormat = winston.format((info, opts) => {
  return {
    ...mdc.getCopyOfStore(),
    ...info
  };
});

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(winston.format.json(), mdcFormat)
});
```

## 许可证

这个项目根据麻省理工学院许可证颁发——见 [自由主义](https://npmcn.com/package/%40blueground/async-mdc/LICENSE) 详细文件.

### MIT 许可证

特此准许任何人免费获得本软件和相关文件文件("软件")的副本,不受限制地在软件中进行交易,包括不受限制地享有软件的使用、复制、修改、合并、出版、分发、分版和(或)销售的权利,并允许软件获得者这样做,但须符合下列条件: 1

上述版权通知和许可通知应载入软件的所有副本或大部分.

软件是提供的"AS IS", 没有任何种类的恐惧, 释放或被卷入, 包括但不限制在 危机的保障, 证明一个特定的目的和无关。 任何索赔、索赔或其他负债,无论是合同、交易或其他行为,产生于、产生于或涉及软件或软件的使用或其他交易的行为,都不得作为担保.

* * *

**版权:"2025"蓝地有限公司. 版权所有.**

## 常见问题

### @blueground/async-mdc 是什么？

Async hooks基于Mapped诊断背景,灵感来自SLF4J的MDC\. 通常与伐木库一起用于丰富木材\.

### 如何安装 @blueground/async-mdc？

在项目目录运行 npm install @blueground/async-mdc，或使用 pnpm add / yarn add / bun add。

### @blueground/async-mdc 支持 TypeScript 吗？

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

### @blueground/async-mdc 支持 ESM 还是 CommonJS？

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

### @blueground/async-mdc 需要什么版本的 Node\.js？

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

### @blueground/async-mdc 可以商用吗？

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

### @blueground/async-mdc 的下载量有多少？

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

### @blueground/async-mdc 还在维护吗？

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