protobuf-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Protocol Buffers Design Skill

Protocol Buffers 设计技能

When to Use This Skill

何时使用本技能

Use this skill when:

Designing gRPC services - Protocol Buffers (proto3) for typed service contracts
Schema definition - Messages, enums, services, streaming patterns
Implementing in C# - gRPC with ASP.NET Core
Schema evolution - Backward/forward compatibility, versioning

在以下场景使用本技能：

设计gRPC服务 - 使用Protocol Buffers（proto3）定义类型化服务契约
Schema定义 - 消息、枚举、服务、流式模式
C#实现 - 结合ASP.NET Core的gRPC开发
Schema演进 - 向前/向后兼容性、版本控制

MANDATORY: Documentation-First Approach

强制要求：文档优先方法

Before creating protobuf definitions:

Invoke
docs-management
skill for API contract patterns
Verify proto3 syntax via MCP servers (context7 for latest spec)
Base all guidance on Google's Protocol Buffers documentation

创建protobuf定义前：

调用
docs-management
技能获取API契约模式
通过MCP服务器验证proto3语法（使用context7获取最新规范）
所有指导均基于Google的Protocol Buffers官方文档

Why Protocol Buffers?

为什么选择Protocol Buffers？

Benefit	Description
Efficient	Binary format, 3-10x smaller than JSON
Typed	Strong typing with code generation
Versioned	Built-in backward/forward compatibility
Cross-Language	Supports C#, Java, Python, Go, etc.
gRPC Integration	Native service definition for gRPC

优势	描述
高效性	二进制格式，体积比JSON小3-10倍
强类型	支持强类型并可生成代码
可版本化	内置向前/向后兼容性
跨语言	支持C#、Java、Python、Go等多种语言
gRPC集成	为gRPC提供原生服务定义

Proto3 Structure Overview

Proto3结构概述

protobuf

syntax = "proto3";

package ecommerce.orders.v1;

option csharp_namespace = "ECommerce.Orders.V1";

import "google/protobuf/timestamp.proto";

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
  rpc WatchStatus(WatchRequest) returns (stream StatusUpdate);
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_DRAFT = 1;
  ORDER_STATUS_SUBMITTED = 2;
}

message Order {
  string id = 1;
  string customer_id = 2;
  OrderStatus status = 3;
  google.protobuf.Timestamp created_at = 4;
}

For complete template: See proto-syntax.md

protobuf

syntax = "proto3";

package ecommerce.orders.v1;

option csharp_namespace = "ECommerce.Orders.V1";

import "google/protobuf/timestamp.proto";

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
  rpc WatchStatus(WatchRequest) returns (stream StatusUpdate);
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_DRAFT = 1;
  ORDER_STATUS_SUBMITTED = 2;
}

message Order {
  string id = 1;
  string customer_id = 2;
  OrderStatus status = 3;
  google.protobuf.Timestamp created_at = 4;
}

完整模板：请查看proto-syntax.md

Quick Reference

快速参考

gRPC RPC Types

gRPC RPC类型

Pattern	Syntax	Use Case
Unary	`rpc Get(Req) returns (Resp)`	Simple CRUD
Server Stream	`rpc List(Req) returns (stream Resp)`	Large results, updates
Client Stream	`rpc Upload(stream Req) returns (Resp)`	Batch uploads
Bidirectional	`rpc Chat(stream Req) returns (stream Resp)`	Real-time sync

For streaming patterns: See grpc-patterns.md

模式	语法	使用场景
一元RPC	`rpc Get(Req) returns (Resp)`	简单CRUD操作
服务器流式RPC	`rpc List(Req) returns (stream Resp)`	大数据结果、实时更新
客户端流式RPC	`rpc Upload(stream Req) returns (Resp)`	批量上传
双向流式RPC	`rpc Chat(stream Req) returns (stream Resp)`	实时同步

流式模式详情：请查看grpc-patterns.md

Naming Conventions

命名规范

Element	Convention	Example
Package	lowercase.dots.version	`ecommerce.orders.v1`
Service	PascalCase + Service	`OrderService`
RPC	PascalCase verb	`CreateOrder`
Message	PascalCase	`OrderCreatedEvent`
Field	snake_case	`customer_id`
Enum	SCREAMING_PREFIX_VALUE	`ORDER_STATUS_DRAFT`

元素	规范	示例
包名	小写+点+版本号	`ecommerce.orders.v1`
服务	大驼峰+Service	`OrderService`
RPC方法	大驼峰动词	`CreateOrder`
消息	大驼峰	`OrderCreatedEvent`
字段	小蛇形	`customer_id`
枚举	大写下划线前缀值	`ORDER_STATUS_DRAFT`

Workflow

工作流程

Identify Resources: What entities does the service manage?
Define Messages: Data structures for each resource
Design Service Methods: CRUD operations, queries, commands
Add Streaming: Where real-time updates needed
Document: Comments for all messages and fields
Lint: Use Buf or protolint for consistency
Version: Plan for schema evolution
Generate: Create client/server code

识别资源：服务需要管理哪些实体？
定义消息：为每个资源设计数据结构
设计服务方法：CRUD操作、查询、命令
添加流式功能：在需要实时更新的场景中使用
文档编写：为所有消息和字段添加注释
代码检查：使用Buf或protolint保证一致性
版本规划：为Schema演进制定计划
代码生成：创建客户端/服务器代码

References

参考资料

Load on-demand based on need:

Reference	Load When
proto-syntax.md	Creating proto definitions, well-known types, advanced patterns
grpc-patterns.md	Designing streaming services (server, client, bidirectional)
csharp-implementation.md	Implementing gRPC in .NET/C# with ASP.NET Core
schema-evolution.md	Planning schema changes, Buf CLI, versioning

根据需求按需加载：

参考资料	加载场景
proto-syntax.md	创建proto定义、知名类型、高级模式
grpc-patterns.md	设计流式服务（服务器、客户端、双向）
csharp-implementation.md	在.NET/C#中结合ASP.NET Core实现gRPC
schema-evolution.md	规划Schema变更、Buf CLI、版本控制

Related Skills (Cross-Plugin)

Phase	Skill	Plugin	Purpose
DESIGN	`protobuf-design` (this skill)	formal-specification	Architecture research, pattern selection
AUTHORING	N/A	spec-driven-development	Gap: `protobuf-authoring` not yet created

阶段	技能	插件	用途
设计	`protobuf-design` （本技能）	formal-specification	架构研究、模式选择
编写	无	spec-driven-development	缺口： `protobuf-authoring` 技能尚未创建

External References

外部参考

Protocol Buffers Documentation - Official Google documentation
gRPC Documentation - Official gRPC guides
Buf CLI - Modern protobuf tooling
Google API Design Guide - Resource-oriented API patterns
gRPC for .NET - ASP.NET Core gRPC docs

Protocol Buffers官方文档 - Google官方文档
gRPC官方文档 - gRPC官方指南
Buf CLI - 现代protobuf工具
Google API设计指南 - 面向资源的API模式
.NET gRPC指南 - ASP.NET Core gRPC文档

MCP Research

MCP研究

For current protobuf patterns and tools:

text

perplexity: "Protocol Buffers proto3" "gRPC service design patterns"
context7: "grpc" (for official documentation)
microsoft-learn: "gRPC ASP.NET Core" (for .NET implementation)

如需获取当前protobuf模式和工具信息：