ts-proto 使用教程

1. 项目介绍

ts-proto 是一个将 .proto 文件转换为强类型、符合习惯的 TypeScript 文件的工具。它能够将 Protobuf 定义转换为 TypeScript 接口和类型，使得在前端项目中使用 Protobuf 变得更加简单和直观。ts-proto 的目标是生成符合 TypeScript/ES6 习惯的类型定义，并且尽可能地简化 Protobuf 在前端的使用。

2. 项目快速启动

安装

首先，你需要安装 ts-proto 和 protoc（Protobuf 编译器）：

npm install ts-proto

编译 Protobuf 文件

假设你有一个 person.proto 文件，内容如下：

syntax = "proto3";
package person;

message Person {
  string name = 1;
  uint64 age = 2;
}

你可以使用以下命令将其编译为 TypeScript 文件：

protoc --plugin=node_modules/ts-proto/protoc-gen-ts_proto --ts_proto_out=. person.proto

这将生成一个 person.ts 文件，包含 Person 接口和相关的编码/解码方法。

使用生成的 TypeScript 文件

在你的 TypeScript 项目中，你可以像使用普通 TypeScript 接口一样使用生成的类型：

import { Person } from './person';

const person: Person = {
  name: 'Alice',
  age: 30,
};

console.log(person);

3. 应用案例和最佳实践

案例1：使用 ts-proto 生成客户端和服务端类型

假设你有一个 gRPC 服务，定义了以下 .proto 文件：

syntax = "proto3";
package example;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

使用 ts-proto 生成 TypeScript 文件后，你可以在客户端和服务端共享这些类型定义，确保类型安全。

案例2：使用 ts-proto 生成 GraphQL 类型

如果你正在使用 GraphQL，你可以使用 ts-proto 生成的类型来定义 GraphQL 的输入和输出类型，确保前后端类型一致。

最佳实践

• 使用 ts-proto 生成类型：确保你的 Protobuf 定义和 TypeScript 类型保持同步。
• 避免手动修改生成的文件：生成的文件应该只由 ts-proto 工具更新，避免手动修改以防止冲突。
• 使用 ts-proto 的配置选项：根据项目需求，合理配置 ts-proto 的选项，如 esModuleInterop、useDate 等。

4. 典型生态项目

NestJS 支持

ts-proto 提供了对 NestJS 的集成支持，可以生成 NestJS 友好的类型和服务接口。你可以通过配置 nestJs=true 选项来启用 NestJS 支持。

gRPC-Web 支持

ts-proto 也支持 gRPC-Web，你可以通过配置 outputClientImpl=grpc-web 选项来生成 gRPC-Web 客户端实现。

其他生态项目

• nice-grpc：一个基于 ts-proto 的 gRPC 框架，提供了更简洁的 API 和更好的 TypeScript 支持。
• starpc：另一个基于 ts-proto 的 RPC 框架，提供了灵活的配置选项和强大的类型支持。

通过这些生态项目，你可以更方便地在 TypeScript 项目中集成 Protobuf 和 gRPC。