Go GopherLua CallByParam 的保护调用和普通调用有什么区别

Go 代码调用 GopherLua 函数时，CallByParam 的 Protect 字段决定了脚本出错后的边界：设为 true，运行错误会变成返回的 error；设为 false，调用沿用普通 Call 路径，错误会触发 panic。两种模式都会使用同一组参数和 NRet，差别主要在异常怎么离开调用点。

官方地址：https://github.com/yuin/gopher-lua

需要把脚本错误交给当前请求、任务或上层逻辑处理时用 Protect: true；已经在初始化阶段，且脚本错误代表进程无法继续时，才考虑普通调用。普通调用成功返回的 error 仍然是 nil，不要把它误当成“永远不会报错”。

先看结论：Protect 改变的是错误传播方式

因此，“保护调用”不是给 Lua 代码增加权限，也不是让函数更安全地执行。它只是在 CallByParam 内部选择是否捕获 GopherLua 的调用异常。Fn、参数、NRet 和返回值栈的工作方式仍然相同。

CallByParam 的四个字段分别管什么

最小配置可以写成下面这样。字段职责分开后，排查“为什么没有拿到结果”会简单很多：

param := lua.P{
	// Fn 是要被 GopherLua 调用的函数值。
	Fn: L.GetGlobal("render"),
	// NRet 表示调用方希望保留的返回值数量。
	NRet: 1,
	// Protect 决定运行错误返回 error 还是触发 panic。
	Protect: true,
	// Handler 可选，只在保护调用处理错误对象时使用。
	Handler: nil,
}

• Fn 必须是可调用的 LValue，通常来自 GetGlobal 或表字段。
• NRet 是调用方的接收数量，不是 Lua 函数声明的返回类型；不需要返回值时可以设为 0，需要全部结果时可使用 lua.MultRet。
• Protect 只负责异常传播方式，和返回值数量没有直接关系。
• Handler 是保护路径上的错误处理函数；没有特殊转换需求时保持 nil 即可。

Protect 为 true：把脚本错误交给 Go 代码

在 HTTP 请求、队列任务或用户可编辑脚本中，通常不应该让一次 Lua 错误直接打断宿主 Go 进程。此时用保护调用，判断返回的 error，成功后再从 LState 取结果：

func callProtected(L *lua.LState, fn lua.LValue) (lua.LValue, error) {
	// 保护调用把函数运行期间的 GopherLua 错误转换成 error。
	err := L.CallByParam(lua.P{
		Fn:      fn,
		NRet:    1,
		Protect: true,
	}, lua.LString("首页"))
	if err != nil {
		// 失败时不要继续读取旧的栈结果，先把错误交给上层。
		return nil, err
	}

	// 成功时 NRet 为 1，结果位于 LState 栈顶。
	result := L.Get(-1)
	L.Pop(1) // 读取后清理结果槽，避免后续调用混入旧值。
	return result, nil
}

这段代码里，CallByParam 成功返回的仍是 nil，真正的业务结果在栈顶。只有脚本执行失败时，返回值才会变成非空 error。因此不能只看 err == nil 就认为结果已经是字符串，还要按 NRet 读取结果并做类型判断。

如果需要统一改写错误信息，可以为 Handler 提供一个 *lua.LFunction。但 Handler 自己也可能失败，错误处理函数不能替代宿主侧的最后一道错误判断。

Protect 为 false：成功简单，失败会 panic

普通调用的成功分支更短：CallByParam 完成后直接读取结果即可。区别在于，脚本里的 error()、参数检查失败或运行时异常不会作为普通 error 返回，而是沿着 panic 路径离开当前调用点。

func callUnprotected(L *lua.LState, fn lua.LValue) (value lua.LValue) {
	// 这里把 panic 限制在一个明确的初始化边界内。
	defer func() {
		if recovered := recover(); recovered != nil {
			// 生产代码应记录 recovered，并按初始化失败处理。
			value = lua.LNil
		}
	}()

	// Protect 为 false 时，错误不会通过 CallByParam 的 error 返回。
	if err := L.CallByParam(lua.P{
		Fn:      fn,
		NRet:    1,
		Protect: false,
	}, lua.LString("配置")); err != nil {
		// 成功路径通常返回 nil；这里保留判断以防包装器改变契约。
		return lua.LNil
	}

	// 只有成功返回后，才读取并清理结果槽。
	result := L.Get(-1)
	L.Pop(1)
	return result
}

这里的 recover 不是普通业务流程的推荐写法，而是说明边界：如果你决定使用普通调用，就必须明确谁负责接住 panic。不要在每个调用点随意恢复后继续处理半成品状态；初始化失败时，让启动流程停止通常更容易保证一致性。

不要把 NRet 和 Protect 混在一起

NRet 决定“成功时取几个返回值”，Protect 决定“失败时怎么传播”。例如下面的调用即使开启保护，也只请求一个结果：

err := L.CallByParam(lua.P{
	// 保护异常，但只接收一个返回槽。
	Fn:      fn,
	NRet:    1,
	Protect: true,
}, args...)
if err != nil {
	// 保护模式的失败分支在这里结束，不读取结果槽。
	return err
}

result := L.Get(-1)
L.Pop(1) // NRet 为 1，所以这里只清理一个结果。

如果 Lua 函数实际返回多个值，NRet: 1 会让调用方只保留需要的数量；这和 Protect 无关。相反，把 Protect 改成 false 也不会让 NRet 自动变成“全部返回”。

按调用场景选择一条稳定规则

1. 脚本内容来自用户、配置或插件时，优先使用 Protect: true，把错误变成当前任务可处理的 error。
2. 初始化阶段调用固定脚本，并且错误意味着服务不能继续时，可以使用 Protect: false，让 panic 直接暴露启动失败。
3. 无论哪种模式，都让 NRet 与实际读取数量一致；调用成功后及时 Pop 结果。
4. 只有确实需要改写错误对象时才设置 Handler，否则先用 nil 保持调用路径清楚。

我的排查顺序通常是：先确认 Fn 是否指向预期函数，再看 NRet，然后确认是否需要保护调用，最后才处理 Handler 和错误格式。这样能避免把“结果槽数量不对”误判成“脚本执行失败”。

几个容易混淆的问题

Protect 为 false 时，CallByParam 会返回非空 error 吗？

正常成功路径返回 nil；脚本运行错误会通过 panic 传播，而不是像保护调用那样返回普通 error。

Protect 为 true 就能防住所有 Go panic 吗？

它处理的是 GopherLua 调用路径中的错误和 panic。不要把它当成宿主 Go 代码的通用 panic 恢复器；宿主侧仍应避免让不受控的 Go panic 进入脚本边界。

Handler 和 Go 的 defer recover 有什么区别？

Handler 是 GopherLua 保护调用的错误处理函数，接收的是调用错误对象；defer recover 是 Go 语言层面的 panic 恢复机制，职责更外层。两者不要混用来掩盖错误。

结论：先决定异常边界，再配置 CallByParam

Go GopherLua 的 CallByParam 并没有两套参数传递协议：Fn、实参和 NRet 的职责保持不变。真正的选择只有一条：Protect: true 走保护调用，把脚本错误交给 error；Protect: false 走普通调用，失败以 panic 暴露。把这个边界和 NRet 分开理解，代码就不会因为错误处理和返回值读取相互混淆。