Huma v2.29.0 版本发布：增强多部分表单处理与参数定制能力

Huma 是一个用于构建 RESTful API 的 Go 框架，它通过 OpenAPI 3.1 规范自动生成文档，并提供强大的输入验证和序列化功能。最新发布的 v2.29.0 版本带来了一系列重要改进，特别是在多部分表单处理、参数定制和路由功能方面。

多部分表单处理能力增强

新版本显著提升了多部分表单的处理能力，现在开发者可以在表单中使用任意类型的字段，这些字段会被自动解析和验证。这种改进使得处理文件上传和结构化数据变得更加灵活和强大。

huma.Register(api, huma.Operation{
    OperationID: "upload-and-decode-files"
    Method:      http.MethodPost,
    Path:        "/upload",
}, func(ctx context.Context, input *struct {
    RawBody huma.MultipartFormFiles[struct {
        MyFile                    huma.FormFile   `form:"file" contentType:"text/plain" required:"true"`
        SomeOtherFiles            []huma.FormFile `form:"other-files" contentType:"text/plain" required:"true"`
        NoTagBindingFile          huma.FormFile   `contentType:"text/plain"`
        MyGreeting                string          `form:"greeting", minLength:"6"`
        SomeNumbers               []int           `form:"numbers"`
        NonTaggedValuesAreIgnored string  // 会被忽略
    }]
}) (*struct{}, error) {
    // 处理逻辑...
})

这种设计允许开发者在一个表单中混合文件上传和其他结构化数据，同时保持类型安全和自动验证。

改进的子路由自动补丁支持

自动补丁功能现在能够识别公共路径前缀，这使得在子路由中使用自动补丁变得更加可靠。例如，当 API 路由被组织在 /api 前缀下时，自动补丁功能仍然能够正确工作。

func apiMux() func(chi.Router) {
    return func(router chi.Router) {
        api := humachi.New(router, humaConfig)
        huma.Register(api, huma.Operation{
            Method: "GET",
            Path:   "/ressources/{id}",
        }, getRessourceByID)
        autopatch.AutoPatch(api)  // 现在能正确处理子路由
    }
}

这一改进使得大型项目的路由组织更加灵活，同时保持了自动补丁功能的便利性。

参数定制能力增强

v2.29.0 引入了两个新接口，为参数定制提供了更强大的能力：

type ParamWrapper interface {
    Receiver() reflect.Value
}

type ParamReactor interface {
    OnParamSet(isSet bool, parsed any)
}

开发者可以利用这些接口创建更复杂的参数类型。例如，实现一个可选参数类型：

type OptionalParam[T any] struct {
    Value T
    IsSet bool
}

func (o OptionalParam[T]) Schema(r huma.Registry) *huma.Schema {
    return huma.SchemaFromType(r, reflect.TypeOf(o.Value))
}

func (o *OptionalParam[T]) Receiver() reflect.Value {
    return reflect.ValueOf(o).Elem().Field(0)
}

func (o *OptionalParam[T]) OnParamSet(isSet bool, parsed any) {
    o.IsSet = isSet
}

这种设计模式使得开发者可以创建符合自己业务需求的参数类型，同时保持与 Huma 框架的无缝集成。

深度对象参数支持

新版本增加了对 OpenAPI deepObject 样式的支持，允许在查询参数中发送结构化数据。这对于需要复杂查询条件的 API 特别有用。

huma.Get(api, "/greeting", func(ctx context.Context, input *struct {
    Person Person            `query:"person,deepObject"`
    Map    map[string]string `query:"map,deepObject"`
}) (*GreetingOutput, error) {
    // 处理逻辑...
})

客户端可以通过类似 ?person[name]=foo&map[a]=foo 的查询字符串传递结构化数据，服务端会自动解析为对应的 Go 结构体。

其他重要改进

1. 外部模式支持：现在可以安全地使用外部 JSON Schema 引用而不会导致 panic，虽然这些外部模式不会被验证，但对于文档生成和客户端开发很有帮助。

2. Fiber 适配器稳定性提升：对 humafiber 适配器进行了重大重构，修复了潜在的竞争条件，并确保测试中启用了竞态检测器。

3. 验证优化：修复了可能导致重复验证错误的问题，提升了错误处理的准确性。

4. 自定义请求体保留：当开发者提供自定义请求体模式时，Huma 不再覆盖它，这为高级用例提供了更大的灵活性。

总结

Huma v2.29.0 版本在多方面进行了增强，特别是改进了表单处理、参数定制和路由功能。这些改进使得开发者能够构建更灵活、更强大的 RESTful API，同时保持框架的简洁性和类型安全性。对于需要处理复杂输入场景或需要高度定制化参数的开发者来说，这个版本提供了更多可能性。