Protobuf

这是为xScript提供的Protocol Buffers支持模块，允许在JavaScript中加载.proto文件，将对象编码为protobuf字节，以及将protobuf字节解码为对象。

功能特性

📄 加载和解析.proto文件（支持proto2和proto3语法）

🔄 将JavaScript对象编码为protobuf二进制格式

📦 将protobuf二进制数据解码为JavaScript对象

🎯 支持多种protobuf数据类型

🔍 查询已加载的消息类型

🔢 支持enum枚举类型

🗺️ 支持map字段（map <K,V>）

📥 支持import导入其他proto文件

🏷️ 支持proto2的required/optional/repeated标签

💾 命名缓存机制，支持多个独立的proto文件加载实例

🔒 线程安全，支持并发访问

安装

该模块已集成到xScript中，无需额外安装。

基础使用

1. 导入模块

2. 加载proto文件（命名缓存）

3. 编码对象为字节

4. 解码字节为对象

5. 获取消息类型列表

6. 命名缓存管理

Proto文件示例

完整示例

高级特性

Proto2语法支持

模块完全支持proto2语法，包括required/optional/repeated字段标签。

Proto2示例:

使用示例:

Enum枚举类型

支持enum枚举类型的定义和使用。

Proto定义:

使用示例:

Map字段支持

支持map <K,V>类型的字段，可以存储键值对数据。

Proto定义:

使用示例:

支持的Map键类型:

整数类型: int32, int64, uint32, uint64, sint32, sint64, fixed32, fixed64, sfixed32, sfixed64

bool

string

支持的Map值类型:

所有基本类型和消息类型

Import导入支持

支持import语句导入其他proto文件，实现模块化的proto文件组织。

公共定义文件 (common.proto):

主文件 (user.proto):

使用示例:

导入特性:

自动递归加载所有import的文件

支持相对路径和绝对路径

导入的类型可以直接使用包名.类型名访问

避免重复加载相同的文件

综合示例（Proto2 + Enum + Map + Import）

test_common.proto:

test_advanced.proto:

使用示例:

支持的数据类型

基本类型

double, float

int32, int64

uint32, uint64

sint32, sint64

fixed32, fixed64

sfixed32, sfixed64

bool

string

bytes

复杂类型

message - 嵌套消息

enum - 枚举类型

repeated - 数组字段

optional - 可选字段（proto2）

required - 必填字段（proto2）

map<K,V> - 映射字段

API参考

protobuf.load(name, filePath)

加载并解析proto文件到命名缓存。如果指定名称的缓存已存在，直接返回缓存的loader，不会重复加载文件。

参数:

name (string): 缓存名称

filePath (string): proto文件的路径

返回:

Array <string>: 消息类型名称列表

示例:

protobuf.encode(messageName, object)

将JavaScript对象编码为protobuf字节。

参数:

messageName (string): 消息类型名称（包含包名，如'example.User'）

object (Object): 要编码的JavaScript对象

返回:

Buffer: protobuf编码的字节数据

示例:

protobuf.decode(messageName, bytes)

将protobuf字节解码为JavaScript对象。

参数:

messageName (string): 消息类型名称

bytes (Buffer|Array): protobuf编码的字节数据

返回:

Object: 解码后的JavaScript对象

示例:

protobuf.getMessageTypes()

获取所有命名缓存中已加载的消息类型列表。

返回:

Array <string>: 消息类型名称列表

示例:

protobuf.getLoaderStats()

获取命名缓存统计信息。

返回:

Object: 包含loaders（实例数）、messages（总消息数）、names（缓存名称列表）

示例:

protobuf.clearMessages(name)

清除指定命名缓存中的所有消息。

参数:

name (string): 缓存名称

示例:

protobuf.removeLoader(name)

移除指定的命名缓存。

参数:

name (string): 缓存名称

示例:

注意事项

Proto文件格式: 支持proto2和proto3语法

消息类型名称: 使用完整的类型名称，包括包名（如'package.MessageName'）

字节数据: encode返回的是Buffer对象，可以与其他模块互操作

错误处理: 所有方法在失败时会抛出异常，请使用try-catch捕获

Import路径: import路径相对于被导入文件所在的目录

Enum值: 使用整数值表示枚举，不支持枚举名称字符串

Map类型: Map的键必须是基本类型（整数、布尔、字符串）

并发安全: 所有操作都是线程安全的，可以在多个goroutine中并发使用

错误处理示例

常见使用场景

嵌套消息

数组字段

多文件项目组织

proto/
  ├── common/
  │   ├── types.proto
  │   └── enums.proto
  ├── user/
  │   └── user.proto
  └── order/
      └── order.proto

性能建议

缓存复用: 尽量重用已加载的proto文件，避免重复加载

命名缓存: 使用不同的缓存名称管理不同的proto文件集合

批量操作: 对于大量数据，建议使用批量编码

Buffer处理: Buffer数据可以直接用于网络传输或文件存储

并发访问: 模块内部使用读写锁保护，支持安全的并发访问

protobuf

Protobuf#

功能特性#

安装#

基础使用#

1. 导入模块#

2. 加载proto文件（命名缓存）#

3. 编码对象为字节#

4. 解码字节为对象#

5. 获取消息类型列表#

6. 命名缓存管理#

Proto文件示例#

完整示例#

高级特性#

Proto2语法支持#

Enum枚举类型#

Map字段支持#

Import导入支持#

综合示例（Proto2 + Enum + Map + Import）#

支持的数据类型#

基本类型#

复杂类型#

API参考#

protobuf.load(name, filePath)#

protobuf.encode(messageName, object)#

protobuf.decode(messageName, bytes)#

protobuf.getMessageTypes()#

protobuf.getLoaderStats()#

protobuf.clearMessages(name)#

protobuf.removeLoader(name)#

注意事项#

错误处理示例#

常见使用场景#

嵌套消息#

数组字段#

多文件项目组织#

性能建议#

相关模块#

Protobuf

功能特性

安装

基础使用

1. 导入模块

2. 加载proto文件（命名缓存）

3. 编码对象为字节

4. 解码字节为对象

5. 获取消息类型列表

6. 命名缓存管理

Proto文件示例

完整示例

高级特性

Proto2语法支持

Enum枚举类型

Map字段支持

Import导入支持

综合示例（Proto2 + Enum + Map + Import）

支持的数据类型

基本类型

复杂类型

API参考

protobuf.load(name, filePath)

protobuf.encode(messageName, object)

protobuf.decode(messageName, bytes)

protobuf.getMessageTypes()

protobuf.getLoaderStats()

protobuf.clearMessages(name)

protobuf.removeLoader(name)

注意事项

错误处理示例

常见使用场景

嵌套消息

数组字段

多文件项目组织

性能建议

相关模块