Go 反射：类型、值、可修改性与工程边界

面向有 Java 经验的开发者，基于 Go 1.26。

反射允许程序在运行期检查类型和值。encoding/json 读取 struct tag，ORM 把查询结果填入结构体，依赖注入工具分析构造函数，背后都离不开 reflect。它看起来容易让人迷糊，其实问题通常出在三层概念没有分开：“静态接口值”“运行期类型描述”和“运行期值”。把这三层理清，再理解可寻址、可设置、方法集和 nil 的规则，大部分反射代码都可以逐步推导。

反射也不该成为普通业务代码的默认选项。能用接口、函数、高阶函数或泛型在编译期解决的问题，通常更容易理解和维护。因此这一章不只讲反射怎么写，还会反复确认它的边界：什么时候继续用，什么时候该停下来换一种设计。

1. 反射解决什么问题

反射适合“类型在编写这段代码时不能穷举”的场景：

序列化与反序列化；
struct tag 驱动的校验、映射和配置；
通用日志或调试工具；
RPC、ORM、依赖注入框架；
测试中的通用比较和构造；
插件边界、动态 schema 或协议适配。

不适合的常见场景：

只是为了少写几个类型断言；
已经有稳定接口，却绕过接口去读内部字段；
用字符串方法名模拟 Java 风格动态调用；
业务数据可以用泛型表达，却全部塞进 any；
每次请求都重复扫描同一个类型而不缓存。

反射会把一部分错误从编译期推迟到运行期。开始写之前，至少要回答几个问题：调用方输入不合法时返回什么错误，哪些操作可能 panic，类型元数据是否缓存，未导出字段又该如何处理。

2. 接口值：反射的入口

reflect.TypeOf 和 reflect.ValueOf 接收 any：

var x any = int64(42)

t := reflect.TypeOf(x)
v := reflect.ValueOf(x)

fmt.Println(t)           // int64
fmt.Println(v)           // 42
fmt.Println(v.Interface()) // 42

接口值可以理解为一对信息：

text

(动态类型, 动态值)

x 的静态类型是 any，动态类型是 int64，动态值是 42。反射观察的是动态部分。

把普通值传给 ValueOf 时会先装进接口，因此得到的 Value 通常表示一个副本，而不是原变量本身：

n := 10
v := reflect.ValueOf(n)

fmt.Println(v.CanSet()) // false

需要修改 n，必须把地址传进去，再取指针指向的元素：

v := reflect.ValueOf(&n).Elem()
fmt.Println(v.CanSet()) // true
v.SetInt(20)

3. `reflect.Type`

reflect.Type 是描述 Go 类型的接口。相同类型通常可直接用 == 比较：

t1 := reflect.TypeOf(int64(0))
t2 := reflect.TypeOf(int64(9))
fmt.Println(t1 == t2) // true

常见信息：

type UserID int64

t := reflect.TypeOf(UserID(7))
fmt.Println(t.Name())       // UserID
fmt.Println(t.PkgPath())    // 定义 UserID 的 package import path
fmt.Println(t.Kind())       // int64
fmt.Println(t.Size())       // 存储大小
fmt.Println(t.Align())      // 普通变量对齐
fmt.Println(t.Comparable()) // 是否可用 == 比较

3.1 获取一个只有类型、没有值的信息

旧代码常写：

t := reflect.TypeOf((*io.Reader)(nil)).Elem()

这里 (*io.Reader)(nil) 提供 *io.Reader 类型，Elem 得到接口类型 io.Reader。

现代 Go 可以用 TypeFor：

t := reflect.TypeFor[io.Reader]()

泛型工具中尤其清楚：

func typeName[T any]() string {
	return reflect.TypeFor[T]().String()
}

3.2 `Name`、`String` 和 `PkgPath`

Name() 返回定义类型在 package 中的名字；指针、slice、匿名 struct 等未命名类型返回空字符串；
String() 返回可读表示，但不保证能作为全局唯一键；
PkgPath() 区分不同 package 中同名的定义类型。

需要稳定标识定义类型时，通常组合 PkgPath 和 Name。不要把 String() 当成跨版本持久化协议。

3.3 类型关系

src.AssignableTo(dst)
src.ConvertibleTo(dst)
src.Implements(iface)
src.Comparable()

它们对应不同问题：

AssignableTo：不显式转换能否赋值；
ConvertibleTo：按语言规则能否显式转换；
Implements：类型是否实现接口；
Comparable：该类型的值能否参与 ==。

指针和值的方法集不同，检查接口实现时经常要同时考虑 T 和 *T：

t := reflect.TypeOf(MyType{})
pt := reflect.PointerTo(t)

fmt.Println(t.Implements(readerType))
fmt.Println(pt.Implements(readerType))

4. `reflect.Value`

reflect.Value 表示运行期的一个值。读取前要根据 Kind 选择对应方法：

v := reflect.ValueOf(int64(42))

fmt.Println(v.Int())       // 42
fmt.Println(v.Type())      // int64
fmt.Println(v.Kind())      // int64
fmt.Println(v.Interface()) // interface{}(int64(42))

读取方法按 kind 分组：

Bool；
Int：所有有符号整数；
Uint：所有无符号整数和 uintptr；
Float；
Complex；
String；
Bytes；
Len、Cap；
Index、Field、MapIndex；
Pointer、Elem、Indirect。

对错误 kind 调方法通常会 panic：

v := reflect.ValueOf("42")
// v.Int() // panic: call of reflect.Value.Int on string Value

反射 API 的契约大量由前置条件组成。框架边界应该先检查并返回带路径的错误，而不是让底层 panic 泄漏给用户。

4.1 `Interface`

raw := v.Interface()
n, ok := raw.(int64)

Interface() 把反射值重新装进 any。如果值来自另一个 package 的未导出字段，调用可能 panic；先检查 CanInterface()。

4.2 保留定义类型

type UserID int64

v := reflect.ValueOf(UserID(7))
fmt.Println(v.Int()) // 7

Int() 只返回底层数值 int64，会丢失 UserID 的定义类型信息。v.Interface() 的动态类型仍是 UserID。做通用复制或调用时不要只依据 kind 重新构造，否则会无意间抹掉定义类型。

5. `Kind` 与具体类型

Kind 是底层类别，不是完整类型：

type UserID int64
type OrderID int64

fmt.Println(reflect.TypeOf(UserID(1)).Kind())  // int64
fmt.Println(reflect.TypeOf(OrderID(1)).Kind()) // int64

两个类型 kind 相同，不代表可直接赋值，也不代表业务含义相同。

常见 kind 包括：

text

Bool, Int*, Uint*, Float*, Complex*,
Array, Chan, Func, Interface, Map, Pointer,
Slice, String, Struct, UnsafePointer

通用编码器通常先按 Kind 分派，再保留 Type 处理定义类型、接口和特殊类型：

switch v.Kind() {
case reflect.String:
	// ...
case reflect.Struct:
	if v.Type() == reflect.TypeFor[time.Time]() {
		// time.Time 的特殊协议
	}
}

6. nil、无效 `Value` 与 typed nil

6.1 真正的 nil 接口

var x any
fmt.Println(reflect.TypeOf(x)) // <nil>

v := reflect.ValueOf(x)
fmt.Println(v.IsValid()) // false

无效 Value 是反射中的“没有值”。除了少数方法（如 IsValid、String），对它调用其他方法可能 panic。

6.2 typed nil

var p *User
var x any = p

fmt.Println(x == nil)              // false
fmt.Println(reflect.TypeOf(x))     // *main.User
fmt.Println(reflect.ValueOf(x).IsNil()) // true

接口本身包含动态类型 *User，所以不等于 nil；动态值才是 nil。

6.3 `IsNil` 只支持部分 kind

IsNil 只能用于：

channel；
function；
interface；
map；
pointer；
slice。

下面会 panic：

v := reflect.ValueOf(0)
// v.IsNil()

通用判断：

func isNil(v reflect.Value) bool {
	if !v.IsValid() {
		return true
	}
	switch v.Kind() {
	case reflect.Chan, reflect.Func, reflect.Interface,
		reflect.Map, reflect.Pointer, reflect.Slice:
		return v.IsNil()
	default:
		return false
	}
}

6.4 `IsZero`

IsZero 判断值是否是其类型的零值。它不等同于“业务为空”：空但非 nil 的 slice 不是零值，数值 0 在某些业务中也可能是合法值。

7. 可寻址与可设置

这是反射最容易出错的一组规则。

7.1 `CanAddr`

值是否有可取得的地址：

v.CanAddr()

7.2 `CanSet`

值能否通过反射修改：

v.CanSet()

可设置通常要求：

值来自可寻址存储，例如指针指向的变量；
访问没有越过未导出字段的封装边界。

type Config struct {
	Port int
}

cfg := Config{Port: 8080}
rv := reflect.ValueOf(&cfg).Elem()
field := rv.FieldByName("Port")

fmt.Println(field.CanAddr()) // true
fmt.Println(field.CanSet())  // true
field.SetInt(9090)

传值则不可设置：

rv := reflect.ValueOf(cfg)
fmt.Println(rv.FieldByName("Port").CanSet()) // false

未导出字段即使可寻址，也不能通过安全反射 API 设置。不要用 unsafe 绕过，标准库对未导出字段的限制是 package 封装的一部分。

7.3 `Set` 和专用 setter

field.Set(reflect.ValueOf(9090))
field.SetInt(9090)
field.SetString("value")
field.SetBool(true)

Set 要求类型可赋值，不会自动做任意转换：

type Port int
field.Set(reflect.ValueOf(Port(9090))) // 若 field 类型是 Port

如果输入只是底层 int，要先确认 ConvertibleTo，再显式 Convert。

8. 指针与间接取值

Elem 用于 pointer 或 interface：

p := new(int)
*p = 42
v := reflect.ValueOf(p)

fmt.Println(v.Kind())        // ptr
fmt.Println(v.Elem().Kind()) // int

reflect.Indirect(v) 在 v 是非 nil pointer 时等价于 v.Elem()，不是 pointer 时返回 v，nil pointer 时返回无效 Value。

通用代码常要剥离多层 pointer/interface：

func indirect(v reflect.Value) reflect.Value {
	for v.IsValid() &&
		(v.Kind() == reflect.Pointer || v.Kind() == reflect.Interface) {
		if v.IsNil() {
			return reflect.Value{}
		}
		v = v.Elem()
	}
	return v
}

是否应该自动解引用取决于协议。例如 JSON 中 nil *int 和 new(0) 表达的字段存在性不同，不能为了“方便”把它们都归为 0。

需要给 nil pointer 分配元素：

if field.Kind() == reflect.Pointer && field.IsNil() {
	field.Set(reflect.New(field.Type().Elem()))
}

9. struct 字段、嵌入与标签

9.1 类型信息和数值信息

type User struct {
	ID   int64  `json:"id" validate:"gt=0"`
	Name string `json:"name,omitempty" validate:"required"`
}

t := reflect.TypeOf(User{})
v := reflect.ValueOf(User{ID: 7, Name: "Alice"})

sf := t.Field(0) // StructField，字段元数据
fv := v.Field(0) // Value，具体对象中的字段值

StructField 常用字段：

sf.Name
sf.Type
sf.Tag
sf.Index
sf.Anonymous
sf.PkgPath // 非空通常表示未导出
sf.Offset

9.2 标签

jsonName, ok := sf.Tag.Lookup("json")
validateRule := sf.Tag.Get("validate")

Get 在不存在时返回空字符串，无法区分“不存在”和“值为空”；
Lookup 返回 (value, exists)。

标签是字符串协议，编译器不会验证业务格式。go vet 能发现一部分 struct tag 语法问题，但自定义规则仍需要测试。

解析 json:"name,omitempty"：

parts := strings.Split(sf.Tag.Get("json"), ",")
name := parts[0]

实际框架还要处理 "-"、空字段名、选项去重、嵌入冲突等规则。不要假设所有 tag 都遵循 JSON 的格式。

9.3 按名字查字段

sf, ok := t.FieldByName("Name")
fv := v.FieldByName("Name")

嵌入可能造成同层名字冲突，FieldByName 会按语言提升规则查找。框架如果需要稳定 schema，通常在初始化阶段递归扫描并保存 sf.Index：

fv := v.FieldByIndex(sf.Index)

遇到 nil 嵌入指针时，FieldByIndex 可能 panic。Go 也提供返回错误的相关 API，或由调用方逐级处理并按需要分配。

9.4 字段布局

Offset、Size 和 Align 能观察字段布局，但不应该把进程内布局当成磁盘或网络协议。跨版本、架构和编译器的稳定格式应使用明确编码规则。

10. slice、array、map 与 channel

10.1 slice 和 array

v.Len()
v.Cap()
v.Index(i)
v.Slice(i, j)
v.Slice3(i, j, k)

创建与追加：

t := reflect.TypeOf([]int{})
s := reflect.MakeSlice(t, 0, 4)
s = reflect.Append(s, reflect.ValueOf(1))
s = reflect.AppendSlice(s, reflect.ValueOf([]int{2, 3}))

reflect.Append 和内建 append 一样可能返回新的 slice 值，必须接住返回值。

10.2 map

m := reflect.MakeMapWithSize(reflect.TypeOf(map[string]int{}), 8)
m.SetMapIndex(reflect.ValueOf("a"), reflect.ValueOf(1))

got := m.MapIndex(reflect.ValueOf("a"))
missing := m.MapIndex(reflect.ValueOf("missing"))
fmt.Println(got.IsValid())     // true
fmt.Println(missing.IsValid()) // false

删除 map 元素时把无效 Value 作为值：

m.SetMapIndex(key, reflect.Value{})

遍历可使用 MapRange，顺序与普通 map 一样未指定：

iter := m.MapRange()
for iter.Next() {
	fmt.Println(iter.Key(), iter.Value())
}

map 元素通常不可寻址。不能取出 struct 元素后原地设置字段；要复制出来、修改，再写回 map。

10.3 channel

ch := reflect.MakeChan(reflect.ChanOf(reflect.BothDir, elemType), 1)
ch.Send(value)
got, ok := ch.Recv()
ch.Close()

reflect.Select 可以在运行期数量的 channel 上执行 select：

chosen, recv, ok := reflect.Select(cases)

如果 channel 集合在编译期已知，普通 select 更清楚、更安全。动态 fan-in 是 reflect.Select 比较合理的使用场景之一。

11. 函数与方法

11.1 调用函数

fn := reflect.ValueOf(strings.TrimSpace)
out := fn.Call([]reflect.Value{
	reflect.ValueOf("  go  "),
})
fmt.Println(out[0].String())

Call 的参数数量和类型必须匹配，否则 panic。可变参数可以使用 CallSlice。

反射调用没有编译期参数检查，开销也高于普通调用。框架应该在注册阶段验证函数签名，构建调用计划；请求路径只执行已验证计划。

11.2 方法

类型级：

method, ok := t.MethodByName("String")

值级：

method := v.MethodByName("String")
result := method.Call(nil)

值方法和指针方法属于不同方法集：

v := reflect.ValueOf(User{})
pv := reflect.ValueOf(&User{})

pv 可能找到只定义在 *User 上的方法，而 v 找不到。普通 Go 调用中的自动取地址只是编译器语法便利，反射不会在所有场景替你完成。

通过反射暴露按字符串调用任意方法会扩大攻击面。方法白名单、参数限制和权限校验必须在反射层之外明确完成。

11.3 创建函数

reflect.MakeFunc 用运行期类型包装一个通用实现：

funcType := reflect.TypeOf(func(int, int) int { return 0 })
swap := reflect.MakeFunc(funcType, func(args []reflect.Value) []reflect.Value {
	return []reflect.Value{reflect.ValueOf(args[1].Int() + args[0].Int())}
})

这适合框架胶水，不适合普通业务逻辑。泛型函数或闭包通常更易读。

12. 运行期创建类型和值

创建值：

reflect.Zero(t)     // T 的零值，不可设置
reflect.New(t)      // *T，新值的 Elem 可设置
reflect.NewAt(t, p) // 使用 unsafe 指针，属于底层工具边界

创建复合类型：

reflect.PointerTo(t)
reflect.SliceOf(t)
reflect.ArrayOf(n, t)
reflect.MapOf(key, elem)
reflect.ChanOf(dir, t)
reflect.FuncOf(in, out, variadic)
reflect.StructOf(fields)

动态 struct 示例：

t := reflect.StructOf([]reflect.StructField{
	{
		Name: "Name",
		Type: reflect.TypeFor[string](),
		Tag:  `json:"name"`,
	},
})

v := reflect.New(t).Elem()
v.Field(0).SetString("Alice")

动态类型适合 schema 驱动的边界层，但有明显限制：

编译期代码无法写出这个具体类型；
方法、嵌入和未导出字段有额外约束；
API 容易退化为 any；
类型数量无界时会持续占用运行期元数据。

能在生成阶段确定 schema 时，代码生成通常更适合。

13. 转换、赋值与比较

13.1 赋值

if src.Type().AssignableTo(dst.Type()) {
	dst.Set(src)
}

13.2 转换

if src.Type().ConvertibleTo(dst.Type()) {
	dst.Set(src.Convert(dst.Type()))
}

“可以转换”不代表业务上安全。例如 int64 转 int8 可能截断，[]byte 和 string 转换可能产生分配。通用绑定器要额外做范围和协议检查。

13.3 比较

if v.Comparable() {
	fmt.Println(v.Interface() == other.Interface())
}

Type.Comparable 描述类型，Value.Comparable 考虑接口值中动态值等运行期情况。对于深层业务等价，仍需明确规则，不能简单把 DeepEqual 当作万能答案。

13.4 溢出检查

if field.OverflowInt(n) {
	return fmt.Errorf("%d overflows %s", n, field.Type())
}
field.SetInt(n)

对应还有 OverflowUint、OverflowFloat、OverflowComplex。

14. Go 1.26 的反射迭代器

Go 1.26 为 reflect.Type 和 reflect.Value 增加了一组迭代器方法：

Type.Fields：遍历 struct 字段；
Type.Methods：遍历方法；
Type.Ins、Type.Outs：遍历函数输入和输出类型；
Value.Fields：遍历字段元数据和字段值；
Value.Methods：遍历方法元数据和方法值。

示意：

t := reflect.TypeOf(User{})
for field := range t.Fields() {
	fmt.Println(field.Name, field.Type)
}

值迭代器同时给出元数据和值：

v := reflect.ValueOf(User{ID: 7, Name: "Alice"})
for field, value := range v.Fields() {
	fmt.Println(field.Name, value.Interface())
}

这些 API 减少了手写 for i := 0; i < t.NumField(); i++ 的索引样板代码，也更适合与 Go 的 iter 生态组合。维护支持旧 Go 版本的库时，仍要使用 NumField/Field(i)，或通过构建标签隔离新版实现。

迭代器没有改变可见性和可设置规则。遍历到未导出字段，不代表可以 Interface 或 Set。

15. 一个可复用的结构体校验器

下面实现一个小型 required 校验器，重点是展示反射边界的组织方式：

type FieldError struct {
	Path string
	Rule string
}

func (e *FieldError) Error() string {
	return e.Path + ": failed " + e.Rule
}

func ValidateRequired(input any) error {
	v := reflect.ValueOf(input)
	if !v.IsValid() {
		return errors.New("validate: nil input")
	}

	for v.Kind() == reflect.Pointer {
		if v.IsNil() {
			return errors.New("validate: nil pointer")
		}
		v = v.Elem()
	}

	if v.Kind() != reflect.Struct {
		return fmt.Errorf("validate: expected struct, got %s", v.Type())
	}

	t := v.Type()
	for i := 0; i < t.NumField(); i++ {
		sf := t.Field(i)
		if sf.PkgPath != "" { // 未导出字段
			continue
		}
		if sf.Tag.Get("validate") != "required" {
			continue
		}

		fv := v.Field(i)
		if fv.IsZero() {
			return &FieldError{Path: sf.Name, Rule: "required"}
		}
	}
	return nil
}

使用：

type Request struct {
	Name string `validate:"required"`
}

err := ValidateRequired(Request{})

真实校验器还要决定：

空 slice 是否等于缺失；
数值 0 是否允许；
是否递归嵌套 struct；
pointer 为 nil 时如何报告路径；
多个错误一次返回还是遇到第一个停止；
嵌入字段和标签重命名规则；
循环引用如何避免无限递归；
自定义类型能否实现校验接口；
类型扫描结果如何缓存。

一个重要的扩展点是先检查显式接口：

type Validator interface {
	Validate() error
}

能通过接口完成的类型特定逻辑，不必硬编码进反射 switch。

16. 性能、缓存与并发安全

反射的成本来自：

动态 kind 分派；
Interface 装箱；
Call 参数和返回值 slice；
tag 解析和字段搜索；
可能的分配；
编译器难以内联和优化动态路径。

优化顺序：

先确认反射真在热点；
把类型扫描放到注册或首次使用；
缓存不可变元数据；
请求路径按预计算索引访问字段；
避免不必要的 Interface()；
仍然过慢时考虑泛型或代码生成。

缓存示例：

type fieldPlan struct {
	index []int
	name  string
}

var plans sync.Map // map[reflect.Type][]fieldPlan

func planFor(t reflect.Type) []fieldPlan {
	if cached, ok := plans.Load(t); ok {
		return cached.([]fieldPlan)
	}
	plan := buildPlan(t)
	actual, _ := plans.LoadOrStore(t, plan)
	return actual.([]fieldPlan)
}

缓存值发布后应视为不可变。不能一边让 goroutine 读取 slice，一边追加字段。

reflect.Type 可以并发使用。reflect.Value 能否并发使用，取决于它代表的底层值是否允许同等方式的并发访问；反射不会自动提供同步。

用基准验证：

bash

go test -bench=. -benchmem

不要凭“反射一定慢”提前做复杂代码生成，也不要凭小数据演示认为反射成本永远可以忽略。

17. 反射、泛型和代码生成如何选择

条件	更合适的工具
操作行为可由小接口表达	接口
类型集合在编译期已知，算法相同	泛型
schema 在构建期可获得，热点明显	代码生成
类型只在运行期到达	反射
少量类型特例	类型 switch
仅减少重复样板	先考虑普通函数或生成工具

泛型保留静态类型并让编译器检查调用：

func Keys[M ~map[K]V, K comparable, V any](m M) []K

反射能处理“调用者传来任意 struct，并按 tag 解释”：

func Encode(v any) ([]byte, error)

两者可以组合：外层反射建立一次类型计划，内层生成或泛型代码执行热点操作。不要把“框架入口需要反射”推导成“框架内部所有值都必须是 any”。

18. 安全边界

18.1 不要突破未导出字段

用 unsafe 修改未导出字段会破坏 package 不变量，也可能被运行时或编译器变化打破。序列化器应跳过未导出字段。

18.2 限制递归和输入规模

攻击者控制的深层结构、巨大 slice 或循环对象图可能导致栈耗尽和内存耗尽。通用遍历器应：

设置最大深度；
对集合长度设上限；
记录访问过的 pointer，检测环；
支持 context 或预算；
避免把任意值格式化成无限字符串。

18.3 动态调用白名单

不要把 HTTP 参数直接作为 MethodByName 的方法名执行。即使只能找到导出方法，也可能调用不应公开的管理操作。

18.4 避免泄漏敏感字段

通用日志反射遍历 struct 时必须支持脱敏或跳过标记。字段“已导出”只说明 Go 可见性，不说明可以写入日志。

19. 与 Java 反射的差异

Java	Go
`Class<?>`	`reflect.Type`
`Field` + 对象	`StructField` + `reflect.Value`
`Method.invoke`	`Value.Call` / 方法 Value
annotation	struct tag（能力更简单）
`setAccessible(true)`	安全反射不提供同等绕过；不要用 unsafe 模拟
泛型类型擦除	Go 类型参数编译实现不同，反射看具体实例化类型
class 构造器	`reflect.New` 只分配零值，没有语言级构造器

Go 的方法集和值/指针接收者是 Java 开发者最容易忽略的差异。T 和 *T 在接口实现与方法查找上可能不同。

20. 常见 panic 与排查方法

`reflect: call of ... on zero Value`

来源通常是 ValueOf(nil)、没找到字段/方法、map key 不存在后继续读取。先 IsValid()。

`reflect.Value.Interface: cannot return value obtained from unexported field`

遍历到了未导出字段。检查 StructField.PkgPath 或 CanInterface()。

`reflect.Value.Set using unaddressable value`

传入的是值副本。传指针并 Elem()，再检查 CanSet()。

`reflect.Set: value of type X is not assignable to type Y`

Kind 相同不代表类型可赋值。使用 AssignableTo；协议允许转换时再使用 ConvertibleTo。

`reflect: call of Value.IsNil on ... Value`

只在支持 nil 的 kind 上调用 IsNil。

方法找不到

检查：

方法是否导出；
当前是 T 还是 *T；
是否拿到了 interface 包装层而未 Elem；
方法名大小写是否正确。

排查模板

fmt.Printf(
	"valid=%v type=%v kind=%v addr=%v set=%v interface=%v\n",
	v.IsValid(),
	func() any {
		if !v.IsValid() { return nil }
		return v.Type()
	}(),
	func() any {
		if !v.IsValid() { return nil }
		return v.Kind()
	}(),
	v.IsValid() && v.CanAddr(),
	v.IsValid() && v.CanSet(),
	v.IsValid() && v.CanInterface(),
)

21. 速查表

目标	API
从值取类型	`reflect.TypeOf(v)`
从类型参数取类型	`reflect.TypeFor[T]()`
从值进入反射	`reflect.ValueOf(v)`
反射值回到接口	`v.Interface()`
判断有效	`v.IsValid()`
判断支持 nil 的值是否 nil	`v.IsNil()`
判断零值	`v.IsZero()`
指针/接口取元素	`v.Elem()`
判断可修改	`v.CanSet()`
修改	`v.Set(x)` / `SetInt` 等
struct 字段	`t.Field(i)` / `v.Field(i)`
标签	`field.Tag.Get` / `Lookup`
map 读取	`v.MapIndex(key)`
map 写入	`v.SetMapIndex(key, value)`
动态调用	`v.Call(args)`
接口实现	`t.Implements(iface)`
可赋值	`src.AssignableTo(dst)`
可转换	`src.ConvertibleTo(dst)`
新值	`reflect.New(t)`
零值	`reflect.Zero(t)`
动态 slice	`reflect.MakeSlice`
动态 map	`reflect.MakeMapWithSize`
动态 select	`reflect.Select`

可运行示例

反射的难点不在于记住 API，而在于每一步都检查 Kind、有效性、可设置性和签名。下面三个程序把这些检查放在真正发生读写的边界上。

示例一：为什么 Value 能读却不能 Set

先看最常见的疑问：同一个结构体字段，从结构体值取得时 CanSet 为什么是 false，从指针的 Elem 取得时却可以安全修改。

package main

import (
	"fmt"
	"reflect"
)

type Profile struct {
	Name string
	Age  int
}

func main() {
	profile := Profile{Name: "Ada", Age: 30}

	copyValue := reflect.ValueOf(profile)
	fmt.Println("结构体副本可设置:", copyValue.FieldByName("Name").CanSet())

	// ValueOf(&profile) 得到的是指针值；Elem 才是指针指向、可寻址的结构体。
	// 只有导出字段可由当前包外的通用反射工具修改。
	target := reflect.ValueOf(&profile).Elem()
	nameField := target.FieldByName("Name")
	fmt.Println("指针目标可设置:", nameField.CanSet())

	if nameField.IsValid() && nameField.CanSet() && nameField.Kind() == reflect.String {
		nameField.SetString("Grace")
	}

	fmt.Printf("修改后: %+v\n", profile)
}

运行：

bash

go run ./examples/ch18/settable

预期输出：

text

结构体副本可设置: false
指针目标可设置: true
修改后: {Name:Grace Age:30}

拆解：

reflect.ValueOf(profile) 包装的是接口中的结构体副本，修改它无法回写原变量，因此不可设置。
ValueOf(&profile).Elem() 指向可寻址的原结构体，导出字段才可能 CanSet。
FieldByName 可能返回无效值；调用 SetString 前依次检查 IsValid、CanSet 和 Kind，避免 panic。
反射不能成为绕过封装的借口。未导出字段、跨包私有状态和不可信字段名都应被拒绝。

修改实验：把 Name 改成未导出的 name，观察 CanSet；再尝试传入 (*Profile)(nil)，为工具函数补上 nil 指针检查。

示例二：读取结构体标签做边界校验

第二个例子从 validate 标签读取 required 和 min 规则，并一次性返回多个字段错误。重点不是做出一个完整校验库，而是看清类型信息和值如何配合。

package main

import (
	"fmt"
	"reflect"
	"strconv"
	"strings"
)

type Input struct {
	Name string `validate:"required"`
	Age  int    `validate:"min=18"`
	Note string
}

// Validate 演示一个刻意受限的标签校验器。
// 它只接受非空结构体值，且只解释自己认识的规则；真实项目应优先选成熟库，
// 因为递归结构、指针、切片元素和错误路径都会显著增加实现复杂度。
func Validate(value any) []error {
	v := reflect.ValueOf(value)
	if v.Kind() == reflect.Pointer {
		if v.IsNil() {
			return []error{fmt.Errorf("不能校验 nil 指针")}
		}
		v = v.Elem()
	}
	if v.Kind() != reflect.Struct {
		return []error{fmt.Errorf("只支持结构体，实际是 %s", v.Kind())}
	}

	var errs []error
	t := v.Type()
	for i := 0; i < v.NumField(); i++ {
		fieldInfo := t.Field(i)
		rules := strings.Split(fieldInfo.Tag.Get("validate"), ",")
		for _, rule := range rules {
			switch {
			case rule == "", rule == "-":
				continue
			case rule == "required":
				if v.Field(i).IsZero() {
					errs = append(errs, fmt.Errorf("%s: 必填", fieldInfo.Name))
				}
			case strings.HasPrefix(rule, "min="):
				min, err := strconv.ParseInt(strings.TrimPrefix(rule, "min="), 10, 64)
				if err != nil {
					errs = append(errs, fmt.Errorf("%s: 非法规则 %q", fieldInfo.Name, rule))
					continue
				}
				if v.Field(i).Kind() != reflect.Int || v.Field(i).Int() < min {
					errs = append(errs, fmt.Errorf("%s: 不能小于 %d", fieldInfo.Name, min))
				}
			default:
				errs = append(errs, fmt.Errorf("%s: 未知规则 %q", fieldInfo.Name, rule))
			}
		}
	}
	return errs
}

func main() {
	input := Input{Age: 16}
	for _, err := range Validate(input) {
		fmt.Println(err)
	}
}

运行：

bash

go run ./examples/ch18/tag-validation

预期输出：

text

Name: 必填
Age: 不能小于 18

拆解：

reflect.Type 提供字段声明和标签，reflect.Value 提供本次输入的实际值，两者按字段索引对应。
入口先解引用非 nil 指针，并拒绝非结构体，避免后续 NumField panic。
未识别规则不会静默忽略，而是作为配置错误返回；否则拼错标签会让校验悄悄失效。
这个实现刻意只支持 int 的 min。通用校验库还要处理字符串长度、数值宽度、嵌套路径、切片元素和循环指针，复杂度远高于几个 switch。

修改实验：为字符串增加 minlen=3；给 Input 增加嵌套结构体，先写清 nil 和错误路径语义，再决定是否递归。

示例三：先校验签名，再进行反射调用

插件式分发器需要在运行时登记函数，但任意值或错误签名不能一直潜伏到第一次请求才 panic。最后一个例子把签名校验提前到注册阶段。

package main

import (
	"fmt"
	"reflect"
)

type Dispatcher struct {
	handlers map[string]reflect.Value
}

func NewDispatcher() *Dispatcher {
	return &Dispatcher{handlers: make(map[string]reflect.Value)}
}

// Register 在系统边界提前验证函数签名。
// 这样 Call 不需要对任意函数做盲目反射调用，也不会把 panic 当控制流。
func (d *Dispatcher) Register(name string, handler any) error {
	value := reflect.ValueOf(handler)
	if value.Kind() != reflect.Func {
		return fmt.Errorf("%q 不是函数", name)
	}
	typ := value.Type()
	errorType := reflect.TypeFor[error]()
	if typ.NumIn() != 1 || typ.In(0).Kind() != reflect.String ||
		typ.NumOut() != 2 || typ.Out(0).Kind() != reflect.String ||
		!typ.Out(1).Implements(errorType) {
		return fmt.Errorf("%q 的签名必须是 func(string) (string, error)", name)
	}
	d.handlers[name] = value
	return nil
}

func (d *Dispatcher) Call(name, input string) (string, error) {
	handler, ok := d.handlers[name]
	if !ok {
		return "", fmt.Errorf("处理器 %q 未注册", name)
	}

	results := handler.Call([]reflect.Value{reflect.ValueOf(input)})
	if !results[1].IsNil() {
		return "", results[1].Interface().(error)
	}
	return results[0].String(), nil
}

func main() {
	dispatcher := NewDispatcher()
	if err := dispatcher.Register("greet", func(name string) (string, error) {
		if name == "" {
			return "", fmt.Errorf("名字不能为空")
		}
		return "你好，" + name, nil
	}); err != nil {
		panic(err)
	}

	message, err := dispatcher.Call("greet", "Go")
	fmt.Printf("结果=%q, 错误=%v\n", message, err)

	_, err = dispatcher.Call("missing", "Go")
	fmt.Println("未知调用:", err)
}

运行：

bash

go run ./examples/ch18/safe-dispatch

预期输出：

text

结果="你好，Go", 错误=<nil>
未知调用: 处理器 "missing" 未注册

拆解：

Register 只接受精确的 func(string) (string, error)，错误尽早发生在配置阶段。
reflect.TypeFor[error]() 得到接口类型，再用 Implements 判断第二个返回值能否作为 error。
Call 只能访问注册表中的白名单处理器，并构造已验证类型的参数，因此不会把外部 JSON 任意转换成反射调用。
反射函数内部仍可能 panic。服务边界若要恢复 panic，应记录堆栈并隔离单个请求，但不能把恢复当成替代输入验证的手段。

修改实验：尝试注册 func(int) string 并打印注册错误；随后给分发器加 sync.RWMutex，支持运行期间并发注册与调用，再用 go test -race 验证。

22. 练习

编写 Dump(v any)，递归打印导出字段名、类型和值；增加最大深度和循环引用检测。
实现配置加载器：按 env:"PORT" 标签把字符串环境变量写入 struct，支持 string、bool、整数、指针和清晰的字段路径错误。
给校验器增加 min、max 和嵌套 struct，缓存字段计划并写基准。
用 reflect.Select 合并运行期数量的 <-chan T，再比较使用 goroutine 转发的泛型实现。
分别用接口、泛型、反射实现一个求和工具，比较 API、错误发现阶段和基准结果。
使用 Go 1.26 的 Type.Fields 重写字段扫描，并为旧版 Go 设计兼容方案。

Go 反射：类型、值、可修改性与工程边界 ​

目录

1. 反射解决什么问题 ​

2. 接口值：反射的入口 ​

3. reflect.Type ​

3.1 获取一个只有类型、没有值的信息 ​

3.2 Name、String 和 PkgPath ​

3.3 类型关系 ​

4. reflect.Value ​

4.1 Interface ​

4.2 保留定义类型 ​

5. Kind 与具体类型 ​

6. nil、无效 Value 与 typed nil ​

6.1 真正的 nil 接口 ​

6.2 typed nil ​

6.3 IsNil 只支持部分 kind ​

6.4 IsZero ​

7. 可寻址与可设置 ​

7.1 CanAddr ​

7.2 CanSet ​

7.3 Set 和专用 setter ​

8. 指针与间接取值 ​

9. struct 字段、嵌入与标签 ​

9.1 类型信息和数值信息 ​

9.2 标签 ​

9.3 按名字查字段 ​

9.4 字段布局 ​

10. slice、array、map 与 channel ​

10.1 slice 和 array ​

10.2 map ​

10.3 channel ​

11. 函数与方法 ​

11.1 调用函数 ​

11.2 方法 ​

11.3 创建函数 ​

12. 运行期创建类型和值 ​

13. 转换、赋值与比较 ​

13.1 赋值 ​

13.2 转换 ​

13.3 比较 ​

13.4 溢出检查 ​

14. Go 1.26 的反射迭代器 ​

15. 一个可复用的结构体校验器 ​

16. 性能、缓存与并发安全 ​

17. 反射、泛型和代码生成如何选择 ​

18. 安全边界 ​

18.1 不要突破未导出字段 ​

18.2 限制递归和输入规模 ​

18.3 动态调用白名单 ​

18.4 避免泄漏敏感字段 ​

19. 与 Java 反射的差异 ​

20. 常见 panic 与排查方法 ​

reflect: call of ... on zero Value ​

reflect.Value.Interface: cannot return value obtained from unexported field ​

reflect.Value.Set using unaddressable value ​

reflect.Set: value of type X is not assignable to type Y ​

reflect: call of Value.IsNil on ... Value ​

方法找不到 ​

排查模板 ​

21. 速查表 ​

可运行示例 ​

示例一：为什么 Value 能读却不能 Set ​

示例二：读取结构体标签做边界校验 ​

示例三：先校验签名，再进行反射调用 ​

22. 练习 ​

23. 官方资料 ​

Go 反射：类型、值、可修改性与工程边界

1. 反射解决什么问题

2. 接口值：反射的入口

3. `reflect.Type`

3.1 获取一个只有类型、没有值的信息

3.2 `Name`、`String` 和 `PkgPath`

3.3 类型关系

4. `reflect.Value`

4.1 `Interface`

4.2 保留定义类型

5. `Kind` 与具体类型

6. nil、无效 `Value` 与 typed nil

6.1 真正的 nil 接口

6.2 typed nil

6.3 `IsNil` 只支持部分 kind

6.4 `IsZero`

7. 可寻址与可设置

7.1 `CanAddr`

7.2 `CanSet`

7.3 `Set` 和专用 setter

8. 指针与间接取值

9. struct 字段、嵌入与标签

9.1 类型信息和数值信息

9.2 标签

9.3 按名字查字段

9.4 字段布局

10. slice、array、map 与 channel

10.1 slice 和 array

10.2 map

10.3 channel

11. 函数与方法

11.1 调用函数

11.2 方法

11.3 创建函数

12. 运行期创建类型和值

13. 转换、赋值与比较

13.1 赋值

13.2 转换

13.3 比较

13.4 溢出检查

14. Go 1.26 的反射迭代器

15. 一个可复用的结构体校验器

16. 性能、缓存与并发安全

17. 反射、泛型和代码生成如何选择

18. 安全边界

18.1 不要突破未导出字段

18.2 限制递归和输入规模

18.3 动态调用白名单

18.4 避免泄漏敏感字段

19. 与 Java 反射的差异

20. 常见 panic 与排查方法

`reflect: call of ... on zero Value`

`reflect.Value.Interface: cannot return value obtained from unexported field`

`reflect.Value.Set using unaddressable value`

`reflect.Set: value of type X is not assignable to type Y`

`reflect: call of Value.IsNil on ... Value`

方法找不到

排查模板

21. 速查表

可运行示例

示例一：为什么 Value 能读却不能 Set

示例二：读取结构体标签做边界校验

示例三：先校验签名，再进行反射调用

22. 练习

23. 官方资料