Go全局异常处理最佳实践

一、基础异常捕获框架

1.1 中间件式异常处理

func RecoveryMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if err := recover(); err != nil {
                stack := debug.Stack()
                log.Printf("[PANIC RECOVERED] %v\n%s", err, stack)
                
                w.Header().Set("Content-Type", "application/json")
                w.WriteHeader(http.StatusInternalServerError)
                json.NewEncoder(w).Encode(map[string]interface{}{
                    "error":  "Internal Server Error",
                    "detail": fmt.Sprintf("%v", err),
                })
            }
        }()
        next.ServeHTTP(w, r)
    })
}

注册方式：

router := mux.NewRouter()
router.Use(RecoveryMiddleware)

二、结构化错误处理

2.1 自定义错误类型

type AppError struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
    Details string `json:"details,omitempty"`
}

func (e *AppError) Error() string {
    return fmt.Sprintf("code=%d, message=%s", e.Code, e.Message)
}

// 常见错误定义
var (
    ErrNotFound     = &AppError{Code: 404, Message: "Resource not found"}
    ErrUnauthorized = &AppError{Code: 401, Message: "Unauthorized access"}
)

2.2 错误响应包装器

func ErrorResponse(w http.ResponseWriter, err error) {
    switch e := err.(type) {
    case *AppError:
        w.WriteHeader(e.Code)
        json.NewEncoder(w).Encode(e)
    default:
        w.WriteHeader(http.StatusInternalServerError)
        json.NewEncoder(w).Encode(&AppError{
            Code:    http.StatusInternalServerError,
            Message: "Internal Server Error",
            Details: e.Error(),
        })
    }
}

三、统一日志记录

3.1 日志上下文集成

type RequestLogger struct {
    *log.Logger
}

func (l *RequestLogger) LogError(r *http.Request, err error) {
    l.Printf("[ERROR] %s %s %s - %v", 
        r.Method, 
        r.URL.Path, 
        r.RemoteAddr, 
        err)
}

// 初始化示例
logger := &RequestLogger{log.New(os.Stderr, "", log.LstdFlags)}

3.2 错误分级处理

graph TD
    A[捕获错误] --> B{错误类型}
    B -->|AppError| C[记录WARN]
    B -->|系统panic| D[记录ERROR]
    B -->|数据库错误| E[记录CRITICAL]
    style D fill:#f66,stroke:#333

四、HTTP服务完整示例

4.1 服务端封装

type Server struct {
    router *mux.Router
    logger *RequestLogger
}

func NewServer() *Server {
    s := &Server{
        router: mux.NewRouter(),
        logger: &RequestLogger{log.New(os.Stdout, "", log.LstdFlags)},
    }
    s.router.Use(s.recoveryMiddleware)
    s.routes()
    return s
}

func (s *Server) routes() {
    s.router.HandleFunc("/api/users", s.handleUsers).Methods("GET")
}

func (s *Server) handleUsers(w http.ResponseWriter, r *http.Request) {
    users, err := fetchUsers()
    if err != nil {
        s.logger.LogError(r, err)
        ErrorResponse(w, err)
        return
    }
    json.NewEncoder(w).Encode(users)
}

五、GRPC集成方案

5.1 GRPC拦截器

func UnaryServerInterceptor(
    ctx context.Context,
    req interface{},
    info *grpc.UnaryServerInfo,
    handler grpc.UnaryHandler,
) (resp interface{}, err error) {
    defer func() {
        if r := recover(); r != nil {
            err = status.Errorf(
                codes.Internal,
                "panic recovered: %v",
                r,
            )
            log.Printf("[GRPC PANIC] %s: %v", info.FullMethod, r)
        }
    }()
    
    resp, err = handler(ctx, req)
    return
}

5.2 注册拦截器

server := grpc.NewServer(
    grpc.UnaryInterceptor(UnaryServerInterceptor),
)

六、错误码标准化

6.1 错误码枚举

const (
    CodeSuccess = iota
    CodeInvalidParam
    CodeDBError
    CodeAuthFailed
    CodeRateLimit
)

var codeMessages = map[int]string{
    CodeSuccess:     "Success",
    CodeInvalidParam: "Invalid parameters",
    CodeDBError:     "Database operation failed",
    CodeAuthFailed:  "Authentication failed",
    CodeRateLimit:   "Request rate exceeded",
}

6.2 业务错误构造

func NewBizError(code int, details ...string) *AppError {
    msg, ok := codeMessages[code]
    if !ok {
        msg = "Unknown error"
    }
    
    err := &AppError{
        Code:    code,
        Message: msg,
    }
    
    if len(details) > 0 {
        err.Details = strings.Join(details, "; ")
    }
    
    return err
}

七、性能监控集成

7.1 Prometheus指标

var (
    errorCounter = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "app_errors_total",
            Help: "Total number of errors",
        },
        []string{"type", "endpoint"},
    )
)

func init() {
    prometheus.MustRegister(errorCounter)
}

func RecordError(errType, endpoint string) {
    errorCounter.WithLabelValues(errType, endpoint).Inc()
}

7.2 集成到中间件

func (s *Server) recoveryMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        defer func() {
            if err := recover(); err != nil {
                RecordError("panic", r.URL.Path)
                // ...原有恢复逻辑
            }
        }()
        next.ServeHTTP(w, r)
    })
}

八、测试策略

8.1 异常注入测试

func TestPanicRecovery(t *testing.T) {
    s := NewServer()
    req := httptest.NewRequest("GET", "/panic", nil)
    rr := httptest.NewRecorder()
    
    // 注入panic的路由
    s.router.HandleFunc("/panic", func(w http.ResponseWriter, r *http.Request) {
        panic("test panic")
    })
    
    s.ServeHTTP(rr, req)
    
    if rr.Code != http.StatusInternalServerError {
        t.Errorf("expected status 500, got %d", rr.Code)
    }
    
    var resp map[string]interface{}
    json.Unmarshal(rr.Body.Bytes(), &resp)
    
    if resp["error"] != "Internal Server Error" {
        t.Errorf("unexpected error message: %v", resp["error"])
    }
}

九、生产环境建议

9.1 错误报告集成

// Sentry集成示例
func ReportError(err error, r *http.Request) {
    if hub := sentry.GetHubFromContext(r.Context()); hub != nil {
        hub.WithScope(func(scope *sentry.Scope) {
            scope.SetRequest(r)
            hub.CaptureException(err)
        })
    }
}

// 在中间件中使用
defer func() {
    if err := recover(); err != nil {
        ReportError(fmt.Errorf("%v", err), r)
        // ...其他处理
    }
}()

9.2 关键配置参数

参数	推荐值	说明
日志保留周期	30天	满足故障回溯需求
错误采样率	生产环境100%	确保关键错误不漏报
告警阈值	5次/分钟	触发运维告警
堆栈深度	4层	平衡信息量与可读性

十、完整架构图示

graph TD
    A[请求入口] --> B[Recovery中间件]
    B --> C{业务处理}
    C -->|正常| D[返回结果]
    C -->|异常| E[错误分类]
    E -->|可预期错误| F[AppError响应]
    E -->|系统异常| G[500响应+日志]
    G --> H[监控系统]
    H --> I[告警通知]
    style B fill:#bbf,stroke:#333
    style I fill:#f66,stroke:#333

实施建议：