Huma框架中中间件间数据传递的最佳实践

前言

在Web开发框架中，中间件间的数据传递是一个常见需求。本文将深入探讨如何在Huma这一路由器无关的REST框架中优雅地实现中间件间的数据共享，特别是针对JWT认证等场景。

问题背景

在传统框架如Gin中，我们可以通过gin.Context.Set/Get方法轻松地在中间件间传递数据。然而Huma作为路由器无关的框架，需要一种更通用的解决方案。

核心解决方案

1. 通过上下文包装器传递数据

Huma提供了通过包装huma.Context接口来传递数据的灵活方式：

// 临时类型重命名避免冲突
type humaContext huma.Context

type MyContext struct {
    humaContext
}

func (c *MyContext) Context() context.Context {
    // 在上下文中设置自定义值并返回
    return context.WithValue(c.humaContext.Context(), "key", "value")
}

func MyMiddleware(ctx huma.Context, next func(huma.Context)) {
    // 在链中调用下一个中间件，使用包装后的上下文
    next(&MyContext{ctx})
}

这种模式是Go语言中的常见做法，允许你通过自定义上下文来传递任意数据。

2. 使用共享结构体与解析器

对于需要在操作处理函数中访问上下文数据的情况，推荐使用共享结构体配合解析器：

type UserInfo struct {
    Username string
}

func (u *UserInfo) Resolve(ctx huma.Context) []error {
    // 从上下文中获取用户信息
    u.Username = ctx.Context().Value("username").(string)
    return nil
}

然后在操作处理函数中嵌入这个结构体：

func later(api huma.API) {
    huma.Register(api, huma.Operation{
        OperationID: "get-user",
        Method:      http.MethodGet,
        Path:        "/user",
    }, func(ctx context.Context, input *struct {
        UserInfo
    }) (*UserResponse, error) {
        resp := &UserResponse{}
        resp.Body.Name = input.Username
        return resp, nil
    })
}

3. 替代方案：使用隐藏头部

如果不希望使用解析器，还可以考虑通过中间件设置内部头部：

type UserInfo struct {
    Username string `header:"InternalUsername" hidden:"true"`
}

这种方法利用了Huma的头部解析能力，同时通过hidden标签避免了这些内部头部暴露在API文档中。

实际应用：JWT认证示例

结合上述技术，我们可以实现一个完整的JWT认证中间件：

func JWTMiddleware(ctx huma.Context, next func(huma.Context)) {
    // 1. 从Authorization头获取JWT
    tokenString := strings.TrimPrefix(ctx.Header("Authorization"), "Bearer ")
    
    // 2. 解析JWT获取用户信息
    claims := parseJWT(tokenString)
    
    // 3. 创建包装上下文
    wrappedCtx := &struct {
        huma.Context
        username string
    }{
        Context:  ctx,
        username: claims.Username,
    }
    
    // 4. 调用后续处理
    next(wrappedCtx)
}

总结

Huma框架提供了多种灵活的方式来实现中间件间的数据传递：

1. 通过包装huma.Context接口来扩展上下文能力
2. 使用共享结构体配合解析器模式实现操作间的数据共享
3. 利用隐藏头部作为轻量级替代方案

这些方法各有适用场景，开发者可以根据具体需求选择最合适的实现方式。特别是在实现认证、授权等跨切面关注点时，这些技术能够帮助保持代码的整洁和可维护性。