Huma框架中处理互斥查询参数的最佳实践

背景介绍

在使用Huma框架开发REST API时，我们经常会遇到需要处理查询参数(Query Parameters)的场景。有时这些参数之间存在互斥关系，即在同一请求中只能使用其中一个参数。本文将探讨在Huma v2.7.0中如何优雅地实现这种需求。

问题分析

在API设计中，我们可能需要实现这样的逻辑：一个GET请求可以接受多个查询参数，但这些参数之间是互斥的。例如：

• 可以按ID过滤(filter_id)
• 也可以按关键词查询(query)
• 但不能同时使用这两个参数

直接使用结构体作为查询参数会遇到unsupported param type的错误，因为Huma框架并不支持所有OpenAPI规范中的序列化选项。

解决方案

Huma框架提供了Resolver接口来实现自定义参数解析逻辑。我们可以利用这个特性来验证参数的互斥性。

实现步骤

1. 定义参数结构体： 创建一个包含所有可能参数的结构体，每个字段都标记为查询参数。

2. 实现Resolver接口： 为该结构体实现Resolve方法，在其中添加验证逻辑。

3. 在路由中使用： 将该结构体嵌入到路由处理函数的输入参数中。

示例代码

// 定义互斥参数结构体
type FilterOrQuery struct {
    FilterID int64  `query:"filter_id" doc:"filter_id和query是互斥的"`
    Query    string `query:"query" doc:"filter_id和query是互斥的"`
}

// 实现Resolver接口
func (f *FilterOrQuery) Resolve(ctx huma.Context) []error {
    if f.FilterID != 0 && f.Query != "" {
        return []error{&huma.ErrorDetail{
            Message:  "不能同时传递filter_id和query参数",
            Location: "query",
            Value:    fmt.Sprintf("filter_id:%d query:%s", f.FilterID, f.Query),
        }}
    }
    return nil
}

// 注册路由
huma.Get(api, "/demo", func(ctx context.Context, input *struct {
    FilterOrQuery
}) (*struct{}, error) {
    // 处理逻辑
    return nil, nil
})

工作原理

1. 当请求到达时，Huma框架会先解析查询参数到结构体中。
2. 然后调用Resolve方法进行验证。
3. 如果验证失败，返回错误响应；否则继续处理请求。

优势与特点

1. 清晰的错误信息：可以自定义返回给客户端的错误消息。
2. 代码可维护性：验证逻辑集中在结构体方法中，便于维护。
3. 文档友好：通过doc标签可以直接生成API文档中的描述。

替代方案比较

虽然OpenAPI规范支持更复杂的参数序列化方式，但Huma框架选择不实现全部特性，主要基于以下考虑：

1. 保持简洁：避免框架过于复杂。
2. 性能考量：减少不必要的解析开销。
3. 明确性：使用Resolver接口使验证逻辑更加明确和可控。

最佳实践建议

1. 对于简单的互斥参数，推荐使用上述Resolver模式。
2. 如果参数关系非常复杂，可以考虑拆分为多个端点。
3. 在文档中明确说明参数的互斥关系。
4. 考虑添加示例请求到API文档中。

通过这种方式，我们可以在Huma框架中优雅地实现查询参数的互斥验证，同时保持代码的清晰和可维护性。