# @asyncapi/converter 中文文档 规范地址：https://npmcn.com/package/%40asyncapi/converter/ 版本：2\.0\.2 npm 元数据更新时间：2026-08-06T14:24:49.743Z 中文译文更新时间：2026-11-07T01:35:16.591Z 软件包许可：Apache-2\.0 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40asyncapi/converter 原文对照：https://npmcn.com/package/%40asyncapi/converter/?lang=original 项目主页：https://github.com/asyncapi/converter-js#readme 源码仓库：https://github.com/asyncapi/converter-js ## 关键信息（来自 npm 元数据） - 包体积（解压后）：93.2 kB，19 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - 运行依赖：3 个 - 首次发布：2020-12-14T09:09:34.305Z - 最新版本发布：2026-08-06T14:24:49.370Z - 近 30 天下载量：800886（2026-10-07 至 2026-11-05，npm 官方下载统计） - 已发布版本数：53（近 12 个月 6 个） ## 中文简介 将 AsyncAPI 文档从旧版本转换为新版本 . ## 安装 ```sh npm install @asyncapi/converter ``` 也可以使用：`pnpm add @asyncapi/converter`、`yarn add @asyncapi/converter`、`bun add @asyncapi/converter` ## README # AsyncAPI 转换器 转换 [AsyncAPI 软件](https://asyncapi.com/) 文档中,您也可以将 OpenAPI 文档转换为 AsyncAPI 文档. [![All Contributors](https://img.shields.io/badge/all_contributors-10-orange.svg?style=flat-square)](https://npmcn.com/package/%40asyncapi/converter/#readme-contributors-) - [安装](https://npmcn.com/package/%40asyncapi/converter/#readme-installation) - [使用量](https://npmcn.com/package/%40asyncapi/converter/#readme-usage) - [从CLI](https://npmcn.com/package/%40asyncapi/converter/#readme-from-cli) - [在联署材料中](https://npmcn.com/package/%40asyncapi/converter/#readme-in-js) - [在TS时](https://npmcn.com/package/%40asyncapi/converter/#readme-in-ts) - [2.x.x转换为3.x.x](https://npmcn.com/package/%40asyncapi/converter/#readme-conversion-2xx-to-3xx) - [已知缺失的特性](https://npmcn.com/package/%40asyncapi/converter/#readme-known-missing-features) - [OpenAPI 3.0 到 AsyncAPI 3.0 转换](https://npmcn.com/package/%40asyncapi/converter/#readme-openapi-30-to-asyncapi-30-conversion) - [限制](https://npmcn.com/package/%40asyncapi/converter/#readme-limitations) - [发展](https://npmcn.com/package/%40asyncapi/converter/#readme-development) - [捐款](https://npmcn.com/package/%40asyncapi/converter/#readme-contribution) - [贡献者](https://npmcn.com/package/%40asyncapi/converter/#readme-contributors-%E2%9C%A8) ## 安装 ```sh npm i @asyncapi/converter ``` ## 使用量 ### 从CLI 要转换控制台中的 AsyncAPI 文档, 需要官方 [AsyncAPI 缩写](https://github.com/asyncapi/cli)。 。 。 . 如果您没有安装 CLI, 请运行此命令, 以便在您的系统上在全球安装 CLI : ```sh npm install -g @asyncapi/cli ``` 输出的最小使用示例 : ```sh asyncapi convert streetlights.yml -o streetlights2.yml # Result: asyncapi: '2.0.0' channels: ... ``` 转换为特定版本 : ```sh asyncapi convert streetlights.yml -o streetlights2.yml -t 2.3.0 # Result: asyncapi: '2.3.0' channels: ... ``` ### 在联署材料中 ```js const fs = require('fs'); const { convert } = require('@asyncapi/converter') try { const asyncapi = fs.readFileSync('streetlights.yml', 'utf-8') console.log(convert(asyncapi, '2.6.0')); } catch (e) { console.error(e); } ``` ### 在TS时 ```ts import { convert } from '@asyncapi/converter'; import type { ConvertVersion, ConvertOptions } from '@asyncapi/converter'; try { const toVersion: ConvertVersion = '2.6.0'; const asyncapi = fs.readFileSync('streetlights.yml', 'utf-8') console.log(convert(asyncapi, toVersion)); } catch (e) { console.error(e) } ``` ## 2.x.x转换为3.x.x > **页:1**:这个功能仍然是WIP,直到最后发布 `3.0.0`。 。 。 . 转换为版本 `3.x.x` 从 `2.x.x` 有若干假设,在转换前应当知道: - 输入必须是有效的 AsyncAPI 文档 . - 外部的参考文献没有解决和转换,即使不正确,它们也没有受到影响. - 版本 `3.0.0`,频道标识符不再是它的地址,但由于难以定义一个独特的标识符,我们仍然将地址视为标识符. 如果需要指定地址以外的标识符 `x-channelId` 扩展应在给定信道的级别上定义. ```yaml # 2.x.x channels: users/signup: x-channelId: 'userSignUp' ... users/logout: ... # 3.0.0 channels: userSignUp: ... users/logout: ... ``` - 这个 `publish` 操作被视为 `receive` 行动,以及 `subscribe` 被视为 `send` 行动。 从应用的角度接受默认转换。 如果您想要改变此逻辑, 您需要指定 `v2tov3.pointOfView` 配置为 `client`。 。 。 . - 如果操作没有 `operationId` 字段定义,操作的独特标识符将被定义为对操作进行定义的信道的标识符+操作类型, `publish` 或者说 `subscribe`. 同样的情况与信息相同。 然而,这里的优先事项是 `messageId` 字段然后接合 `{publish|subscribe}.messages.{optional index of oneOf messages}`。 。 。 . ```yaml # 2.x.x channels: users/signup: publish: message: ... subscribe: operationId: 'userSignUpEvent' message: oneOf: - messageId: 'userSignUpEventMessage' ... - ... # 3.0.0 channels: users/signup: messages: publish.message: ... userSignUpEventMessage: ... userSignUpEvent.message.1: ... operations: users/signup.publish: action: receive ... userSignUpEvent: action: send ... ``` - 使用范围的安全要求在适当的内在地点界定,其余则作为参照 `components.securitySchemes` 对象. - 如果服务器在频道级别上被定义,它们会被转换为引用在 `servers` 字段. - 在组件中定义的通道和服务器也被转换(除非另作配置). ## 已知缺失的特性 - 在从 1. x 转换为 2. x 时, 流出 API (使用 `stream` 改为 `topics` 或者说 `events`)被正确转换,但有关框架类型和划界符的信息将丢失,直到 [协议信息](https://github.com/asyncapi/extensions-catalog/issues/1) 将为此设立. - 从 2. x 转换为 3. x 时,和 `parameter.schema` 以引用方式定义,它不会研究计划参考,并包括v3参数的任何相关关键词。 它只会创建一个空参数, 但将计划留在组件部分不变 . ```yaml # 2.x.x channels: "{myParameter}": parameters: myParameter: schema: $ref: "#/components/schemas/mySchema" components: schemas: mySchema: enum: ["test"] default: "test" examples: ["test"] # 3.0.0 channels: "{myParameter}": parameters: myParameter: {} components: schemas: mySchema: enum: ["test"] default: "test" examples: ["test"] ``` ## OpenAPI 3.0 到 AsyncAPI 3.0 转换 现在的转换器支持从OpenAPI 3.0到AsyncAPI 3.0的转换. 这个功能可以方便地将现有的OpenAPI 3.0文档转换为AsyncAPI 3.0. 要使用此新转换特性 : ```js const fs = require('fs'); const { convertOpenAPI } = require('@asyncapi/converter') try { const openapi = fs.readFileSync('openapi.yml', 'utf-8') const asyncapi = convertOpenAPI(openapi, '3.0.0', { from: 'openapi' }); console.log(asyncapi); } catch (e) { console.error(e); } ``` 当从 OpenAPI 转换到 AsyncAPI 时, 您可以使用 `perspective` 选项。 这使得您可以选择转换是否应该从应用程序或客户端的角度进行 ```js const { convertOpenAPI } = require('@asyncapi/converter') try { const asyncapi2 = fs.readFileSync('asyncapi2.yml', 'utf-8') const asyncapi3 = convertOpenAPI(asyncapi2, '3.0.0', { openAPIToAsyncAPI: { perspective: 'client' } }); console.log(asyncapi3); } catch (e) { console.error(e); } ``` 视角选项可以设置为“ 服务器”( 默认) 或“ 客户端 ” . - 与 `server` 视角 : `action` 变成 `receive` - 与 `client` 视角 : `action` 变成 `send` #### 限制 - 内部参考之外: 转换器不支持外部schema文件引用OpenAPI文档内部组件的假想. 在这种情况下,可能需要人工调整转换后的文件. ## 发展 1. 通过安装依赖来设置项目 `npm install` 2. 写出密码和测试. 3. 确保所有测试通过 `npm test` ## 捐款 读取 [捐款](https://github.com/asyncapi/.github/blob/master/CONTRIBUTING.md) 向导. ## 贡献者 感谢这些伟大的人[emoji 密钥](https://allcontributors.org/docs/en/emoji-key):
Maciej Urbańczyk
马西杰·乌尔班奇克
🚧 💻 🐛 👀 ⚠️ 📖		Fran Méndez
弗朗·门德斯
🚧 💻 🐛 👀 ⚠️ 📖		Lukasz Gornicki
卢卡斯·戈尔尼茨基
🚧 💻 🐛 👀 ⚠️ 📖 🚇		Germán Schnyder
赫尔曼·施奈德
💻 ⚠️		Barbara Czyż
芭芭拉・克西
🚇		depimomo
depimomo 语录
💻		Orville Daley
奥维尔·戴利
💻
Ryan R Sundberg
瑞安·R·桑德贝格
💻		Mohan Kumar
莫汉·库马尔
💻 ⚠️ 📖 💡		Mintu Gogoi
明图高伊
💻 📖 💡 ⚠️
本项目遵循 [全部贡献者](https://github.com/all-contributors/all-contributors) 规格。 任何捐款都欢迎! ## 常见问题 ### @asyncapi/converter 是什么？ 将 AsyncAPI 文档从旧版本转换为新版本 \. ### 如何安装 @asyncapi/converter？ 在项目目录运行 npm install @asyncapi/converter，或使用 pnpm add / yarn add / bun add。 ### @asyncapi/converter 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @asyncapi/converter 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @asyncapi/converter 可以商用吗？ @asyncapi/converter 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。 ### @asyncapi/converter 的下载量有多少？ 根据 npm 官方下载统计，@asyncapi/converter 在 2026/10/07 – 2026/11/05 这 30 天内被下载 800,886 次，日均约 26,696 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @asyncapi/converter 还在维护吗？ 最新版本 2\.0\.2 发布于 2026/08/06（3 个月前）；至今共发布 53 个版本，其中过去 12 个月发布了 6 个；首次发布于 2020/12/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。