gRPC 错误处理入门第一课用 grpc-errors 快速搞懂 9 大语言的报错与捕获【免费下载链接】grpc-errorsA handy guide to gRPC errors项目地址: https://gitcode.com/gh_mirrors/gr/grpc-errors学习 gRPC 错误处理时新手最大的困惑就是不同语言的报错与捕获写法千差万别。本文以开源项目grpc-errors为向导用一个 Hello 示例带你一次性搞懂 Python、Go、C# 等 9 大语言中服务端如何报错、客户端如何捕获帮你快速建立统一的 gRPC 错误处理心智模型。为什么需要一份 gRPC 错误处理速查表如果你用过 HTTP对404 Not Found、500 Internal Server Error一定不陌生。gRPC 也有类似的状态码体系——Status Code只不过它更精细HTTP 习惯gRPC 错误码含义400INVALID_ARGUMENT参数不合法401UNAUTHENTICATED未认证403PERMISSION_DENIED无权限404NOT_FOUND资源不存在429RESOURCE_EXHAUSTED资源耗尽/限流超时DEADLINE_EXCEEDED调用超时503UNAVAILABLE服务不可用gRPC 一共有 16 个标准错误码。服务端选对码、客户端读对码就是 gRPC 错误处理的全部核心。grpc-errors 正是为此而生的项目——它为同一份接口协议提供了 9 种主流语言的完整报错/捕获示例堪称人形速查表。3 分钟看懂项目结构整个项目围绕一个极简协议展开hello.proto 中定义了HelloService服务的两个方法SayHello永远成功返回 Hey, (name)!SayHelloStrict当Name长度超过 10 个字符时抛出INVALID_ARGUMENT错误service HelloService { rpc SayHello(HelloReq) returns (HelloResp) {}; rpc SayHelloStrict(HelloReq) returns (HelloResp) {}; }每个语言目录都是一份标准答案语言目录服务端客户端Pythonpython/server.pyclient.pyGogo/server.goclient.goNode.jsnode/server.jsclient.jsC#csharp/Hello/HelloServer/Program.cscsharp/Hello/HelloClient/Ccpp/server.cppclient.cppRustrust/server.rsrust/src/client.rsRubyruby/ruby/server.rbruby/client.rbScalascala/scala/src/main/scala/hello/server/scala/src/main/scala/hello/client/Swift / Objective-Cswift/、objective-c/示例客户端工程—学习建议先看 Python语法最接近伪代码再看 Go错误处理风格最典型其余语言对照速查即可。服务端报错三步法以 Python 为例所有语言的服务端报错本质都是同一套动作检查条件 → 选择错误码 → 附带错误信息。以 python/server.py 中最清晰的实现为例def SayHelloStrict(self, request, context): if len(request.Name) 10: context.set_details(Length of Name cannot be more than 10 characters) context.set_code(grpc.StatusCode.INVALID_ARGUMENT) return hello_pb2.HelloResp()其他语言的同一种写法Go直接返回 error ——status.Errorf(codes.InvalidArgument, Length ofName...)见 go/server.goC#抛出异常 ——throw new RpcException(new Status(StatusCode.InvalidArgument, msg))Node.js把错误码塞进回调 ——callback({code: grpc.status.INVALID_ARGUMENT, message: msg})C返回Status(StatusCode::INVALID_ARGUMENT, msg)Ruby / Scala / Rustraise/Status.INVALID_ARGUMENT.asException/grpcio错误返回套路一致✅ 记住错误信息message写给人看错误码code写给程序看。客户端永远靠 code 做分支判断而不是靠 message 文本。客户端捕获三步法读码 → 读信息 → 做分支捕获端同样只有三步。最直观的 Python 版python/client.pytry: response stub.SayHelloStrict(hello_pb2.HelloReq(NameLeonhard Euler)) except grpc.RpcError as e: print(e.details()) # 错误信息 status_code e.code() if status_code grpc.StatusCode.INVALID_ARGUMENT: pass # 针对特定错误码做处理各语言捕获方式速查语言捕获方式取错误码取错误信息Pythonexcept grpc.RpcErrore.code()e.details()Goif err ! nilstatus.Code(err)status.Convert(err).Message()Node.js回调第一个参数err.codeerr.detailsC#try/catch RpcExceptionex.StatusCodeex.DetailC检查grpc::Statusst.error_code()st.error_message()Rubyrescue GRPC::RpcErrore.status_codee.detailsScalatry/catch StatusRuntimeExceptionstatus.codestatus.descriptionRustResult的Err分支status.code()status.message()⚠️新手易错点不要捕获所有异常然后打印。正确姿势是针对错误码做精确分支——比如INVALID_ARGUMENT提示用户改参数UNAVAILABLE才值得自动重试UNAUTHENTICATED则应引导重新登录。常用 gRPC 错误码选型指南选错错误码是新人最常见的问题这里给一张决策小抄用户传参不合法 →INVALID_ARGUMENT参数格式对但语义冲突如要删除一个已删除的资源→FAILED_PRECONDITION调用方未登录/令牌过期 →UNAUTHENTICATED资源不存在 →NOT_FOUND客户端超时 →DEADLINE_EXCEEDED服务端依赖挂了、网络不通 →UNAVAILABLE客户端可安全重试服务端自己的 bug →UNKNOWN最后手段优先想清楚具体是哪类错误本地运行 Demo最快上手路径 整个项目跑起来只需要两样依赖gRPC和protobuf 编译器protoc。第 1 步克隆仓库git clone https://gitcode.com/gh_mirrors/gr/grpc-errors第 2 步选一个语言跑起来推荐 Pythoncd grpc-errors/python pip install -r requirements.txt python server.py python client.py第 3 步观察错误客户端会先打印成功调用SayHello的返回然后触发SayHelloStrict的报错你会看到完整的错误信息Length ofNamecannot be more than 10 characters和错误码INVALID_ARGUMENT——这就是服务端报错到客户端捕获的完整链路。其他语言的构建步骤都写在各自目录的 README 中例如 go/README.md 里的protoc生成命令和go build流程照着敲即可。新手常见问题 FAQQ1gRPC 错误码和 HTTP 状态码能一一对应吗不能。gRPC 状态码更细16 种gRPC-Web 或网关场景下才需要映射到 HTTP 状态码。Q2自定义业务错误码怎么传标准做法是通过元数据Metadata或错误 message 携带业务码Status Code 保持标准含义两者各司其职。Q3哪些错误可以自动重试一般UNAVAILABLE、DEADLINE_EXCEEDED这类网络类错误适合重试INVALID_ARGUMENT这类客户端错误重试多少次都一样不要重试。写在最后gRPC 错误处理并不神秘服务端选对 Status Code客户端按 Code 精确分支剩下的只是各语言的语法差异。建议把 grpc-errors 当作随身速查手册——以后每接触一种新语言翻翻对应目录10 分钟就能补上该语言的错误处理知识。【免费下载链接】grpc-errorsA handy guide to gRPC errors项目地址: https://gitcode.com/gh_mirrors/gr/grpc-errors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考