用反射实现插件注册时限制允许的方法签名

用反射做插件注册时，最重要的不是“找得到同名方法”，而是注册阶段就确认它的完整签名。对约定为 Handle(context.Context, []byte) ([]byte, error) 的插件，应当先取得绑定后的方法值，再将它的 reflect.Type 与允许函数类型做精确比较；参数类型、返回值、顺序或变参属性只要不同，就立即拒绝注册。

Go reflect 官方文档：https://pkg.go.dev/reflect

不要把签名错误拖到 reflect.Value.Call。注册器越早拒绝，错误越接近插件定义，定位成本也越低。

影响面：一个“注册成功”的插件让调用链突然崩溃

我遇到这个问题时，注册器看起来一直很稳定：配置里写入插件名，启动日志显示注册完成，直到第一条请求命中插件才 panic。最初我们以为是业务数据异常，后来才发现插件虽然有一个叫 Handle 的方法，参数却是 string，而调用器固定传入 []byte。

type BrokenPlugin struct{}

// Handle 名称正确，但第二个参数错误地写成了 string。
func (*BrokenPlugin) Handle(ctx context.Context, payload string) ([]byte, error) {
	return []byte(payload), nil
}

只用 MethodByName("Handle") 判断方法存在时，这个插件会通过。真正调用时，反射要求传入值可赋给对应参数；[]byte 不能赋给 string，于是问题从“可返回的注册错误”升级成了运行时 panic。它影响的不只是当前插件，还可能中断共用同一调度协程的其他任务。

时间线：错误为什么一直拖到第一次请求

复盘之后，故障链条很清楚：插件实例先进入注册函数，注册函数只检查名称；注册表保存反射方法值；服务启动完成；请求到达后，调用器按固定参数构造 []reflect.Value；最后在 Call 处才暴露签名不兼容。

真正的触发条件不是“使用了反射”，而是注册契约与调用契约分离。调用端知道自己会传什么，注册端却没有把这份知识变成可执行检查。只要插件由不同模块、不同团队或配置驱动加载，这种遗漏就很容易发生。

根因：比较了带接收者的方法类型

修复的第一个坑，是 reflect.Type.MethodByName 与 reflect.Value.MethodByName 得到的方法类型不同。Go 规范中的方法表达式会把接收者放在函数的第一个参数位置；对应地，从类型上取得的 Method.Type 也包含接收者。假设 *JSONPlugin 有目标方法，从类型视角看，它更接近下面的函数：

// 类型方法把接收者作为第一个显式参数。
func(*JSONPlugin, context.Context, []byte) ([]byte, error)

而从具体插件值取得的绑定方法已经保存了接收者，它的类型才是调用器真正需要的签名：

// 绑定方法已固定插件接收者，只保留业务参数和返回值。
func(context.Context, []byte) ([]byte, error)

如果直接拿类型方法与允许函数比较，就会因为多出接收者而误拒绝合法插件。我最后选择在注册时使用 reflect.ValueOf(plugin).MethodByName("Handle")，这样比较规则和后续调用看到的是同一种绑定方法。

修复：在注册阶段建立签名门禁

下面的注册器只允许一个公开的 Handle 方法，并把允许类型定义成未命名函数类型。这里不要写成自定义的命名函数类型再直接比较，因为命名类型与未命名方法类型并不相同。精确类型相等会同时覆盖参数个数、参数类型、返回值个数、返回值类型以及是否为变参函数。

package registry

import (
	"context"
	"fmt"
	"reflect"
	"strings"
)

var allowedHandleType = reflect.TypeOf(
	// 使用未命名函数类型，便于和绑定方法的 Type 做精确比较。
	(func(context.Context, []byte) ([]byte, error))(nil),
)

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

func (r *Registry) Register(name string, plugin any) error {
	if strings.TrimSpace(name) == "" {
		return fmt.Errorf("插件名不能为空")
	}

	v := reflect.ValueOf(plugin)
	if !v.IsValid() {
		return fmt.Errorf("插件 %q 是 nil", name)
	}
	// 指针、映射、切片等可为空值要单独拒绝，避免保存不可调用的接收者。
	switch v.Kind() {
	case reflect.Pointer, reflect.Map, reflect.Slice, reflect.Func, reflect.Interface, reflect.Chan:
		if v.IsNil() {
			return fmt.Errorf("插件 %q 是带类型的 nil", name)
		}
	}

	method := v.MethodByName("Handle")
	if !method.IsValid() {
		return fmt.Errorf("插件 %q 缺少公开方法 Handle", name)
	}
	if method.Type() != allowedHandleType {
		return fmt.Errorf(
			"插件 %q 的 Handle 签名为 %s，要求 %s",
			name, method.Type(), allowedHandleType,
		)
	}

	if r.handlers == nil {
		r.handlers = make(map[string]reflect.Value)
	}
	if _, exists := r.handlers[name]; exists {
		return fmt.Errorf("插件名 %q 已注册", name)
	}
	// 只有完整签名匹配的绑定方法才能进入注册表。
	r.handlers[name] = method
	return nil
}

这个门禁有一个很实用的效果：错误信息能同时打印“实际签名”和“期望签名”。插件作者不需要翻调用栈，就能直接看到是参数还是返回值写错。对我来说，这是这次修复里比“避免 panic”更有价值的部分，因为它把跨模块协作变成了可读契约。

调用端仍要把反射边界收窄

注册通过后，调用器可以假定参数和返回值形状已经固定。这里仍需要处理“插件内部返回的 error”和“插件实现自身 panic”之间的区别：前者是业务结果，后者属于插件隔离策略，不能混成签名校验问题。

func (r *Registry) Call(
	ctx context.Context,
	name string,
	payload []byte,
) ([]byte, error) {
	method, ok := r.handlers[name]
	if !ok {
		return nil, fmt.Errorf("插件 %q 未注册", name)
	}

	// 参数形状已在 Register 中确认，这里只负责调用和解包返回值。
	out := method.Call([]reflect.Value{
		reflect.ValueOf(ctx),
		reflect.ValueOf(payload),
	})

	result := out[0].Bytes()
	if out[1].IsNil() {
		return result, nil
	}
	return result, out[1].Interface().(error)
}

reflect.Type 的 NumIn、In、NumOut、Out 和 IsVariadic 适合生成更细的差异报告；如果目标只是严格允许一种签名，直接比较类型更短，也不容易漏掉变参属性。只有当规则允许多个签名版本时，才值得逐项检查并给出迁移提示。

防复发：把拒绝规则写成表驱动测试

这次故障之后，我补的不是一条“正确插件能注册”测试，而是一组拒绝测试。因为签名门禁真正的价值来自它能稳定挡住错误输入，包括缺少方法、错误参数、错误返回值、变参方法和带类型的 nil 指针。

func TestRegisterRejectsInvalidPlugins(t *testing.T) {
	tests := []struct {
		name   string
		plugin any
		wantOK bool
	}{
		// GoodPlugin 的 Handle 完整匹配允许签名。
		{name: "good", plugin: &GoodPlugin{}, wantOK: true},
		// 下面几项分别覆盖常见的契约破坏方式。
		{name: "wrong-input", plugin: &WrongInputPlugin{}, wantOK: false},
		{name: "wrong-output", plugin: &WrongOutputPlugin{}, wantOK: false},
		{name: "variadic", plugin: &VariadicPlugin{}, wantOK: false},
		{name: "typed-nil", plugin: (*GoodPlugin)(nil), wantOK: false},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			r := &Registry{}
			err := r.Register(tt.name, tt.plugin)
			if (err == nil) != tt.wantOK {
				t.Fatalf("Register() error = %v, wantOK = %v", err, tt.wantOK)
			}
		})
	}
}

还应补一个容易忽略的接收者用例：值接收者方法可以出现在指针的方法集中，而仅有指针接收者的方法不会出现在值类型的方法集中。注册器接受的是调用时的实际值，因此测试要覆盖 T 与 *T 两种传法，不要假定它们的可用方法完全一致。

什么时候不该用反射

如果所有插件都与主程序一起编译，接口通常更简单。定义下面的接口后，编译器就能在赋值或参数传递时检查方法集合，不需要把错误推迟到注册阶段：

type Handler interface {
	// Handle 是插件必须实现的静态契约。
	Handle(context.Context, []byte) ([]byte, error)
}

反射更适合“插件对象先以 any 进入系统，再根据描述发现能力”的场景，例如通用依赖容器、配置驱动的处理器目录或需要统一诊断多种方法契约的框架。即使必须使用反射，也应把它限制在注册阶段；运行阶段尽量保存已经验证的绑定方法或转换后的强类型适配器。

复盘后的检查清单

• 是否在注册阶段检查方法存在，而不是等到第一次调用？
• 比较的是绑定方法类型，还是错误地把接收者也算进参数？
• 是否同时限制参数、返回值、顺序和变参属性？
• 是否拒绝无类型 nil 与带类型 nil？
• 错误信息能否显示实际签名和允许签名？
• 是否阻止重复名称覆盖已有插件？
• 测试是否覆盖值接收者、指针接收者和错误签名？
• 如果接口已经能解决问题，是否仍有使用反射的必要？

这次问题最后没有靠更复杂的恢复逻辑解决，而是把失败点前移了：插件一进入注册器就接受完整签名检查。反射本身并不可怕，真正危险的是把动态发现当成动态放行。先用 reflect.Type 把允许边界写清楚，再让注册表接收方法，插件系统会更容易诊断，也更适合长期维护。