ProtoBuff 数据类型 Schema 解析器

用于 协议缓冲 数据类型。 它会插入 @asyncapi/parser 让你嵌入 .proto 消息 定义 payload (或 schemaasyncAPI 文档中的 在解析期间 Protobuf定义被转换成基于JSON Schema的AsyncAPI(基于JSON Schema)计划,所以其余的 AsyncAPI工具可以和任何其他消息有效载荷一样工作.

概览

AsyncAPI消息可以携带以不同语种描述的有效载荷. @asyncapi/parser 代表任何有效载荷 schemaFormat 它不理解 本地注册 策略解析器。这个软件包是协议缓冲的策略:您注册一次,以及 每个信件的有效载荷都贴上Protobuf标签 schemaFormat 解析并扩展为 等同 AsyncAPI 计划.

• 与 Protobuf 2和Protobuf 3号 计划.
• 计划格式的注册 application/vnd.google.protobuf;version=2 财务报告和审定财务报表 application/vnd.google.protobuf;version=3。 。 。 .
• 地图 Protobuf 消息, scalars, enums, repeated 字段,则, oneof 和巢型给JSON Schema.
• 将主要评论理解为说明和一套 @- 用于验证的说明,默认 和实例.
• 可选地图 原型验证 财务报告和审定财务报表 缩写 规则给 JSON Schema 验证器.
• 与浏览器相兼容的和同时建造了CommonJS和ES模块.

Protobuf 2和3没有严格的区分. 声明 schemaFormat 作为 application/vnd.google.protobuf;version=2 提供原型3计划(反之亦然)时 本身不会造成错误.

版本 >= 2.0.0 本软件包需要 @asyncapi/parser >= 2.0.0; 数据 3.x 目标 @asyncapi/parser >= 3.6.0。 。 。 .

• 安装
• 使用量
• 支持的投入
• 如何运作
• Scalar 类型格式
• 评论和说明
  • 每个字段注释
  • 每个信件注释
  • 头条注释
  • 首注"可选"
• 支持的验证框架
• 发展
• 捐款
• 许可证

安装

npm install @asyncapi/protobuf-schema-parser
# or
yarn add @asyncapi/protobuf-schema-parser

@asyncapi/parser 要使用此软件包。 需要节点.js >= 18。 。 。 .

使用量

创建一个 Parser,然后分析 AsyncAPI 文档 使用Protobuf软件 schemaFormat。Protobuf 源到消息中 payload 作为弦.

import { Parser } from '@asyncapi/parser';
import { ProtoBuffSchemaParser } from '@asyncapi/protobuf-schema-parser';

const parser = new Parser();
parser.registerSchemaParser(ProtoBuffSchemaParser());

const asyncapiWithProto = `
asyncapi: 2.0.0
info:
  title: Example with ProtoBuff
  version: 0.1.0
channels:
  example:
    publish:
      message:
        schemaFormat: 'application/vnd.google.protobuf;version=3'
        payload: |
          message Point {
            required int32 x = 1;
            required int32 y = 2;
            optional string label = 3;
          }

          message Line {
            required Point start = 1;
            required Point end = 2;
            optional string label = 3;
          }
`;

const { document, diagnostics } = await parser.parse(asyncapiWithProto);

同样的工作是与CommonJS:

const { Parser } = require('@asyncapi/parser');
const { ProtoBuffSchemaParser } = require('@asyncapi/protobuf-schema-parser');

const parser = new Parser();
parser.registerSchemaParser(ProtoBuffSchemaParser());

注释:

• ProtoBuffSchemaParser 既作为命名导出,又作为默认导出。 调用它 获取解析器实例,然后将该实例传递给 registerSchemaParser。 。 。 .
• 将您的 Protobuf 计划作为字符串放入信件 payload (AsyncAPI 2.x)或者在计划中 对象的 schema 关键词( AsyncAPI 3. x) 以获得解析. 见下面的固定装置 test/documents 对于两个变体.
• 解析后,信件有效载荷输入 document 是已转换的 AsyncAPI 计划.

支持的投入

• Protobuf 2和Protobuf 3号 消息定义.
• 两种注册计划格式:
  • application/vnd.google.protobuf;version=2
  • application/vnd.google.protobuf;version=3

参考资料为 没有 支持:

• 无支持 $ref 在普罗托布夫的有效载荷内.
• 无支持 import, (中文(简体) ), 除捆绑的知名定义外:
  • google/protobuf/* (以千美元计) protobufjs(中文(简体) )
  • google/type/* (与本包捆绑在一起)
  • 审定定义 validate/validate.proto 财务报告和审定财务报表 buf/validate/validate.proto

任何其他 import 解析时丢出错误.

如何运作

每个AsyncAPI文件可能包含数个消息有效载荷. 对于每个有效载荷: schemaFormat 匹配已注册的 MIME 类型之一,解析器将原始 Protobuf 字符串交给转换器, 用于 protobufjs 来分析 然后走 消息树,释放一个基于JSON Schema的 AsyncAPI schema.

因为一个JSON Schema有一个单一的根,转换器首先决定 根消息页:1 信件中未被任何其他信件作为字段类型引用。 如果有几个候选人留下来, 注释要用 @RootNode; 否则解析失败 Found more than one root proto messages。如果找不到根,解析失败 Not found a root proto messages。 。 。 .

主要绘图规则:

一个球场在 required 列表,如果附加了注释 @Required,是一种原型2 required 字段,或 携带 required 规则a 审定框架原生的3字段 从来不需要自己, optional 否:原型3没有 required 标签,和 a 字段中,没有明确存在的字段会从电线和ProtoJSON中省略,当它持有默认值时 数值。 A 类 required proto3 文件中的标签无效 proto3; 解析器忽略它并登录警告 命名字段.

递归信件被支持: 当当前两次遇到相同的信件类型时 分支,转换器停止下降以避免无限循环.

非标准x-)关键词用于保存没有直接JSON Schema的Protobuf信息 等量: x-primitive (原始 scalar 类型), x-type (参考消息/enum名称), x-type-description (当一个字段注释取代了引用的电文时的评论), x-enum-mapping (数字名称为数值),和 x-oneof-item (单位:千美元) oneof 字段已出现变体 从.

Scalar 类型格式

每个Protobuf scalar 类型被映射到一个 JSON Schema type 加一个 format 保留 原始的Protobuf线型. 举个例子 int64 变成 {"type": "integer", "format": "int64"} 财务报告和审定财务报表 bytes 变成 {"type": "string", "format": "bytes"}。另外保留了Protobuf型号 非标准 x-primitive 关键词 默认数字类型也带有 minimum编号 :maximum 限制(参见 primitiveTypesWithLimits 选项).

评论和说明

一个消息的每个字段都可能有一个评论,反应为JSON Schema description。 。 。 . 此外,评论还可包含以下说明:

message Point {
    /*
     * The coordinate on the x axis.
     * @Default 99
     * @Min 0
     * @Max 100
     */
    required int32 x = 1;

    /*
     * The coordinate on the y axis.
     * @Default 12
     * @Min 0
     * @Max 100
     */
    required int32 y = 2;
    optional string label = 3;
}

每个字段注释

每个信件注释

头条注释

首注"可选"

这个 @Option 后面必须有一个空间分隔的选项键和一个空间分隔的值.

// @Option primitiveTypesWithLimits false

message Point {

}

可能的选择是:

支持的验证框架

如果您想要在您的原始文件中添加额外的验证, 您可以使用以下其中之一 : 验证框架。 他们的规则翻译为 JSON Schema 验证关键词 解析.

• 原型验证 清单的验证不是 百分之百的支持.
• 缩写

这个 required 任意框架的规则将字段添加到 JSON Schema required 列表 : (buf.validate.field).required = true,或 (validate.rules).<type>.required = true 类型 message, (中文(简体) ), duration, (中文(简体) ), timestamp 财务报告和审定财务报表 any。 。 。 .

发展

这个项目用 TypeScript 写成,并同时构建一个ES模块(esm/)和一个共同JS(cjs/(中文(简体) ) 输出。 测试使用情况 欢乐 与快照式固定装置相对应 test/documents。 。 。 .

npm install          # install dependencies

npm run build        # build both esm/ and cjs/ (build:esm, build:cjs)
npm test             # run the Jest test suite with coverage
npm run lint         # run ESLint (use lint:fix to auto-fix)

来源布局 :

捐款

读取 捐款 了解贡献过程和AsyncAPI 行为守则欢迎提出问题和拉动请求.

许可证

阿帕奇 - 2.0