必须同时使用--go_out和--go-grpc_out生成代码，并嵌入UnimplementedXXXServer、显式调用RegisterXXXServer，否则服务无法注册导致UNIMPLEMENTED错误；需正确配置go_package路径、protoc插件版本及paths=source_relative选项。
能快速构建，但“快”不等于跳过契约定义和代码生成环节——protoc 命令跑不通、go_package 写错、插件没装对，这三处卡住 80% 的新手。
proto 文件必须写对 go_package 和 syntax
很多报错看似是生成失败，实际根子在 .proto 文件配置。常见现象：import "xxx.pb.go": no such file 或生成的代码里包路径混乱。
-
syntax = "proto3"必须显式声明，不能省略；proto2 已淘汰，混用会直接编译失败 -
option go_package要写成相对路径或模块路径，比如option go_package = "./api;api"（分号前是生成路径，后是包名），不能只写option go_package = "api" - 字段编号必须从 1 开始连续，中间跳号或重复会导致二进制兼容问题，后续升级难
- 推荐把所有
.proto放在api/目录下，避免生成时路径错乱
protoc 命令要带 --go-grpc_opt=paths=source_relative
默认生成的 import 路径可能指向绝对 GOPATH，导致 Go 模块找不到依赖。不加这个参数，go build 很大概率报 cannot find package。
- 正确命令示例：
protoc --go_out=. --go-grpc_out=. --go-grpc_opt=paths=source_relative api/user.proto - 必须确保已安装两个插件：
protoc-gen-go和protoc-gen-go-grpc，且都在$PATH中 - 验证插件是否可用：
protoc-gen-go --version和protoc-gen-go-grpc --version，输出应为版本号，不是 “command not found” - 如果用 Go modules，生成的
.pb.go文件顶部应有package api，而非package main或空包名
服务端注册必须嵌入 UnimplementedXXXServer
不嵌入 UnimplementedXXXServer，哪怕只实现一个方法，gRPC 启动时也会 panic：“method XXX not implemented”。这不是运行时报错，而是 RegisterXXXServer 内部检查触发的。
立即学习“go语言免费学习笔记（深入）”；
- 正确写法：
type UserServiceServer struct{ pb.UnimplementedUserServiceServer } - 不能只写
type UserServiceServer struct{}然后靠编译器推导接口实现——Go 不支持鸭子类型 - 如果后续新增 RPC 方法，未嵌入
Unimplemented的旧服务结构体会直接编译失败，而嵌入后可安全忽略新方法 - 拦截器（如日志、鉴权）要通过
grpc.UnaryInterceptor显式传入grpc.NewServer()，不能在 handler 里手动调用
客户端 Dial 必须处理 insecure 或 TLS 配置
本地调试时用 grpc.WithTransportCredentials(insecure.NewCredentials()) 是快捷方式，但上线必须换 TLS；反过来，如果服务启用了 TLS，客户端却用 insecure 连接，会报 connection closed 或 transport: authentication handshake failed。
- 开发阶段可临时用：
grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials())) - 生产环境必须加载证书：
creds, _ := credentials.NewClientTLSFromFile("ca.crt", "server.name")，再传给grpc.WithTransportCredentials(creds) - 超时控制别漏：客户端调用必须设
context.WithTimeout，否则服务端 hang 住时整个 goroutine 泄漏 - 连接复用是默认行为，不要每次调用都
Dial—— 应全局复用一个*grpc.ClientConn
真正拖慢进度的从来不是写业务逻辑，而是 protoc 输出路径不对、go_package 和模块路径不一致、或者客户端连上去就断连却没打日志——这些点不提前踩一遍，后面查半天不如重跑一次生成命令。
