必须显式调用RegisterXXXServer注册服务，否则客户端连得上但所有RPC返回UNIMPLEMENTED；需正确配置go_package路径、TLS选项，并监听0.0.0.0或127.0.0.1而非localhost。
用 protoc 生成 Go 代码是 gRPC 服务落地的必经环节，但默认生成的代码不能直接跑起来——缺少服务注册、传输层配置、拦截器等框架级支撑。别指望“自动生成”就等于“开箱即用”，得手动补全关键胶水代码。
protoc-gen-go-grpc 生成的 RegisterXXXServer 函数必须手动调用
新版 protoc-gen-go-grpc（v1.2+）不再生成 XXXServer 接口的默认实现，只生成注册函数（如 RegisterUserServiceServer）。这意味着你写完 UserServiceImpl 结构体后，必须显式把它注册到 gRPC server 实例上：
server := grpc.NewServer()-
pb.RegisterUserServiceServer(server, &UserServiceImpl{})—— 这行漏掉，客户端连得上但所有 RPC 调用都返回UNIMPLEMENTED - 如果用了拦截器或
grpc.Creds，必须在grpc.NewServer()里传入，不能靠生成代码自动注入
proto 文件中 syntax = "proto3" 和 go_package 必须严格匹配实际路径
生成代码的包路径由 go_package option 决定，不是文件所在目录。常见错误：
-
go_package写成"user"，但实际想放在github.com/yourorg/api/user下 → 生成的.pb.go文件会 import 错包，编译失败 -
go_package没带版本（如"user/v1"），后续升级 proto 时容易和旧版生成代码冲突 - 多个 proto 文件相互 import 时，
go_package值必须唯一，否则protoc会报duplicate symbol
gRPC Server 启动时监听地址不支持 localhost 绑定（仅 macOS/Linux）
用 lis, _ := net.Listen("tcp", "localhost:8080") 在 Linux 上会失败，报错 failed to listen: listen tcp localhost:8080: bind: cannot assign requested address。原因：localhost 解析为 IPv6 地址 ::1，但内核未启用 IPv6 或端口被占。
立即学习“go语言免费学习笔记（深入）”；
- 正确做法是用
"0.0.0.0:8080"或"127.0.0.1:8080" - 若需同时支持 IPv4/IPv6，用
"[::1]:8080"并确保系统开启 IPv6 - Docker 容器内部署时，必须用
0.0.0.0，否则 host 无法访问
客户端 Dial 失败常见于 TLS 配置与服务端不一致
服务端启用了 TLS（credentials.NewServerTLSFromCert），但客户端仍用 grpc.Dial("xxx:8080", grpc.WithInsecure())，会卡在连接阶段，日志只显示 transport: authentication handshake failed。
- 服务端开了 TLS，客户端必须配
grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(...)) - 若服务端用自签名证书，客户端需设
credentials.NewClientTLSFromCert(pool, "")，第二个参数留空表示跳过域名校验（生产环境禁用） - 开发期快速验证可用
grpc.WithTransportCredentials(insecure.NewCredentials())，但这是明文传输，不能用于测试以外场景
生成代码只是起点，真正让服务活起来的是那几行注册、监听、Dial 的胶水逻辑——它们不炫酷，但写错一个字符，整个链路就静默失败。尤其 go_package 路径和 TLS 配对，最容易在 CI 环境里突然暴露问题。
