protobufjs/protobuf.js - TS 中文文档

Protocol Buffersare a language-neutral, platform-neutral, extensible way of serializing structured data for use in communications protocols, data storage, and more, originally designed at Google (see ).

protobuf.jsis a pure JavaScript implementation with TypeScript support for node.js and the browser. It's easy to use, blazingly fast and works out of the box with .proto files!

Installation How to include protobuf.js in your project.

Usage A brief introduction to using the toolset.

Valid Message

Toolset

Examples A few examples to get you started.

Using .proto files

Using JSON descriptors

Using reflection only

Using custom classes

Using services

Usage with TypeScript

Additional documentation A list of available documentation resources.

Performance A few internals and a benchmark on performance.

Compatibility Notes on compatibility regarding browsers and optional libraries.

Building How to build the library and its components yourself.

Installation

node.js

``` sh
$> npm install protobufjs [--save --save-prefix=~]
```

``` js
var protobuf = require("protobufjs");
```

The command line utility lives in the protobufjs-cli package and must be installed separately:

``` sh
$> npm install protobufjs-cli [--save --save-prefix=~]
```

Notethat this library's versioning scheme is not semver-compatible for historical reasons. For guaranteed backward compatibility, always depend on ~6.A.B instead of ^6.A.B (hence the --save-prefix above).

Browsers

Development:

``` sh
<script src="//cdn.jsdelivr.net/npm/protobufjs@7.X.X/dist/protobuf.js"></script>
```

Production:

``` sh
<script src="//cdn.jsdelivr.net/npm/protobufjs@7.X.X/dist/protobuf.min.js"></script>
```

Rememberto replace the version tag with the exact release your project depends upon.

The library supports CommonJS and AMD loaders and also exports globally as protobuf.

Distributions

Where bundle size is a factor, there are additional stripped-down versions of the [full library][dist-full] (~19kb gzipped) available that exclude certain functionality:

When working with JSON descriptors (i.e. generated by pbjs ) and/or reflection only, see the [light library][dist-light] (~16kb gzipped) that excludes the parser. CommonJS entry point is:

``` js
var protobuf = require("protobufjs/light");
```

When working with statically generated code only, see the [minimal library][dist-minimal] (~6.5kb gzipped) that also excludes reflection. CommonJS entry point is:

``` js
var protobuf = require("protobufjs/minimal");
```

Distribution	Location
:---	:---
Full	https://cdn.jsdelivr.net/npm/protobufjs/dist/
Light	https://cdn.jsdelivr.net/npm/protobufjs/dist/light/
Minimal	https://cdn.jsdelivr.net/npm/protobufjs/dist/minimal/

Usage

Because JavaScript is a dynamically typed language, protobuf.js introduces the concept of a valid messagein order to provide the best possible performance (and, as a side product, proper typings):

Valid message

A valid message is an object (1) not missing any required fields and (2) exclusively composed of JS types understood by the wire format writer.

There are two possible types of valid messages and the encoder is able to work with both of these for convenience:

Message instances(explicit instances of message classes with default values on their prototype) always (have to) satisfy the requirements of a valid message by design and

Plain JavaScript objectsthat just so happen to be composed in a way satisfying the requirements of a valid message as well.

In a nutshell, the wire format writer understands the following types:

Field type	Expected JS type (create, encode)	Conversion (fromObject)
:---	:---	:---
s-/u-/int32s-/fixed32	number (32 bit integer)	`value
s-/u-/int64s-/fixed64	Long-like (optimal)number (53 bit integer)	Long.fromValue(value) with long.jsparseInt(value, 10) otherwise
floatdouble	number	Number(value)
bool	boolean	Boolean(value)
string	string	String(value)
bytes	Uint8Array (optimal)Buffer (optimal under node)Array.<number> (8 bit integers)	base64.decode(value) if a stringObject with non-zero .length is assumed to be buffer-like
enum	number (32 bit integer)	Looks up the numeric id if a string
message	Valid message	Message.fromObject(value)

Explicit undefined and null are considered as not set if the field is optional.

Repeated fields are Array.<T>.

Map fields are Object.<string,T> with the key being the string representation of the respective value or an 8 characters long binary hash string for Long -likes.

Types marked as optimalprovide the best performance because no conversion step (i.e. number to low and high bits or base64 string to buffer) is required.

Toolset

With that in mind and again for performance reasons, each message class provides a distinct set of methods with each method doing just one thing. This avoids unnecessary assertions / redundant operations where performance is a concern but also forces a user to perform verification (of plain JavaScript objects that mightjust so happen to be a valid message) explicitly where necessary - for example when dealing with user input.

Notethat Message below refers to any message class.

Message.verify(message: Object ): null|string verifies that a plain JavaScript objectsatisfies the requirements of a valid message and thus can be encoded without issues. Instead of throwing, it returns the error message as a string, if any.

``` js
var payload = "invalid (not an object)";
var err = AwesomeMessage.verify(payload);
if (err)
throw Error(err);
```

Message.encode(message: Message|Object [, writer: Writer ]): Writer encodes a message instanceor valid plain JavaScript object. This method does not implicitly verify the message and it's up to the user to make sure that the payload is a valid message.

``` js
var buffer = AwesomeMessage.encode(message).finish();
```

Message.encodeDelimited(message: Message|Object [, writer: Writer ]): Writer works like Message.encode but additionally prepends the length of the message as a varint.

Message.decode(reader: Reader|Uint8Array ): Message decodes a buffer to a message instance. If required fields are missing, it throws a util.ProtocolError with an instance property set to the so far decoded message. If the wire format is invalid, it throws an Error.

``` js
try {
var decodedMessage = AwesomeMessage.decode(buffer);
} catch (e) {
if (e instanceof protobuf.util.ProtocolError) {
// e.instance holds the so far decoded message with missing required fields
} else {
// wire format is invalid
}
}
```

Message.decodeDelimited(reader: Reader|Uint8Array ): Message works like Message.decode but additionally reads the length of the message prepended as a varint.

Message.create(properties: Object ): Message creates a new message instancefrom a set of properties that satisfy the requirements of a valid message. Where applicable, it is recommended to prefer Message.create over Message.fromObject because it doesn't perform possibly redundant conversion.

``` js
var message = AwesomeMessage.create({ awesomeField: "AwesomeString" });
```

Message.fromObject(object: Object ): Message converts any non-valid plain JavaScript objectto a message instanceusing the conversion steps outlined within the table above.

``` js
var message = AwesomeMessage.fromObject({ awesomeField: 42 });
// converts awesomeField to a string
```

Message.toObject(message: Message [, options: ConversionOptions ]): Object converts a message instanceto an arbitrary plain JavaScript objectfor interoperability with other libraries or storage. The resulting plain JavaScript object mightstill satisfy the requirements of a valid message depending on the actual conversion options specified, but most of the time it does not.

``` js
var object = AwesomeMessage.toObject(message, {
enums: String, // enums as string names
longs: String, // longs as strings (requires long.js)
bytes: String, // bytes as base64 encoded strings
defaults: true, // includes default values
arrays: true, // populates empty arrays (repeated fields) even if defaults=false
objects: true, // populates empty objects (map fields) even if defaults=false
oneofs: true // includes virtual oneof fields set to the present field's name
});
```

For reference, the following diagram aims to display relationships between the different methods and the concept of a valid message:

In other words: verify indicates that calling create or encode directly on the plain object will [result in a valid message respectively] succeed. fromObject, on the other hand, does conversion from a broader range of plain objects to create valid messages. (ref )

Examples

Using .proto files

It is possible to load existing .proto files using the full library, which parses and compiles the definitions to ready to use (reflection-based) message classes:

``` proto
// awesome.proto
package awesomepackage;
syntax = "proto3";
message AwesomeMessage {
string awesome_field = 1; // becomes awesomeField
}
```

``` js
protobuf.load("awesome.proto", function(err, root) {
if (err)
throw err;
// Obtain a message type
var AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
// Exemplary payload
var payload = { awesomeField: "AwesomeString" };
// Verify the payload if necessary (i.e. when possibly incomplete or invalid)
var errMsg = AwesomeMessage.verify(payload);
if (errMsg)
throw Error(errMsg);
// Create a new message
var message = AwesomeMessage.create(payload); // or use .fromObject if conversion is necessary
// Encode a message to an Uint8Array (browser) or Buffer (node)
var buffer = AwesomeMessage.encode(message).finish();
// ... do something with buffer
// Decode an Uint8Array (browser) or Buffer (node) to a message
var message = AwesomeMessage.decode(buffer);
// ... do something with message
// If the application uses length-delimited buffers, there is also encodeDelimited and decodeDelimited.
// Maybe convert the message back to a plain object
var object = AwesomeMessage.toObject(message, {
longs: String,
enums: String,
bytes: String,
// see ConversionOptions
});
});
```

Additionally, promise syntax can be used by omitting the callback, if preferred:

``` js
protobuf.load("awesome.proto")
.then(function(root) {
...
});
```

Using JSON descriptors

The library utilizes JSON descriptors that are equivalent to a .proto definition. For example, the following is identical to the .proto definition seen above:

``` json
// awesome.json
{
"nested": {
"awesomepackage": {
"nested": {
"AwesomeMessage": {
"fields": {
"awesomeField": {
"type": "string",
"id": 1
}
}
}
}
}
}
}
```

JSON descriptors closely resemble the internal reflection structure:

Type (T)	Extends	Type-specific properties
:---	:---	:---
ReflectionObject		options
Namespace	ReflectionObject	nested
Root	Namespace	nested
Type	Namespace	fields
Enum	ReflectionObject	values
Field	ReflectionObject	rule, type, id
MapField	Field	keyType
OneOf	ReflectionObject	oneof (array of field names)
Service	Namespace	methods
Method	ReflectionObject	type, requestType, responseType, requestStream, responseStream

Bold propertiesare required. Italic typesare abstract.

T.fromJSON(name, json) creates the respective reflection object from a JSON descriptor

T#toJSON() creates a JSON descriptor from the respective reflection object (its name is used as the key within the parent)

Exclusively using JSON descriptors instead of .proto files enables the use of just the light library (the parser isn't required in this case).

A JSON descriptor can either be loaded the usual way:

``` js
protobuf.load("awesome.json", function(err, root) {
if (err) throw err;
// Continue at "Obtain a message type" above
});
```

Or it can be loaded inline:

``` js
var jsonDescriptor = require("./awesome.json"); // exemplary for node
var root = protobuf.Root.fromJSON(jsonDescriptor);
// Continue at "Obtain a message type" above
```

Using reflection only

Both the full and the light library include full reflection support. One could, for example, define the .proto definitions seen in the examples above using just reflection:

``` js
...
var Root = protobuf.Root,
Type = protobuf.Type,
Field = protobuf.Field;
var AwesomeMessage = new Type("AwesomeMessage").add(new Field("awesomeField", 1, "string"));
var root = new Root().define("awesomepackage").add(AwesomeMessage);
// Continue at "Create a new message" above
...
```

Detailed information on the reflection structure is available within the API documentation.

Using custom classes

Message classes can also be extended with custom functionality and it is also possible to register a custom constructor with a reflected message type:

``` js
...
// Define a custom constructor
function AwesomeMessage(properties) {
// custom initialization code
...
}
// Register the custom constructor with its reflected type (*)
root.lookupType("awesomepackage.AwesomeMessage").ctor = AwesomeMessage;
// Define custom functionality
AwesomeMessage.customStaticMethod = function() { ... };
AwesomeMessage.prototype.customInstanceMethod = function() { ... };
// Continue at "Create a new message" above
```

(*) Besides referencing its reflected type through AwesomeMessage.$type and AwesomeMesage#$type, the respective custom class is automatically populated with:

AwesomeMessage.create

AwesomeMessage.encode and AwesomeMessage.encodeDelimited

AwesomeMessage.decode and AwesomeMessage.decodeDelimited

AwesomeMessage.verify

AwesomeMessage.fromObject, AwesomeMessage.toObject and AwesomeMessage#toJSON

Afterwards, decoded messages of this type are instanceof AwesomeMessage.

Alternatively, it is also possible to reuse and extend the internal constructor if custom initialization code is not required:

``` js
...
// Reuse the internal constructor
var AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage").ctor;
// Define custom functionality
AwesomeMessage.customStaticMethod = function() { ... };
AwesomeMessage.prototype.customInstanceMethod = function() { ... };
// Continue at "Create a new m

Contents

Installation

node.js

Browsers

Distributions

Usage

Valid message

Toolset

Examples

Using .proto files

Using JSON descriptors

Using reflection only

Using custom classes