gRPC接口定义必须用.proto文件，Go代码仅为生成结果；.proto是唯一权威来源，修改后须重新生成stub，否则报错或panic。
gRPC 接口定义必须用 .proto 文件，不是 Go 代码
gRPC 的接口契约和序列化协议由 Protocol Buffers 控制，.proto 文件是唯一权威来源。Go 代码只是生成结果，不能反向定义或绕过它。一旦改了 .proto，必须重新运行 protoc 生成 Go stub（*.pb.go），否则编译会报错或运行时 panic。
常见错误：直接在 Go struct 上加 gRPC 标签、试图用 interface{} 传参、或把 HTTP handler 风格的函数签名硬套进 service 定义 —— 这些都无效。
-
service块里只能定义rpc方法，每个方法必须明确指定request和responsemessage 类型 - 所有字段必须带数字标签（
1,2…），且不可跳号、不可重复；删除字段只能注释掉，不能重用旧编号 - 避免使用
optional（除非 Protobuf v3.12+ 且显式启用），默认字段就是可选的；v3 中optional int32 foo = 1;和int32 foo = 1;行为不同（后者无法区分“未设”和“设为 0”）
message 设计要面向演进，别照搬数据库表或 JSON 结构
Protobuf message 是数据契约，不是数据容器。设计时优先考虑「字段是否可能被下游忽略」「新增字段会不会破坏老客户端」「字段语义是否稳定」。
典型反例：message User { string name = 1; int64 created_at = 2; } —— created_at 类型用 int64 没法表达时区、精度、是否为 Unix timestamp；后续想改成 google.protobuf.Timestamp 就得 breaking change。
立即学习“go语言免费学习笔记（深入）”；
- 时间统一用
google.protobuf.Timestamp（需 import"google/protobuf/timestamp.proto"） - ID 字段不用
int64，用string（兼容 Snowflake、UUID、数据库自增等后端实现） - 枚举必须定义
UNKNOWN = 0，且 0 值保留不赋业务含义（Protobuf 默认值机制依赖它） - 嵌套 message 要克制：深层嵌套（>3 层）会让客户端解析变慢，也难做字段级权限控制
一元 / 流式 RPC 选型取决于调用语义，不是性能直觉
很多人以为 “streaming 更快”，其实不然。流式 RPC（stream 关键字）解决的是「单次请求响应无法承载完整语义」的问题，比如实时日志推送、长周期状态同步、分块上传 —— 不是为提速而用。
错误场景：用 rpc ListUsers(stream Empty) returns (stream User) 替代 rpc ListUsers(ListUsersRequest) returns (ListUsersResponse)。这会导致客户端无法获知总数、无法做分页参数校验、服务端无法预分配内存、gRPC Gateway 无法自动生成 REST 接口。
- 一元 RPC（unary）：适合「请求-响应」明确、有界、幂等的操作（如查询、创建、更新）
- Server streaming：适合「一个请求，多个响应」且响应顺序敏感（如搜索建议、监控指标推送）
- Client streaming：适合「多个请求，一个响应」且需要累积状态（如语音转文字、批量导入）
- Bidirectional streaming：仅当双方必须实时互发、无固定发起方（如协作编辑、游戏帧同步）
Go 侧生成代码后，RegisterXXXServer 和 NewXXXClient 必须配对使用
Protobuf 生成的 Go 代码中，RegisterXXXServer 函数注册的是实现了 XXXServer interface 的结构体，而 NewXXXClient 返回的是实现了 XXXClient interface 的 client 实例。二者类型完全独立，不能混用。
常见坑：client := pb.NewUserServiceClient(conn) 却试图调用 client.GetUser(context.Background(), &pb.GetUserRequest{Id: "1"})，但服务端实现的却是 func (*UserService) GetUser(...) —— 看似能跑，但若中间加了拦截器、认证逻辑或 gRPC-Gateway，就会静默失败或返回 500。
另一个易错点：忘记在 server 初始化时传入正确的 grpc.ServerOption，比如没开 grpc.UnaryInterceptor 却指望日志/鉴权生效。
package main
import (
"google.golang.org/grpc"
pb "your-project/api/user/v1"
)
func main() {
srv := grpc.NewServer(
grpc.UnaryInterceptor(authInterceptor),
grpc.StreamInterceptor(loggingInterceptor),
)
pb.RegisterUserServiceServer(srv, &userServer{}) // ← 必须是 *userServer，且实现 pb.UserServiceServer
}
字段命名、包路径、版本目录（如 api/user/v1）这些细节，在 .proto 里定死之后，就锁定了整个生态的兼容边界。改一个 package 名，Go import 路径、生成文件名、gRPC-Gateway 的 REST 路由前缀全得跟着动 —— 所以一开始就要想清楚层级和稳定性。
