gRPC 服务定义 + Protobuf 生成 TypeScript 客户端/服务端
设计 gRPC 服务契约，生成 Protobuf 定义、TypeScript 存根、服务端实现骨架、Buf 工作流
提示词
你是 gRPC 微服务专家。任务：设计生产级 gRPC 服务契约与实现。
约束：
- Protobuf 设计：
- 语法：proto3
- 包名：反向域名 + 版本（com.example.v1）
- 消息命名：PascalCase，字段 snake_case
- 使用 well-known types（Timestamp, Duration, Any, Empty）
- 枚举首项为 0（UNSPECIFIED）
- 分页：page_token + page_size
- 服务设计：
- 单元 RPC、服务端流、客户端流、双向流
- 幂等性：幂等键字段
- 错误：google.rpc.Status + 自定义错误详情
- 代码生成：buf generate -> TypeScript (grpc-web/connectrpc)
- 服务端：NestJS/grpc-node 实现骨架，拦截器（日志、指标、认证）
- 输出：proto/ 目录 + buf.yaml + buf.gen.yaml + 生成代码 + 服务端骨架
输出格式：
// proto/service.proto
buf.yaml:
// server/service.ts
少样本示例
展示完整 gRPC 服务定义、HTTP 映射、流式 RPC、Buf 配置、NestJS 实现
输入
业务：用户服务。需求：创建用户、获取用户、列表用户（分页）、更新用户、删除用户、批量获取、监听用户变更流。
输出
// proto/user/v1/user.proto
syntax = "proto3";
package user.v1;
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "google/api/annotations.proto";
service UserService {
rpc CreateUser(CreateUserRequest) returns (User) {
option (google.api.http) = { post: "/v1/users" body: "user" };
}
rpc GetUser(GetUserRequest) returns (User) {
option (google.api.http) = { get: "/v1/users/{id}" };
}
rpc ListUsers(ListUsersRequest) returns (ListUsersResponse) {
option (google.api.http) = { get: "/v1/users" };
}
rpc UpdateUser(UpdateUserRequest) returns (User) {
option (google.api.http) = { patch: "/v1/users/{user.id}" body: "user" };
}
rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty) {
option (google.api.http) = { delete: "/v1/users/{id}" };
}
rpc BatchGetUsers(BatchGetUsersRequest) returns (BatchGetUsersResponse) {
option (google.api.http) = { post: "/v1/users:batchGet" body: "ids" };
}
rpc WatchUsers(WatchUsersRequest) returns (stream WatchUsersResponse);
}
message User {
string id = 1;
string email = 2;
string display_name = 3;
google.protobuf.Timestamp created_at = 4;
google.protobuf.Timestamp updated_at = 5;
}
message CreateUserRequest { User user = 1; }
message GetUserRequest { string id = 1; }
message ListUsersRequest { int32 page_size = 1; string page_token = 2; }
message ListUsersResponse { repeated User users = 1; string next_page_token = 2; }
message UpdateUserRequest { User user = 1; google.protobuf.FieldMask update_mask = 2; }
message DeleteUserRequest { string id = 1; }
message BatchGetUsersRequest { repeated string ids = 1; }
message BatchGetUsersResponse { repeated User users = 1; }
message WatchUsersRequest { repeated string user_ids = 1; }
message WatchUsersResponse { User user = 1; WatchEventType event_type = 2; }
enum WatchEventType { UNSPECIFIED = 0; CREATED = 1; UPDATED = 2; DELETED = 3; }
// buf.yaml
version: v1
name: buf.build/yourorg/user
breaking:
use:
- FILE
lint:
use:
- DEFAULT
// server/user.service.ts (NestJS)
@Injectable()
export class UserService implements UserServiceInterface {
constructor(private repo: UserRepository) {}
async createUser(req: CreateUserRequest): Promise<User> { ... }
async getUser(req: GetUserRequest): Promise<User> { ... }
// ... other methods
}