plugin Lookup 找不到符号时如何保留原始错误

调用 plugin.Lookup 找不到导出符号时，最容易犯的错误不是没有判断 err，而是把错误转成字符串后重新创建一个错误，导致上层再也拿不到原始原因。更稳妥的做法是：保留 Lookup 返回的错误值，用 fmt.Errorf 的 %w 增加插件路径和符号名；拿到 plugin.Symbol 后，再把函数或变量的类型断言错误单独处理。

官方地址：https://pkg.go.dev/plugin

Lookup 的原始错误负责说明“符号没有找到”，包装错误负责说明“在哪个插件、查哪个符号”。不要用 err.Error() 拼接后再交给 errors.New，要用 %w 保留错误链。

先分清三个错误出现的位置

官方文档把插件符号定义为导出的函数或变量，Lookup(symName) 找不到符号时返回错误。实际调用链通常有三个可能失败的地方：

• plugin.Open 失败：插件文件没有成功打开，后面还没有进入符号查找。
• Lookup 失败：插件已经打开，但指定名称没有对应的导出符号。
• 类型断言失败：符号找到了，但调用方把它断言成了错误的函数或变量类型。

这三类错误的处理动作不同。本文只聚焦第二类及其向上返回的方式，但把另外两类列出来，是为了避免把类型断言问题误报成“Lookup 找不到”。

不要把 Lookup 错误改写成字符串

下面这种写法看起来能把上下文补齐，但它只留下了错误文本：

return fmt.Errorf("查找符号失败: %s", err.Error())

如果上层要记录日志，这样做可能暂时看不出问题；但如果调用方需要继续包装、比较或提取错误，就已经失去了原始错误值。尤其是插件错误可能包含平台动态链接器给出的具体信息，字符串只是展示形式，不应成为唯一的数据载体。

正确的最小写法是使用 %w：

package loader

import (
	"fmt"
	"plugin"
)

// lookupExport 只负责查找导出符号，并在错误上保留原始 Lookup 原因。
func lookupExport(path, name string) (plugin.Symbol, error) {
	p, err := plugin.Open(path)
	if err != nil {
		// 打开失败与符号不存在是两个不同边界，分别保留原始错误。
		return nil, fmt.Errorf("打开插件 %q 失败: %w", path, err)
	}

	symbol, err := p.Lookup(name)
	if err != nil {
		// %w 让上层仍能沿错误链拿到 Lookup 返回的原始错误。
		return nil, fmt.Errorf("在插件 %q 中查找符号 %q 失败: %w", path, name, err)
	}
	return symbol, nil
}

这里的 %q 只负责把路径和符号名安全地放进上下文，%w 才是错误链的关键。返回值仍然是同一个原始错误，只是外面多了一层可读的定位信息。

找到符号后，再单独处理类型断言

Lookup 返回成功并不等于符号可以直接调用。plugin.Symbol 是一个可以承载函数或变量的值，调用方需要按插件约定做类型断言。如果断言目标错了，问题发生在“使用符号”阶段，而不是“找符号”阶段。

package loader

import (
	"fmt"
	"plugin"
)

type Handler func(string) (string, error)

// loadHandler 把“找不到符号”和“符号类型不符合约定”分别返回。
func loadHandler(path string) (Handler, error) {
	symbol, err := lookupExport(path, "Handle")
	if err != nil {
		// 不再创建第二个泛化错误，直接继续保留 Lookup 的错误链。
		return nil, err
	}

	handler, ok := symbol.(func(string) (string, error))
	if !ok {
		// 类型断言失败没有对应的 Lookup 原始错误，单独说明实际约定。
		return nil, fmt.Errorf("插件符号 %q 的类型不是 func(string) (string, error)", "Handle")
	}
	return handler, nil
}

如果插件导出的函数签名与宿主约定不同，类型断言会失败；这时继续追加“Lookup 找不到”反而会掩盖真正的接口不匹配。把这两个判断分开，日志和调用方才能做出正确处理。

上层如何继续保留原始原因

中间层通常还会添加业务动作，例如“加载报表处理器失败”。这时仍然使用 %w，让每一层只增加自己知道的上下文：

package service

import (
	"fmt"
)

// prepareHandler 给业务层补充动作信息，但不切断底层错误链。
func prepareHandler(path string) error {
	if _, err := loadHandler(path); err != nil {
		return fmt.Errorf("准备报表处理器失败: %w", err)
	}
	return nil
}

这样得到的错误文本会包含“准备报表处理器”“查找符号”“具体符号名”等上下文，而错误链仍然按调用顺序保留。需要向外返回时，直接返回这个包装后的错误即可；不要在每层都用 errors.New(err.Error()) 重新创建。

按错误边界做一次速查

排查时可以先看错误文本定位插件和符号，再沿错误链判断底层是否来自 Lookup。如果日志只剩下一段拼接后的文本，就无法区分是打开失败、符号不存在，还是类型断言失败。

常见误区与结论

误区一：用 err.Error() 拼接后再返回。这样只保留文字，不保留原始错误值。需要上下文时，用 %w。

误区二：Lookup 成功就直接调用。plugin.Symbol 还要按约定做类型断言，断言错误应与查找错误分开。

误区三：每一层都重建错误。中间层只应补充自己知道的动作和对象，继续使用 %w，避免错误链在边界处断掉。

可以把这条规则记成一句话：Lookup 错误负责保留根因，%w 负责增加上下文，类型断言负责验证符号契约。

相关问题

• Lookup 找不到符号时能用 errors.Is 判断吗？可以沿错误链检查，但标准库没有为“符号不存在”提供一个可供所有情况匹配的公开哨兵；实际排查通常依赖错误上下文和原始错误，而不是自行假设错误文本格式。
• 为什么不直接返回 err？直接返回当然能保留原因，但缺少插件路径、符号名等定位信息；用 %w 可以同时满足可读性和可追溯性。
• 类型断言失败能用 Lookup 的错误处理吗？不能。Lookup 已经成功，问题是导出符号和宿主约定的函数或变量类型不一致，应建立独立错误。