gRPC错误必须用status.Error构造，否则客户端收到Unknown错误；客户端需用status.FromError解包获取code和details；可借助WithDetails添加结构化信息，但需提前注册proto类型；context超时/取消错误不可包装为status.Error。
gRPC 错误必须用 status.Error 构造，不能直接返回 Go 原生 error
Go 原生 error 在 gRPC 传输中会被序列化为空消息，客户端收到的是 status.Code = Unknown、status.Message = ""，根本看不出错在哪。gRPC 规范要求所有错误必须包装成 status.Status 实例，再通过 status.Error 转为 error 类型返回。
正确做法是：在服务端 handler 中调用 status.Error，传入标准 code 和带上下文的 message：
import "google.golang.org/grpc/status"
func (s *Server) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
if req.Id == "" {
return nil, status.Error(codes.InvalidArgument, "id is required")
}
// ...
}
常见错误写法：
-
return nil, fmt.Errorf("id is required")→ 客户端看到UNKNOWN -
return nil, errors.New("id is required")→ 同上 -
return nil, status.New(codes.InvalidArgument, "id is required").Err()→ 可行但冗余，status.Error更直接
客户端如何正确检查和提取 gRPC 错误详情
客户端收到的 error 是 *status.Status 的封装，必须用 status.FromError 解包才能拿到 code 和 details。直接用 err.Error() 只能打印字符串，无法做类型判断或结构化解析。
立即学习“go语言免费学习笔记（深入）”；
典型检查模式：
resp, err := client.GetUser(ctx, &pb.GetUserRequest{Id: "123"})
if err != nil {
st, ok := status.FromError(err)
if !ok {
// 不是 gRPC 错误，可能是网络断开、context canceled 等
log.Fatal("non-gRPC error:", err)
}
switch st.Code() {
case codes.NotFound:
log.Println("user not found")
case codes.InvalidArgument:
log.Printf("validation failed: %s", st.Message())
default:
log.Printf("unexpected RPC error: %v", st)
}
return
}
注意点：
-
status.FromError对非 gRPC error 返回ok = false，不能跳过这个判断 -
st.Message()是服务端传入的原始 message 字符串，不含 code；如需完整描述，可拼接：fmt.Sprintf("%s: %s", st.Code(), st.Message()) - 不要用
strings.Contains(err.Error(), "NotFound")做判断 —— 不可靠，且破坏了 code 的语义契约
如何在错误中附带结构化信息（如字段名、重试建议）
单纯靠 status.Error 的 string message 不足以支撑前端精细化提示或自动重试逻辑。gRPC 支持通过 status.WithDetails 添加任意 proto message 到 error 中，前提是该 message 已注册到 status.RegisteredDetails。
例如定义一个 ValidationError：
message ValidationError {
string field = 1;
string reason = 2;
}
服务端添加 details：
import "google.golang.org/grpc/status"
import "google.golang.org/genproto/googleapis/rpc/errdetails"
func (s *Server) CreateUser(ctx context.Context, req *pb.CreateUserRequest) (*pb.User, error) {
if req.Email == "" {
ve := &errdetails.BadRequest_FieldViolation{
Field: "email",
Description: "email is required",
}
badReq := &errdetails.BadRequest{}
badReq.FieldViolations = append(badReq.FieldViolations, ve)
st := status.New(codes.InvalidArgument, "invalid request")
st, _ = st.WithDetails(badReq)
return nil, st.Err()
}
// ...
}
客户端提取：
st, _ := status.FromError(err)
for _, detail := range st.Details() {
if v, ok := detail.(*errdetails.BadRequest); ok {
for _, fv := range v.FieldViolations {
log.Printf("field %s invalid: %s", fv.Field, fv.Description)
}
}
}
关键限制：
- 所有 details proto message 必须提前注册，否则
st.Details()返回空切片 —— 默认只注册了errdetails包下的几个标准类型 - 自定义 message 需手动调用
status.RegisterType(&MyCustomError{}, "type.googleapis.com/xxx.MyCustomError") - details 会增加响应体积，高频调用场景慎用大结构体
context 超时和取消错误不能当作业务错误处理
context.DeadlineExceeded 和 context.Canceled 是调用生命周期控制信号，不是服务端返回的业务错误。它们会以非 *status.Status 形式透传给客户端，status.FromError 会返回 ok = false。
这意味着：你不能假设所有 error 都能解包出 gRPC code；必须先区分是传输层中断还是服务端主动报错。
典型误操作：
- 把
ctx.Err()直接 return 给 gRPC handler → 客户端收不到标准 code - 在 middleware 中统一拦截所有 error 并转成
status.Error(codes.Internal, ...)→ 抹掉了超时/取消的语义，导致前端无法区分“服务卡住”和“服务炸了”
合理做法是保留原 error 类型，在日志或监控中单独标记：
if ctx.Err() == context.DeadlineExceeded {
log.Warn("request timed out before response")
return nil, ctx.Err() // 不包装，让 client 自行处理
}
// 其他业务逻辑...
真正容易被忽略的是：gRPC 连接池、负载均衡器、网关（如 Envoy）可能对超时做二次解释，服务端看到的 ctx.Err() 不一定等于客户端发起的 timeout —— 链路中任一环节超时都会触发它。
