概览

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

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

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

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

安装

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

使用量

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)

频道合同

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/——它们只是你的在经纪人边界上应用,而不是套接字运行时间验证的东西.

交叉文件和远程 $refs是加载器的工作:先解决(例如: @amritk/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 读取.

许可证

麻省理工学院