Go微服务中RPC错误需结构化设计：统一错误码、可序列化错误类型（如RPCError）、分层语义转换、脱敏日志与上下文、客户端按码分支处理，确保跨服务一致可观测。
在 Go 微服务中，RPC 错误不能只靠 error 接口的字符串描述来传递语义——它需要可识别、可分类、可跨服务一致处理。核心是：把错误当成**结构化数据**设计，而非临时字符串。
统一错误码 + 可序列化的错误结构
避免直接返回 fmt.Errorf("user not found") 这类无结构错误。定义一个可 JSON/gRPC 编码的错误类型：
例如：
- 定义
type RPCError struct { Code int32; Message string; Details map[string]string } - 所有业务错误都映射到预定义的整数错误码（如
ErrUserNotFound = 40401），而非 HTTP 状态码，避免语义混淆 - gRPC 中用
status.Error(codes.Code, msg)包装，再通过status.FromError()在客户端解包 - HTTP API 层也复用同一套错误码，响应体中显式携带
"code": 40401字段
区分错误层级：底层错误不透出，只暴露语义错误
数据库超时、Redis 连接失败这类 infra 错误，对调用方没有业务意义，不应原样向上抛。要“翻译”成服务契约内的错误语义：
立即学习“go语言免费学习笔记（深入）”；
- DB 查询失败 → 判断是否因主键不存在？是则转为
ErrUserNotFound；否则转为ErrInternal并打日志记录原始 error - 下游服务返回 503 → 不直接返回 “upstream unavailable”，而是根据当前接口语义降级或转为
ErrServiceUnavailable - 使用中间件或 defer 拦截 panic 和未处理 error，统一做语义转换和日志脱敏
错误上下文要可追溯，但不泄露敏感信息
错误消息面向开发者调试，不是给终端用户看的。需平衡可观测性与安全性：
- 在
Details字段中存入 traceID、requestID、影响的 userID（脱敏后）等调试线索 - Message 字段保持简洁、稳定、国际化友好（如 "user not found" 而非 "user 12345 not found in mysql"）
- 日志中记录原始 error（含 stack），但响应体/错误码中绝不包含路径、SQL、密码、token 等敏感内容
客户端必须按错误码分支处理，而非字符串匹配
写死 if strings.Contains(err.Error(), "not found") 是反模式。正确方式是：
- 生成客户端 SDK 时，把服务端错误码定义同步为常量（如
user.ErrUserNotFound） - 用 switch 匹配
status.Code(err)或解析响应中的code字段 - 对不同错误码设置不同重试策略（如 404 不重试，503 可指数退避重试）
- 前端或 App 根据错误码展示对应提示文案，而非依赖后端 message 字段
基本上就这些。错误语义设计不是加个 error 类型就完事，关键在服务边界上达成共识——哪类问题该由谁处理、怎么表达、怎么响应。定好规则，上下游才不会各说各话。
