设计Go RPC服务时需统一错误结构，使用结构化RPCError包含Code、Message和Details；映射gRPC标准状态码如InvalidArgument、NotFound；分层管理错误码，按1xx、2xx、3xx划分客户端、服务端、第三方错误；返回客户端信息应简洁友好，避免暴露技术细节，调试模式下可返回更多上下文，确保错误可分类、可追溯、可处理。
在Go语言中设计RPC服务时，错误处理和状态码的合理使用对系统的可维护性、可观测性和客户端体验至关重要。直接返回裸错误不仅难以调试，还会让调用方无法准确判断问题类型。以下是实际开发中总结的关键技巧。
统一错误结构设计
避免使用errors.New或fmt.Errorf直接返回字符串错误。应定义结构化错误类型，包含错误码、消息和可选详情。
例如：
type RPCError struct {
Code int // 业务或系统错误码
Message string // 可展示给用户的提示
Details interface{} // 调试信息，如字段名、原始值等
}
立即学习“go语言免费学习笔记（深入）”；
这样客户端可根据Code做条件判断，Message用于展示，Details辅助日志和排查。
映射gRPC标准状态码
若使用gRPC，建议遵循其codes.Code规范（如NotFound、InvalidArgument等）。在服务端将内部错误转为标准状态，并携带自定义错误信息。
示例转换逻辑：
switch err := internalErr.(type) {
case *ValidationError:
return status.Errorf(codes.InvalidArgument, "参数校验失败: %s", err.Field)
case *NotFoundError:
return status.Errorf(codes.NotFound, "资源不存在")
default:
return status.Errorf(codes.Internal, "服务器内部错误")
}
这样做既符合生态习惯，也便于生成文档和工具识别。
错误码分层管理
大型系统中，错误码应分层定义：公共层（通用错误）+ 模块层（业务特定错误）。避免全局冲突，也方便扩展。
常见做法：
- 1xx 表示客户端输入错误（如参数缺失）
- 2xx 表示服务端处理异常（如数据库超时）
- 3xx 保留给第三方依赖错误（如调用外部API失败）
每个模块在对应范围内分配具体数值，比如用户服务用1001表示用户名已存在，订单服务用1101表示库存不足。
客户端友好的信息传递
不要把技术细节暴露给最终用户。服务端记录完整错误日志，但返回给客户端的信息要简洁明确。
例如，数据库唯一约束失败，日志可记录"duplicate key error on email"，但返回错误应是：
{ "code": 1002, "message": "邮箱已被注册", "details": null }
同时支持调试模式，在请求头中加入X-Debug: true时返回更多上下文，便于开发排查。
基本上就这些。关键是保持一致性，让错误可分类、可追溯、可处理。不复杂但容易忽略。
