Go Validator 怎样通过 TagNameFunc 在错误中显示 JSON 字段名

要让 Go Validator 的错误使用 profile_name 这样的 JSON 字段名，需要在校验器首次处理结构体之前调用 RegisterTagNameFunc，从结构体的 json 标签取名称，再读取 FieldError.Field()。它负责错误中的名称映射，不负责修改 JSON 编解码行为，也不负责翻译错误文案。

官方地址：https://github.com/go-playground/validator

假设注册接口接收 profile_name 和 contact_email，后端却把 ProfileName 返回给前端。排查重点应放在“错误对象采用哪一套名字”，不必先修改 required、email 等校验规则。

先分清显示名称和校验规则

一个 Go 字段可以同时拥有三种信息：源代码名称 ProfileName、JSON 标签名 profile_name、校验标签 required。Validator 默认按 validate 标签查找规则；TagNameFunc 则提供错误名称的替代值。不要把 SetTagName("json") 当作这项功能：那会改变规则标签的读取位置，把 JSON 名称当作校验规则解析。

把注册和错误提取放进一个完整例子

下面是单文件示例，需要项目已经安装 github.com/go-playground/validator/v10。这里明确选择“未设置 JSON 名称或 JSON 名称为短横线时，使用 Go 名称兜底”的策略。回调只截取第一个逗号之前的部分，因此 json:"contact_email,omitempty" 不会把 omitempty 混入名称。

package main

import (
    "encoding/json"
    "errors"
    "fmt"
    "reflect"
    "strings"

    "github.com/go-playground/validator/v10"
)

type Signup struct {
    ProfileName string `json:"profile_name" validate:"required"`
    ContactEmail string `json:"contact_email,omitempty" validate:"required,email"`
}

type Issue struct {
    Field string `json:"field"`
    Rule  string `json:"rule"`
}

func newValidator() *validator.Validate {
    v := validator.New()
    // 在首次 Struct 调用前完成注册，随后复用此实例。
    v.RegisterTagNameFunc(func(f reflect.StructField) string {
        name := strings.SplitN(f.Tag.Get("json"), ",", 2)[0]
        if name == "" || name == "-" {
            // 默认实例使用 Go 字段名兜底；这不代表跳过校验。
            return f.Name
        }
        return name
    })
    return v
}

func collectIssues(v *validator.Validate, input Signup) ([]Issue, error) {
    err := v.Struct(input)
    if err == nil {
        return []Issue{}, nil
    }
    var fields validator.ValidationErrors
    if !errors.As(err, &fields) {
        // 非字段校验错误交给调用方处理，不冒充用户输入错误。
        return nil, err
    }
    issues := make([]Issue, 0, len(fields))
    for _, f := range fields {
        // 不回传字段原值，避免把敏感输入放入错误响应。
        issues = append(issues, Issue{Field: f.Field(), Rule: f.Tag()})
    }
    return issues, nil
}

func main() {
    v := newValidator()
    issues, err := collectIssues(v, Signup{ContactEmail: "invalid"})
    if err != nil {
        fmt.Println("校验器调用失败:", err)
        return
    }
    payload, err := json.Marshal(issues)
    if err != nil {
        fmt.Println("错误响应编码失败:", err)
        return
    }
    // 演示错误字段名称；实际 HTTP 层自行设置状态码及响应信封。
    fmt.Println(string(payload))
}

根据声明的规则，示例输入对应两项错误：profile_name 的 required，以及 contact_email 的 email。这是代码逻辑说明，未附带实际运行记录。JSON 的 omitempty 只影响编码，空邮箱仍会触发 validate 中的 required；若要允许邮箱为空，应按业务需要调整校验标签，而不是只改 JSON 标签。

接口响应建议保留字段键和规则键，再由前端或服务端翻译层生成提示语。不要直接把 err.Error() 当作稳定的用户提示协议：它是供开发者查看的错误文本。上例也没有回传 Value()，避免将用户输入原样带进响应或日志。

嵌套字段应该返回哪个路径

扁平表单通常读取 Field 即可。嵌套请求中，多个对象可能都包含 name 或 postal_code；此时只返回末级字段会丢失位置，应根据接口约定采用 Namespace，或进一步转换成业务路径。

例如具名根类型 Signup 含 Address 字段（JSON 名称 address），其中 PostalCode 的 JSON 名称为 postal_code。对应错误的 Namespace 通常是 Signup.address.postal_code，StructNamespace 是 Signup.Address.PostalCode，Field 则只有 postal_code。根结构体名称不会因为注册 JSON 名称回调就自动消失。

Namespace 不是 JSON Pointer，也不是已经完成转义的前端表单路径。集合下标、特殊字符和根名称的移除都需要你明确协议。若将路径返回给外部调用方，应先定义统一格式，不要让各个接口临时用不同的字符串截取办法。

注册后仍显示 Go 名称，按这三个位置排查

先看是否注册得太晚。Validator 会缓存结构体元信息，字段替代名也是缓存内容的一部分。一个类型已经由该实例处理过，再改变回调不能作为可靠的缓存刷新方式。将注册放到实例构造阶段，再把配置好的实例交给业务层复用；不要在请求处理期间反复修改共享实例的配置。

再看是否读错了方法。StructField 的用途就是返回 Go 字段名。已经注册回调却仍用 StructField 组装错误，当然看不到 JSON 名称。需要别名时使用 Field，需要完整别名层级时选择 Namespace。

最后看是否使用了另一个实例。在服务初始化时注册到 v1，却在 handler 中通过另一次 New 得到 v2，配置不会自动共享。把初始化函数作为唯一构造入口，并将同一个配置完成的实例注入使用方，通常比在每个 handler 里补注册更清楚。

json 短横线和空名字应如何处理

json:"-" 表示 JSON 编解码忽略该字段，不等于 Validator 忽略它。如果内部字段不需要校验，应明确使用 validate:"-"，或者把内部模型与请求 DTO 分开。只在命名回调返回空字符串，并不能替代跳过校验规则。

默认实例在回调返回空字符串时会回退到 Go 字段名；本文的回调主动返回 f.Name，使回退策略更加直观。若启用了改变空白名称行为的额外选项，应以该实例的具体配置为准。缺少 json 标签以及 json:",omitempty" 都没有显式别名，本例同样返回 Go 名称。

完成这项改造的关键是保持四个选择一致：构造实例时注册名称解析、校验规则仍来自 validate 标签、接口层读取适合的 Field 或 Namespace、内部诊断保留 StructField 或 StructNamespace。这样调整的是错误字段协议，不会意外改变校验规则。

参考：RegisterTagNameFunc 官方 API；结构体缓存与名称处理实现；FieldError 接口定义。