微服务需统一错误响应结构，采用含code、message、status、request_id字段的JSON格式；定义AppError类型及工厂方法封装错误；通过中间件统一拦截panic和AppError并转换为标准响应；集成结构化日志与错误上报。
定义统一错误响应结构
微服务中各接口返回的错误格式必须一致，便于前端统一解析和日志系统归集。推荐使用 JSON 格式，包含状态码、错误码、错误信息和可选的请求 ID：
- code：业务错误码（如 red">1001 表示参数校验失败，5001 表示数据库连接异常）
- message：面向用户或调用方的简明提示（如 "用户名不能为空"）
- status：HTTP 状态码（如 400、500），用于网关或反向代理识别
- request_id：全局唯一请求 ID，方便链路追踪与问题定位
Go 中可定义如下结构体：
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，并统一渲染响应：
- 捕获 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()) 
