@bufbuild/protobuf

import { create, fromBinary, toBinary, toJson } from "@bufbuild/protobuf";
import { type User, UserSchema } from "./gen/user/v1/user_pb";

// Messages are plain objects: pass fields in an initializer, or set them later.
const user: User = create(UserSchema, {
  id: "123",
  firstName: "Alice",
});
user.lastName = "Smith";

// Serialize to the Protobuf wire format, then parse it back.
const wire = toBinary(UserSchema, user);
user = fromBinary(UserSchema, wire);

console.log(user.firstName);           // Alice
console.log(toJson(UserSchema, user))  // {"id": "123", "firstName": "Alice", "lastName": "Smith"}

Protobuf 是构建 API 的最简单方式。我们建议将其与 Connect 配合使用，它能在所有主要编程语言中提供类型安全的客户端和服务器，并与 gRPC 无缝互操作。

以下是客户端的样子：

import { createClient } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-web";
import { UserService } from "./gen/user/v1/user_pb.js";

const client = createClient(
  UserService,
  createConnectTransport({
    baseUrl: "http://localhost:8080",
  })
);

const response = await client.getUser({ id: "123" });
console.log(response.user.firstName); // Alice

以及服务器：

import { ConnectRouter } from "@connectrpc/connect";
import { UserService } from "./gen/user/v1/user_pb.js";

export default (router: ConnectRouter) => {
  router.service(UserService, {
    async getUser(request) {
      const user = { id: request.id, firstName: "Alice", lastName: "Smith" };
      return { user };
    },
  });
}

使用 Fastify、Next.js、Express 等] 提供服务。

快速入门

// proto/user/v1/user.proto
syntax = "proto3";

package user.v1;

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
}

message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}

message User {
  string id = 1;
  string first_name = 2;
  string last_name = 3;
}

# buf.gen.yaml
version: v2
inputs:
  - directory: proto
plugins:
  - local: protoc-gen-es
    out: src/gen
    opt: target=ts

$ npm install @bufbuild/protobuf @connectrpc/connect
$ npm install --save-dev @bufbuild/protoc-gen-es @bufbuild/buf
$ npx buf generate

这就是全部——类型化消息和 Connect 存根现在位于 src/gen。

特性

• 生成纯 TypeScript
• 纯消息对象，无 getter/setter
• 反射、注册表和自定义选项
• 100% 符合官方 Protobuf 测试套件
• 标准的基于插件的生成，兼容 Buf CLI 以及 protoc
• 使用 @bufbuild/protoplugin 编写你自己的代码生成器
• 与 @connectrpc/connect 配合用于 RPC，与 @bufbuild/protovalidate 配合用于验证

对比

• google-protobuf 使用过时的 getter/setter API，并且需要第三方插件来支持 TypeScript。
• protobuf.js 是一个复杂的库，包含三个运行时和三个代码生成目标。它需要额外配置才能完全符合规范，并且在某些配置下不具备类型安全。

文档

• protobufes.com：关于代码生成、消息、JSON、反射、注册表、扩展和迁移的完整指南。
• 代码示例：一个在应用代码中使用生成的 Protobuf 类型的工作示例。
• 插件示例：生成 Twirp 客户端的示例插件。
• 一致性测试结果：公共运行器和对比表。
• 包大小对比：与 Google 生成器的并排数据。
• connect-es：用于 Connect、gRPC 和 gRPC-Web 的配套 RPC 库。

包

• @bufbuild/protobuf: 包含消息 API、常用类型、JSON、反射、注册表和扩展的运行时库。
• @bufbuild/protoc-gen-es: 用于生成 TypeScript 和 JavaScript 的标准 Protobuf 插件。
• @bufbuild/protoplugin: 用于使用 TypeScript 编写自定义 Protobuf 插件的框架。

Compatibility

• 支持过去 2.5 年内的 Baseline web browsers。
• Node.js: 支持所有受维护的版本。
• Deno: 支持最新的 LTS 版本。
• Bun: 支持最新的 v1 版本。
• TypeScript: 使用默认编译器设置时，支持 2 年以内的版本。

Copyright

编码和解码 varint 的代码 版权归 Google Inc. 所有（2008 年），采用 BSD-3-Clause 许可证。 其他所有文件均采用 Apache-2.0 许可证，请参阅 LICENSE。