Go reflect.Value.Methods 怎样遍历可调用的方法集

如果你在写插件诊断器、对象能力检查或调试面板，想知道一个 Go 值“能调用哪些方法”，可以从 reflect.Value.Methods 开始。它返回的是一个可用 range 遍历的 iter.Seq2[reflect.Method, reflect.Value]：每次同时拿到方法描述和绑定了接收者的方法值。

真正容易出错的地方有三个：值和指针的反射结果可能不同；方法描述与方法值必须成对使用；Call 之前必须确认反射值有效、参数数量和参数类型都匹配。下面按一个“列出对象能力”的调试任务拆开。

先确认 Methods 返回的两部分结果

reflect.Method 更像方法的目录信息，包含 Name、Type 和 Func；同一对结果中的第二个 reflect.Value 是已经绑定当前接收者的方法值，后续调用时不需要再把接收者作为第一个参数传入。

先定义一个同时拥有值接收者和指针接收者的方法类型：

package main

import (
    "fmt"
    "reflect"
)

type Worker struct {
    Name string
}

// Label 是值接收者方法，适合展示不会修改对象的能力。
func (w Worker) Label() string {
    return "worker:" + w.Name
}

// Rename 是指针接收者方法，用于说明值反射与指针反射的差异。
func (w *Worker) Rename(name string) {
    // 先判断空指针，避免调试工具在探测能力时直接崩溃。
    if w == nil {
        return
    }
    w.Name = name
}

func listMethods(v reflect.Value) {
    // 无效 Value 没有具体类型，调用 Methods 前必须先退出。
    if !v.IsValid() {
        fmt.Println("invalid value")
        return
    }

    // 每一轮同时取得方法描述和绑定接收者的方法值。
    for method, value := range v.Methods() {
        fmt.Printf("%s: %s, callable=%t\n", method.Name, method.Type, value.IsValid())
    }
}

func main() {
    worker := Worker{Name: "alpha"}
    listMethods(reflect.ValueOf(worker))
    listMethods(reflect.ValueOf(&worker))
}

这里的关键不是把所有方法都调用一遍，而是先把方法名、签名和可调用值保存为一个清单。调试工具可以据此决定是否展示按钮，插件系统也可以据此做白名单匹配。

把方法名和值收集成可读清单

如果只想做诊断输出，可以把方法描述转换成轻量结构。注意不要把 reflect.Value 直接当成普通业务值保存太久；它仍然受原对象生命周期和可访问性规则约束。

type MethodInfo struct {
    Name string
    Type reflect.Type
    Func reflect.Value
}

func methodList(v reflect.Value) []MethodInfo {
    if !v.IsValid() {
        return nil
    }

    result := make([]MethodInfo, 0)
    for method, fn := range v.Methods() {
        // 保留方法描述和绑定后的函数值，调用时不需要重新查找接收者。
        result = append(result, MethodInfo{
            Name: method.Name,
            Type: method.Type,
            Func: fn,
        })
    }
    return result
}

返回结果为空不一定是错误：可能是类型没有导出方法，也可能是你传入了值而不是指针。先打印 v.Type() 和 v.Kind()，再决定是否需要调整入口。

按值类型和指针类型分别检查

这是最常见的“为什么少了一个方法”现象。reflect.ValueOf(worker) 得到的是不可寻址的值，能看到值接收者方法；reflect.ValueOf(&worker) 得到的是指针，通常能同时看到值接收者和指针接收者方法。

因此，方法清单里缺项时，第一张检查卡不是“反射坏了”，而是“调用方传入的到底是值还是指针”。如果工具希望展示完整的可修改能力，通常应明确接收指针；如果只做只读能力探测，则不要为了凑齐方法而随意取地址。

调用方法前先处理参数与错误边界

拿到方法值后，Call 的参数列表只包含业务参数，不包含接收者。下面只按名称调用一个无参方法，并在调用前检查方法值和签名：

func callLabel(v reflect.Value) (string, bool) {
    if !v.IsValid() {
        return "", false
    }

    for method, fn := range v.Methods() {
        if method.Name != "Label" {
            continue
        }
        // Label 没有业务参数；先核对签名，再执行 Call。
        if fn.Type().NumIn() != 0 || fn.Type().NumOut() != 1 {
            return "", false
        }
        out := fn.Call(nil)
        if len(out) != 1 || out[0].Kind() != reflect.String {
            return "", false
        }
        return out[0].String(), true
    }
    return "", false
}

带参数的方法要把参数包装成对应的 reflect.Value，例如 Rename 需要一个字符串。不要依赖字符串方法名就直接调用：方法可能不存在、方法值可能无效，或者参数类型并不匹配。反射调用的参数错误会以 panic 暴露，调试工具最好在边界层先过滤。

整理成调试检查清单

1. 先用 IsValid 排除零 reflect.Value，再读取类型和方法。
2. 用 range 同时接收 reflect.Method 与绑定后的方法值，不要把两者拆成两套索引。
3. 遇到方法缺失，先比较 ValueOf(value) 与 ValueOf(&value)，确认值/指针接收者。
4. 调用前核对 NumIn、NumOut 和每个参数的 Type。
5. 把可调用方法当作能力清单使用；不要把反射发现到的方法自动开放成外部命令。

常见问题

Methods 返回的第二个值是不是普通函数？

它是绑定了当前接收者的 reflect.Value，可用 Call 执行，但仍要遵守反射的参数和可访问性规则。

为什么值对象看不到指针方法？

因为方法集合和接收者类型有关。将值传给 ValueOf 与将指针传给 ValueOf，得到的集合可能不同。

Methods 为空是不是 API 调用失败？

不一定。类型没有可见方法、入口类型不对，或者值本身无效，都可能得到空结果；先检查 IsValid、Type 和值/指针形态。

把 Methods 当成“能力目录”而不是“自动执行器”，先列清单、再筛选、最后调用，反射代码会更容易调试。