写.proto文件需以syntax = "proto3";开头，字段用snake_case，service方法的请求/响应类型必须是已定义的message，map和repeated需确保proto3支持。
怎么写 .proto 文件才不会被生成器报错
Protobuf 文件是 gRPC 的契约起点，写错一个字段类型或漏掉 syntax = "proto3"; 就会卡在代码生成阶段。常见错误是把 int 当成合法类型（实际得用 int32 或 int64），或者在 service 定义里用了未声明的 message 类型。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 开头必须写
syntax = "proto3";，不加这行，protoc默认按 proto2 解析，后续 Python 生成代码会缺__slots__、字段默认值行为也不一致 - message 字段名用
snake_case，gRPC Python 生成器会自动转成snake_case属性名（不是camelCase），别强行模仿 JSON key 风格 - service 方法的请求/响应类型必须是已定义的 message，不能是内置类型如
string或int32—— 这点和 REST 不同，gRPC 强制封装 - 如果要用 map 或 repeated，确保 proto3 支持：比如
map<string int32> metadata = 1;</string>是合法的，但 proto2 不支持 map 关键字
protoc 命令生成 Python 代码时为什么总少文件
执行 protoc 后只生成了 *_pb2.py，没看到 *_pb2_grpc.py，说明插件没启用或路径没配对。Python 的 gRPC 代码分两层：底层序列化（_pb2）和上层 RPC stub（_pb2_grpc），后者依赖 grpcio-tools 提供的插件。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 必须显式加
--python_out=.和--grpc_python_out=.两个输出参数，缺一不可 - 确保已安装
grpcio-tools（不是只装grpcio），否则--grpc_python_out会被忽略且无提示 - 路径要对齐：如果
.proto在proto/hello.proto，运行命令得在proto/外层，并用--proto_path=proto/告诉编译器去哪找依赖文件 - 生成后检查文件内容：若
*_pb2_grpc.py里没有class GreeterStub或GreeterServicer，大概率是.proto里 service 块写法有误，比如少了rpc关键字
Python server 启动时报 AttributeError: 'NoneType' object has no attribute 'add_insecure_port'
这是典型的 server 实例没正确创建就调了方法。常见于复制示例时漏掉 server = grpc.server(...)，或把 add_insecure_port 写在 server = None 的分支里。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- server 创建必须用
grpc.server(futures.ThreadPoolExecutor(max_workers=10))，不能直接grpc.server()（会返回 None） -
add_insecure_port('localhost:50051')必须在add_<em>servicer</em>to_server()之后、server.start()之前调用，顺序错会导致端口绑定失败但错误不明显 - 如果用
ssl，别漏掉credentials参数；insecure 模式下也别传空字符串或None给 credentials 相关字段 - 启动后用
netstat -an | grep 50051（Linux/macOS）或netstat -ano | findstr :50051（Windows）确认端口真在监听，避免“看似启动成功实则静默失败”
client 调用时卡住或报 StatusCode.UNAVAILABLE
UNAVAILABLE 不一定是服务挂了，更可能是连接参数、TLS 设置或 DNS 解析出了问题。Python client 默认不设超时，一卡就是几十秒，容易误判为服务异常。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 构造 channel 时务必加
options=[('grpc.max_send_message_length', -1), ('grpc.max_receive_message_length', -1)]，否则默认 4MB 上限，大响应直接断连 - 调用方法时显式传
timeout=10（单位秒），避免无限等待；错误处理别只 catchException，优先捕获grpc.RpcError并 inspecterror.code()和error.details() - insecure channel 要用
grpc.insecure_channel('localhost:50051')，不能写成http://或https://—— gRPC channel 地址不带协议前缀 - 跨容器或远程调用时，别用
localhost，换成宿主机 IP 或 service 名（K8s 环境下），DNS 解析失败时 UNAVAILABLE 是默认 fallback 错误码
真正麻烦的是 protobuf 版本混用：client 用 v3.20 生成的 stub，server 用 v3.19 编译的 pb2，字段解析可能错位。这种问题不报错，只默默丢数据——得靠打日志看 raw request body 才能定位。
