Go reflect.VisibleFields 怎么处理嵌入字段冲突

处理带匿名嵌入的结构体时，reflect.VisibleFields 不会把所有物理字段都原样返回。它模拟的是字段能否直接通过 FieldByName 找到：外层同名字段优先，同一嵌入深度的同名字段互相抵消，只有最终可见的字段才会出现在结果中。理解这条规则后，反射遍历就不会把隐藏字段误当成可读字段。

结论：把嵌入字段的层级看成查找深度。浅层同名字段覆盖深层字段；两个字段处在同一深度且名字相同，则两者都不可见。读取结果时使用返回的 StructField.Index，不要自己拼字段下标。

本文要解决：Go 反射遍历嵌入结构时，怎么判断冲突结果，以及怎样用正确的索引取值。

VisibleFields 解决了什么遍历问题

普通的 Type.Field(i) 只能看到当前结构体直接声明的字段，手动递归匿名字段又容易漏掉深度规则。Go 1.17 起，VisibleFields 接收一个结构体类型，返回能被 FieldByName 直接访问的字段，并保留匿名字段内部的可见字段和未导出字段。返回顺序仍遵循结构体声明顺序，匿名字段后紧跟它提升出来的字段。

因此它适合做通用日志、表单映射或字段元数据遍历，但不等价于“递归收集全部字段”。冲突字段被排除，正是为了和 Go 的名称查找语义一致。

同名字段为什么会被隐藏

下面的例子故意放入两种冲突：Left.ID 和 Right.ID 位于同一深度；如果再声明外层 ID，它就比嵌入字段浅一层。

package main

import (
    "fmt"
    "reflect"
)

type Left struct {
    ID int
    Name string
}

type Right struct {
    ID int
    Code string
}

type Outer struct {
    Left       // 左侧嵌入字段，内部 ID 深度更深
    Right      // 右侧嵌入字段，内部 ID 与 Left.ID 同层
    Local bool // 直接字段，不参与嵌入冲突
}

func main() {
    typ := reflect.TypeOf(Outer{})
    for _, field := range reflect.VisibleFields(typ) {
        // Index 是从 Outer 走到该字段的完整路径。
        fmt.Printf("name=%s anonymous=%v index=%v\\n", field.Name, field.Anonymous, field.Index)
    }
}

结果中会保留 Left、Name、Right、Code 和 Local，两个 ID 都不会出现。原因不是声明顺序，而是它们处在相同嵌入深度，名称查找无法选择其中一个。如果给 Outer 增加 ID string，外层字段会保留，两个嵌入的 ID 则被更浅的字段隐藏。

用 Index 读取真正可见的字段

StructField.Index 是一个下标路径。例如嵌入在第 0 个字段中的 Name，索引可能是 [0, 1]。拿到结构体值后，用 Value.FieldByIndex(field.Index) 取值，能够跟随 VisibleFields 的裁决结果。

func printVisible(value any) {
    rv := reflect.ValueOf(value)
    if rv.Kind() != reflect.Struct {
        return // VisibleFields 只接受结构体类型
    }

    for _, field := range reflect.VisibleFields(rv.Type()) {
        // 这里的索引已包含嵌入路径，不要只使用 FieldByName。
        fv := rv.FieldByIndex(field.Index)
        fmt.Printf("%s = %v\\n", field.Name, fv.Interface())
    }
}

如果匿名字段是指针，索引路径中途遇到 nil 指针，FieldByIndex 可能触发 panic。读取外部输入或可选配置时，应先保证嵌入指针已初始化，或者在 Go 1.18 及以后使用 FieldByIndexErr 获取错误，再决定跳过该字段还是补齐对象。

写反射遍历时保留这张判断表

两个容易误判的边界

VisibleFields 会返回未导出字段吗？会。它描述的是反射层面的可见字段集合，不等于当前包可以安全调用 Interface。对未导出字段继续取接口值前，要考虑包边界和 CanInterface。

能用字段名去重替代它吗？不建议。只按名字去重无法表达“同层抵消”和“浅层覆盖”，还会丢失嵌入路径。让标准库先给出可见集合，再用 Index 定位，是更稳定的实现方式。