Huma框架中自定义字段验证错误消息的方法

在使用Huma框架进行API开发时，我们经常会遇到需要对输入参数进行验证的情况。默认情况下，Huma会为验证失败生成标准的错误消息，但有时这些消息可能不够友好或不符合我们的需求。本文将介绍如何在Huma框架中自定义字段验证的错误消息，特别是针对字符串长度验证的场景。

问题背景

在Huma框架中，我们可以通过结构体标签来定义字段的验证规则，例如：

type User struct {
    PhoneNumber *string `json:"phoneNumber" doc:"用户电话号码" minLength:"10" maxLength:"12"`
}

当验证失败时，Huma会生成类似以下的错误消息：

phoneNumber: length must be \u003e= 10, but got 9

这里的\u003e实际上是Unicode字符>的转义表示，虽然技术上正确，但对于最终用户来说可能不够直观。

解决方案：自定义验证器

为了提供更友好的错误消息，我们可以实现自定义类型并为其添加验证逻辑。Huma框架提供了ResolverWithPath接口，允许我们自定义验证行为。

实现自定义电话号码类型

type PhoneNumber string

func (s PhoneNumber) Resolve(ctx huma.Context, prefix *huma.PathBuffer) []error {
    l := len(s)
    if l < 10 || l > 12 {
        return []error{&huma.ErrorDetail{
            Location: prefix.With("phoneNumber"),
            Message:  "电话号码验证失败：长度必须在10到12位之间",
            Value:    s,
        }}
    }
    return nil
}

在模型中使用自定义类型

type User struct {
    PhoneNumber PhoneNumber `json:"phoneNumber,omitempty" doc:"用户电话号码"`
}

实现原理

1. 自定义类型：我们创建了一个PhoneNumber类型，本质上是string的别名，但赋予了它自定义的行为。

2. 验证逻辑：通过实现Resolve方法，我们接管了该字段的验证过程。在这个方法中，我们可以检查字段值的各种属性，并根据需要返回自定义的错误消息。

3. 错误构造：使用huma.ErrorDetail结构体可以精确控制错误的位置、消息和值，使错误信息更加清晰和友好。

优势与适用场景

这种方法的主要优势包括：

1. 更友好的错误消息：可以完全控制错误消息的格式和内容，使其更符合业务需求。

2. 集中验证逻辑：将验证逻辑与类型绑定，避免在多个地方重复相同的验证代码。

3. 更强的类型安全：使用自定义类型可以增加代码的可读性和类型安全性。

适用于以下场景：

• 需要特定格式验证的字段（如电话号码、邮箱、身份证号等）
• 需要复杂验证逻辑的字段
• 需要提供本地化或特定业务错误消息的场景

总结

通过实现自定义类型和验证逻辑，我们可以在Huma框架中灵活控制字段验证的行为和错误消息。这种方法不仅解决了Unicode字符显示的问题，还为我们提供了更强大的验证能力，使API的错误反馈更加专业和用户友好。