微服务需统一错误响应结构，采用含code、message、status、request_id字段的jsON格式；定义appError类型及工厂方法封装错误；通过中间件统一拦截panic和AppError并转换为标准响应；集成结构化日志与错误上报。
定义统一错误响应结构
微服务中各接口返回的错误格式必须一致，便于前端统一解析和日志系统归集。推荐使用 json 格式，包含状态码、错误码、错误信息和可选的请求 ID：
- code：业务错误码（如 red”>1001 表示参数校验失败，5001 表示数据库连接异常）
- message：面向用户或调用方的简明提示（如 “用户名不能为空”）
- status：http 状态码（如 400、500），用于网关或反向代理识别
- request_id：全局唯一请求 ID，方便链路追踪与问题定位
type ErrorResponse struct { Code int `json:"code"` Message string `json:"message"` Status int `json:"status"` RequestID string `json:"request_id,omitempty"` }封装自定义错误类型与工厂方法
避免直接使用 errors.New 或 fmt.Errorf，而是构建可携带错误码和 HTTP 状态的错误类型：
type AppError struct { Code int Message string Status int } func (e *AppError) Error() string { return e.Message } // 工厂函数示例 func NewBadRequest(code int, msg string) *AppError { return &AppError{Code: code, Message: msg, Status: http.StatusbadRequest} } func NewinternalError(code int, msg string) *AppError { return &AppError{Code: code, Message: msg, Status: http.StatusInternalServerError} }将常用错误预定义为常量，提高可读性和复用性：
立即学习“go语言免费学习笔记（深入）”；
const ( ErrInvalidParam = iota + 1000 ErrUserNotFound ErrDBConnection ) var ( ErrInvalidParamError = NewBadRequest(ErrInvalidParam, "请求参数不合法") ErrUserNotFoundError = NewBadRequest(ErrUserNotFound, "用户不存在") )中间件统一拦截并转换错误
在 gin / echo / Fiber 等框架中，通过中间件捕获 handler 中 panic 或显式返回的 *AppError，并统一渲染响应：
Find JSON Path Online
193
Easily find JSON paths within JSON objects using our intuitive Json Path Finder
193 
- 捕获 panic（如空指针、数组越界），转为 500 Internal Server Error
- 判断返回值是否为 *AppError，提取字段构造 ErrorResponse
- 设置对应 HTTP 状态码，并写入响应头 X-Request-ID
Gin 示例中间件：
func ErrorHandler() gin.HandlerFunc { return func(c *gin.Context) { defer func() { if err := recover(); err != nil { c.JSON(http.StatusInternalServerError, ErrorResponse{ Code: 5000, Message: "服务内部异常", Status: http.StatusInternalServerError, RequestID: c.GetString("request_id"), }) return } }() c.Next() if len(c.Errors) > 0 { appErr, ok := c.Errors.Last().Err.(*AppError) if ok { c.JSON(appErr.Status, ErrorResponse{ Code: appErr.Code, Message: appErr.Message, Status: appErr.Status, RequestID: c.GetString("request_id"), }) c.Abort() return } } } }注册时注意顺序：先注入请求 ID 中间件，再注册错误处理中间件。
集成日志与错误上报（可选增强）
在错误中间件中，记录结构化日志（含 error stack、request_id、path、method）；对特定错误码（如 DB、rpc 调用失败）触发告警或上报至 sentry / prometheus：
- 使用 log/slog 或 zerolog 记录错误上下文
- 对非预期 panic 或高频错误码添加采样上报逻辑
- 敏感字段（如密码、Token）需在日志前脱敏
例如：
slog.Error("app error occurred", "request_id", c.GetString("request_id"), "path", c.Request.URL.Path, "error_code", appErr.Code, "error_msg", appErr.Message, "stack", debug.Stack())