go-kit中错误需分层处理：transport层用transport.Error或status.Error显式封装状态码，endpoint层返回业务错误，domain层定义语义化错误值；各层映射缺一不可，否则降级为500/UNKNOWN。
go-kit 中 error 要封装成 transport.Error 才能被 HTTP/gRPC 层识别
直接 return 原生 error，比如 errors.New("not found")，在 HTTP transport 里默认会变成 500 Internal Server Error，且响应体是空的或只有模糊的 JSON 错误。go-kit 要求你显式把业务错误映射为可序列化的、带状态码的 transport 错误。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
transport.NewError包装错误，第一个参数是 HTTP 状态码（如http.StatusNotFound），第二个是原始 error； - 确保你的
DecodeRequestFunc和EncodeResponseFunc都处理了transport.Error类型（尤其是 encode 响应时要检查err != nil并调用encodeError）； - 不要在 endpoint 层 return
transport.Error—— 它是 transport 层概念，endpoint 应该只返回业务 error，由 transport 的server.EncodeResponse统一转换。
自定义 error 类型需实现 Error() 和 ErrorCode() 才能统一透传状态码
如果你有一套业务错误码体系（如 ErrUserNotFound = &appError{code: "USER_NOT_FOUND", httpCode: 404}），go-kit 不会自动识别 httpCode 字段。必须让错误类型满足两个条件：能转成字符串（Error() 方法），且能暴露状态码（通常加一个 ErrorCode() int 方法）。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 定义结构体错误类型，包含
code string、msg string、httpStatus int字段； - 实现
Error() string返回用户友好的提示（如return e.msg）； - 实现
ErrorCode() int返回对应 HTTP 状态码（如return e.httpStatus）； - 在 transport 的
encodeError函数中做类型断言：if e, ok := err.(interface{ ErrorCode() int }); ok { statusCode = e.ErrorCode() }。
kit/transport/http 的 ServerErrorEncoder 是控制错误响应格式的关键入口
默认的 ServerErrorEncoder 只写状态码和空 body，无法输出错误详情或自定义字段（如 {"code": "VALIDATION_FAILED", "message": "email invalid"}）。所有错误响应都经由它发出，改这里才能统一响应结构。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 不要 patch 默认 encoder，而是自己实现一个函数，签名是
func(ctx context.Context, err error, w http.ResponseWriter)； - 先根据 error 类型决定 status code（用类型断言或
errors.Is判断）； - 构造 map 或 struct，填入
code、message、trace_id（如果上下文有）； - 设
w.Header().Set("Content-Type", "application/json; charset=utf-8")，再用json.NewEncoder(w).Encode(...)输出； - 把这个函数传给
http.NewServer的ServerErrorEncoder选项。
gRPC transport 中 error 必须转成 status.Error，否则客户端收不到正确 Code
gRPC 的 error 语义靠 status.Code（如 codes.NotFound）驱动，不是 HTTP 状态码。go-kit 的 gRPC transport 不会自动转换原生 Go error，也不认你自定义的 ErrorCode() 方法。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 在 gRPC server 的
DecodeRequestFunc后、调用 endpoint 前，或在EncodeResponseFunc中，对 error 做显式转换； - 用
status.Error(codes.NotFound, "user not found")替代errors.New(...)； - 如果已有业务 error 类型，写个转换函数：
func toGRPCStatus(err error) *status.Status，内部用 switch 判断类型并返回对应codes.XXX； - 注意：gRPC client 端必须用
status.FromError(err)解包，不能直接用err.Error()判断逻辑分支。
真正难的不是怎么包装 error，而是保持 transport 层、endpoint 层、domain 层对错误语义的理解一致 —— 比如 “用户不存在” 在 HTTP 是 404，在 gRPC 是 NotFound，在 domain 层却应该只是 ErrUserNotFound 这个值对象。中间这层映射漏掉任何一个，错误就悄无声息地降级成 500 或 UNKNOWN。
