在Huma框架中实现全局错误日志记录的最佳实践

背景介绍

Huma是一个用于构建RESTful API的Go语言框架，它提供了简洁的API设计和丰富的中间件支持。在实际开发中，我们经常需要记录API处理过程中发生的错误，以便后续分析和排查问题。

问题分析

在Huma框架中，当操作处理器返回错误时，默认情况下错误会被转换为相应的HTTP状态码和响应体。然而，开发者有时需要在中间件中访问这些原始错误信息，以便进行统一的日志记录或其他处理。

解决方案

方法一：包装上下文对象

通过创建一个自定义的上下文包装器，我们可以拦截并记录错误响应。这种方法的关键在于实现一个结构体，该结构体包装原始的huma.Context接口，并添加我们需要的功能。

type NewContext struct {
    humaCtx huma.Context
    newCtx  context.Context
}

// 实现huma.Context接口的所有方法
func (c *NewContext) Context() context.Context { return c.newCtx }
// ... 其他方法实现 ...

方法二：使用响应转换器

Huma提供了响应转换器功能，可以在响应被序列化之前对数据进行处理。我们可以利用这一特性来检查并记录错误。

api.UseTransformer(func(v interface{}) (interface{}, error) {
    if err, ok := v.(error); ok {
        logError(err)
    }
    return v, nil
})

方法三：包装注册函数

通过包装huma.Register函数，我们可以在每个操作处理器执行后添加自定义的错误处理逻辑。

func Register[I, O any](api huma.API, op huma.Operation, handler func(context.Context, *I) (*O, error)) {
    huma.Register(api, op, func(ctx context.Context, input *I) (*O, error) {
        res, err := handler(ctx, input)
        if err != nil {
            logError(err)
        }
        return res, err
    })
}

综合实践

在实际项目中，我们通常会结合多种方法来实现更完善的错误处理机制。例如，可以同时使用上下文包装和注册函数包装：

1. 在中间件中包装上下文，添加跟踪ID等信息
2. 在包装的注册函数中记录错误，并关联跟踪ID

func TraceMiddleware(humaCtx huma.Context, next func(huma.Context)) {
    newCtx := &NewContext{
        humaCtx: humaCtx,
        newCtx: context.WithValue(humaCtx.Context(), "trace", humaCtx.Header("X-Trace-ID")),
    }
    next(newCtx)
}

func RegisterWithLogging[I, O any](api huma.API, op huma.Operation, handler func(context.Context, *I) (*O, error)) {
    huma.Register(api, op, func(ctx context.Context, input *I) (*O, error) {
        res, err := handler(ctx, input)
        if err != nil {
            traceID := ctx.Value("trace").(string)
            log.Printf("[%s] Error: %v", traceID, err)
        }
        return res, err
    })
}

最佳实践建议

1. 统一错误处理：确保所有错误都经过相同的处理流程，保持日志格式一致
2. 上下文传递：利用context.Context传递请求相关的元数据，如跟踪ID、用户信息等
3. 错误分类：根据错误类型和严重程度采取不同的处理策略
4. 性能考虑：在高并发场景下，注意日志记录的性能影响，考虑异步记录

总结

在Huma框架中实现全局错误日志记录需要理解框架的请求处理流程和中间件机制。通过合理组合上下文包装、注册函数包装和响应转换器等技术，我们可以构建出灵活且强大的错误处理系统，为API的稳定运行和问题排查提供有力支持。