简介
protobuf-jsonschema2 是一个将 Protocol Buffers（PB）转换为 JSON schema 的 npm 包。在前端领域，PB 可以进行跨语言的数据传输，而 JSON schema 可以方便实现前后端的数据校验及 API 文档生成。通过使用 protobuf-jsonschema2，我们可以将 PB 转换为 JSON schema，轻松地实现数据校验及 API 文档自动生成。
安装
使用 npm 安装 protobuf-jsonschema2 ：
npm install -g protobuf-jsonschema2
使用
1. 生成 JSON schema 文件：
通过使用以下命令可以将 PB 文件转换为 JSON schema 文件：
pbjs path/to/proto.proto | pbts -s > path/to/output.json
或者：
pbjs path/to/proto.proto -t json > path/to/output.json
2. 校验数据：
假设有一个名为 User 的 PB 结构（proto），我们可以在前端中使用 PB 来构建一个 User 对象，并将其发送到后端：
-- -------------------- ---- ------- ----- ---- - --- ------- ------- - -- --------- - ------- ---------- - ------------------- ------------- - --------- -------------- - ------- ------- ----- ---------------------- --
前端发送后，后端可以通过使用 protobuf.js 的 parse() 方法将数据解析为 PB 对象。同时，我们可以通过使用 protobuf-jsonschema2 的 validate() 方法，对数据进行校验：
-- -------------------- ---- ------- ----- --------- - ------------------------------------------ -- -- ---- ------ -------- ----- ------ - --------------------------------- ----- -------- - ------------------ -- ------------ ----- ---- - --------------------- ----- ------ - ---------------- ------ -- --------------- - ---------------------- -
3. 生成 API 文档：
通过使用 protobuf-jsonschema2，我们可以将 PB 转换为 OpenAPI（Swagger）格式的 JSON 文件，从而方便我们生成 API 文档。具体步骤如下：
将 PB 文件转换为 JSON 格式的 PB 文件：
pbjs path/to/proto.proto --target json > path/to/output.json
使用
protobuf-jsonschema2的convert()方法，将 PB 转换为 OpenAPI 格式的 JSON 文件：const converter = require('protobuf-jsonschema2').converter; // 将 JSON 格式的 PB 文件转换为 JSON schema 格式的 PB 文件 converter.convert('/path/to/output.json', '/path/to/output-schema.json', 'json', 'proto2'); // 将 JSON schema 格式的 PB 文件转换为 OpenAPI 格式的 JSON 文件 converter.convert('/path/to/output-schema.json', '/path/to/openapi.json', 'proto2', 'oas3', {title: 'API 文档'});执行以上命令后，会在
/path/to/目录下生成一个名为openapi.json的文件，其中即为转换后的 OpenAPI 格式的 JSON 数据。接下来，我们可以使用 Swagger 工具将其转化为各种格式的 API 文档：swagger-cli bundle --type=yaml --outfile=output.yaml openapi.json swagger-cli bundle --type=html --outfile=output.html openapi.json swagger-cli bundle --type=pdf --outfile=output.pdf openapi.json
示例代码
PB 文件
一个名为 User 的 PB 结构：
syntax = "proto2";
message User {
required int64 id = 1;
required string name = 2;
required string email = 3;
required string password = 4;
}转换为 JSON schema
将 PB 文件转换为 JSON schema 文件：
pbjs path/to/proto.proto --target json > path/to/output.json
生成的 output.json 文件内容：
-- -------------------- ---- -------
-
--------- -
------- -
--------- ---
--------- -
----- -
------- --------
----- -
--
------- -
------- ---------
----- -
--
-------- -
------- ---------
----- -
--
----------- -
------- ---------
----- -
-
-
-
-
-校验数据
在 Node.js 环境中使用 protobuf-jsonschema2 进行数据校验：
-- -------------------- ---- -------
----- -------- - ----------------------
----- --------- - ------------------------------------------
-- -- ---- ------ --------
----- ------ - -
--------- -
------- -
--------- ---
--------- -
----- -
------- --------
----- -
--
------- -
------- ---------
----- -
--
-------- -
------- ---------
----- -
--
----------- -
------- ---------
----- -
-
-
-
-
--
----- -------- - ------------------
-- ------------
----- ---- - -------------------------------------------------------------------
----- ------ - ---------------- ------
-- --------------- -
----------------------
-生成 API 文档
使用 protobuf-jsonschema2 将 PB 转换为 OpenAPI（Swagger）格式的 JSON 文件：
const converter = require('protobuf-jsonschema2').converter;
converter.convert('/path/to/output.json', '/path/to/output-schema.json', 'json', 'proto2');
converter.convert('/path/to/output-schema.json', '/path/to/openapi.json', 'proto2', 'oas3', {title: 'API 文档'});使用 Swagger 打开转换后的 openapi.json：
总结
protobuf-jsonschema2 是一个十分实用的 npm 包，它能够将 PB 转化为 JSON schema，使得前后端数据传输和 API 文档生成变得更加简单和便捷。同时，它还提供了对数据的校验功能，可以更好地保障数据的合法性和安全性。通过掌握 protobuf-jsonschema2 的使用方法，我们可以大大提高前端开发的效率，同时也能够提升整个系统的可维护性和安全性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60055d2d81e8991b448dae5b