# @amritk/asyncapi 中文文档

规范地址：https://npmcn.com/package/%40amritk/asyncapi/

版本：0\.3\.8
npm 元数据更新时间：2026-10-22T18:54:16.625Z
中文译文更新时间：2026-11-06T01:36:00.659Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40amritk/asyncapi
原文对照：https://npmcn.com/package/%40amritk/asyncapi/?lang=original
项目主页：https://github.com/amritk/mjst/tree/main/packages/asyncapi#readme
源码仓库：https://github.com/amritk/mjst

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

- 包体积（解压后）：91 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-09-08T17:29:34.361Z
- 最新版本发布：2026-10-22T18:54:16.190Z
- 近 30 天下载量：58970（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

从 AsyncAPI 2.x/3.0 文档中提取 mjst 生成器的 JSON Schemas .

## 安装

```sh
npm install @amritk/asyncapi
```

也可以使用：`pnpm add @amritk/asyncapi`、`yarn add @amritk/asyncapi`、`bun add @amritk/asyncapi`

## README

# @ amritk/ ayncapi

**摘录 JSON Schemas——和 `@amritk/api` 频道合同——取自AsyncAPI 2.x/3.0文档.**

![status](https://img.shields.io/badge/status-pre--alpha-ef4444?style=flat-square)  ![version](https://img.shields.io/npm/v/@amritk/asyncapi?style=flat-square&logo=npm&logoColor=white&label=version&color=6366f1)  ![license](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)  ![AsyncAPI](https://img.shields.io/badge/AsyncAPI-2.x%20%7C%203.0-f97316?style=flat-square)  ![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=flat-square&logo=node.js&logoColor=white)  ![vibe coded](https://img.shields.io/badge/vibe-coded-a855f7?style=flat-square)

* * *

## 概览

`@amritk/asyncapi` 将 AsyncAPI 文档—— 2. 0 到 2.6 或 3.0 —— 拖出每个消息的有效载荷和信头 **自成一体的JSON Schema 2020-12文档**,准备 [`@amritk/validation`](https://npmcn.com/package/%40amritk/validation), (中文(简体) ), [`@amritk/generate-examples`](https://npmcn.com/package/%40amritk/generate-examples),或 [`@amritk/runtime-validators`](https://npmcn.com/package/%40amritk/runtime-validators)。这是后面的取出层 `mjst --input asyncapi`。 。 。 .

"自足"买什么:AsyncAPI默认的schema方言(草案-07超集)升级为2020-12公约,OpenAPI格式有效载荷获得 `nullable` 折叠成它们 `type`和每个 `$ref` 输入文档 `#/components/schemas/...` 重置为本地 `$defs` 与中途复制的被引用组件——因此,每个提取出的计划都单独作为生成器输入.

它还将每个频道投放到一个 [`@amritk/api`](https://npmcn.com/package/%40amritk/api) **电文合同**: AsyncAPI 宣布的两个方向成为 `clientToServer`编号 :`serverToClient`,每个消息的名称成为其电线歧视值,而歧视者的财产被从有效载荷中剥出——这正是形状 `defineMessages` 拿着 那个预测就是 `mjst --input asyncapi --message-contracts` 写入磁盘 .

两个主机都正常化为一个3.0形状的模型. 方向从应用程序的角度命名( 2. x) `publish` → `receive`, (中文(简体) ), `subscribe` → `send`),匹配 [`@amritk/api`](https://npmcn.com/package/%40amritk/api)信息合约 阿芙罗 `schemaFormat` 实值 **转换**没有跳过.. [`@amritk/adapters`](https://npmcn.com/package/%40amritk/adapters) 已经读了Avro, 所以这些有效载荷到达 发电机像任何其他。 一个用这里没有读到的语言写出的有效载荷(Protobuf, RAML),每条电文都会被跳过,并附有一个被记录的问题,一个转换器拒绝的Avro schema也是如此——一个坏的有效载荷从不花费文件的其他电文.

* * *

## 安装

```bash
npm install @amritk/asyncapi
# or
pnpm add @amritk/asyncapi
# or
yarn add @amritk/asyncapi
# or
bun add @amritk/asyncapi
```

* * *

## 使用量

```ts
import { extractAsyncApi, listMessageSchemas } from '@amritk/asyncapi'

// Parse the document yourself (JSON.parse, @amritk/yaml, ...) — this package
// takes the already-parsed value and never touches the filesystem or network.
const model = extractAsyncApi(document)

for (const issue of model.issues) {
  console.warn(`${issue.path}: ${issue.message}`)
}

for (const channel of model.channels) {
  for (const message of channel.messages) {
    // message.payload / message.headers are self-contained JSON Schema 2020-12
    console.log(channel.key, message.name, message.direction)
  }
}

// Flatten into generator inputs: one { subDir, rootTypeName, schema } per
// payload/headers, laid out as channels/<channel>/<message>[-headers].
const schemas = listMessageSchemas(model)
```

### 频道合同

```ts
import { buildChannelContract } from '@amritk/asyncapi'
import { defineMessages } from '@amritk/api'

for (const channel of model.channels) {
  const contract = buildChannelContract(channel)
  for (const issue of contract.issues) console.warn(`${issue.path}: ${issue.message}`)

  // The two maps are keyed by the value a frame carries on the wire, payloads
  // already stripped of the tag — hand them straight to defineMessages.
  const messages = defineMessages({
    discriminator: contract.discriminator,
    clientToServer: contract.clientToServer,
    serverToClient: contract.serverToClient,
  })
}
```

歧视者按以下优先顺序解决: `x-mjst: { discriminator }` 在频道,然后 `discriminator` 选项,然后 `'type'` (比对) `@amritk/api`'默认'). 文档故意胜过选项——一个选项涵盖整个运行,运行可能跨越不一致的通道.

**关键是标记,而不是名字.** 有效载荷通常写出自己的标记—— `type: { const: 'bot_added' }` 一个替代的渠道是如何说哪个信息——这个价值成为合同的关键,因为它是电线上真正到达的东西。 AsyncAPI 信件 _名称_ 仅仅是一个无所不能的有效载荷的倒置;它是一个文件授权手柄,以及一个内有2.x的信息 `oneOf` 经常一无所有。 Slack 的 RTM 文档名称为消息 `botAdded` 并标记它 `bot_added`在名字上按键会发出合同 听从一个从未到过的框架.

有两条留言 _不变_ 标记在 _不变_ 方向是一个框架形状,有两种描述,所以第一个胜利,第二个报告(Slack声明其单曲有两个消息) `bot_added` 活动)。 有效载荷限制标记而不把它固定在一个字符串上—— `type: { type: 'string' }`,多成员 `enum`,非字符串 `const` 运行时间无法选择的消息名称, 并随一个问题跳过 .

**信头不是合同的一部分.** `listMessageSchemas` 发送消息的 `headers` 计划是自己的可基因树,但是 `buildChannelContract` 只有项目有效载荷: `@amritk/api` 信件合同描述WebSocket帧,其中没有包含自己的信头. 对于 Kafka 或 MQTT 文档,仍然生成标题类型( under `<message>-headers/`——它们只是你的在经纪人边界上应用,而不是套接字运行时间验证的东西.

交叉文件和远程 `$ref`s是加载器的工作:先解决(例如: [`@amritk/resolve-refs`](https://npmcn.com/package/%40amritk/resolve-refs);一个仍未解决的外部引用作为一个问题报告,从未被获取.

* * *

## API 密码

-   **`extractAsyncApi(document, options?)`** → `AsyncApiModel` - 正常化文件: `version`, (中文(简体) ), `major`, (中文(简体) ), `title?`, (中文(简体) ), `channels` (每个单位 `key`, (中文(简体) ), `address?`, (中文(简体) ), `messages`),并收集 `issues`。只有在输入根本不是 AsyncAPI 文档时才丢出. `options.avroEncoding` 选择 JSON 塑造 Avro 有效载荷的形状 : `'json'` (默认)是被解码的对象,应用程序与, `'avro-json'` 这是Spec的JSON编码,因为它行走在线上.
-   **`listMessageSchemas(model, issues?)`** → `ExtractedSchema[]` 一个 `{ subDir, rootTypeName, schema }` 每个可基因的有效载荷/弹头,带有确定性的相撞后缀目录符号;碰撞问题附在 `model.issues` (或对 `issues` 阵列.
-   **`buildChannelContract(channel, options?)`** → `ChannelContract` - 一个频道作为 `{ exportName, discriminator, clientToServer, serverToClient, issues }`,准备 `defineMessages`。 。 。 .
-   **`resolveDiscriminator(channel, override?)`** 编号 : **`DEFAULT_DISCRIMINATOR`** ——以上优先权顺序 `'type'` 倒计时.
-   **`stripDiscriminator(payload, discriminator)`** → `{ schema, tag? }` 或者说 `{ issue }` 标记的有效载荷被移除,加上标记贴有的值,或者为什么两个标记都无法读取.
-   **`sanitizeToken(value, fallback)`** ——文件系统 和 导入安全 符号 两种输出布局都命名一个频道或信件.
-   **`detectAsyncApiVersion(document)`** - 那个 `asyncapi` 版本及其主要,或 `undefined`。 。 。 .
-   **`classifySchemaFormat(schemaFormat)`** - 哪种语法a `schemaFormat` 名称 (`'asyncapi' | 'draft-07' | '2020-12' | 'openapi' | 'avro'`),或 `'unsupported'`。 。 。 .
-   **`mergeTraits(target, traits, precedence)`** 作为RFC 7386 JSON 合并补丁的特性应用(重复性,因此双方的嵌入式贡献能活下来); `precedence` 实值 `'trait'` 2.x(海峡超过目标)或 `'target'` 3.0(目标胜出)。 之前应用 `schemaFormat` 读取.

* * *

## 许可证

麻省理工学院

## 常见问题

### @amritk/asyncapi 是什么？

从 AsyncAPI 2\.x/3\.0 文档中提取 mjst 生成器的 JSON Schemas \.

### 如何安装 @amritk/asyncapi？

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

### @amritk/asyncapi 支持 TypeScript 吗？

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

### @amritk/asyncapi 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @amritk/asyncapi 需要什么版本的 Node\.js？

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

### @amritk/asyncapi 可以商用吗？

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

### @amritk/asyncapi 的下载量有多少？

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

### @amritk/asyncapi 还在维护吗？

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