lua

Lua 脚本引擎

基于 GopherLua 封装的 Go 嵌入式 Lua 脚本引擎实现，作为 go-scripts 的子模块对外提供。

GopherLua 是纯 Go 实现的 Lua 5.1 虚拟机，与 C 风格的 Lua C API 风格接近，性能不错且零 CGO 依赖。

包结构

设计要点

• 统一接口：实现 script_engine.Engine 接口，可与 Manager、EnginePool、AutoGrowEnginePool 等根模块组件无缝配合。
• 工厂自动注册：通过 init() 注册到 script_engine 全局工厂表，只需 import _ "github.com/tx7do/go-scripts/lua" 即可启用。
• 并发安全：内部用 sync.RWMutex 保护 VM / source / initialized；Execute* / CallFunction 通过 channel + ctx.Done() 支持取消和超时。
• LState 复用池：本模块自带 statePool，在 engine Init 时借出、Close 时归还，默认上限 10 个 LState 实例，避免每次脚本运行都重建虚拟机。
• 脚本源解耦：通过 Source 接口（FileSource / MemSource / MultiSource / 自定义扩展）注入脚本来源，engine 本身不再耦合任何 IO 细节。
• 标准 Lua 生态：Init 时开启 Lua 标准库（支持 AllowedLib* 沙箱白名单按需开启）+ 选择性预载 gopher-lua-libs 的 json / http client 与 gluacrypto（聚合式 libs.Preload 会拖入 aws-sdk 等重依赖，刻意不用）+ GetLuaPath 辅助函数；宿主业务模块（kratos_*）见 host。

gopher-lua 的几点限制（务必留意）

依赖

• Go 1.24+
• github.com/yuin/gopher-lua —— Lua 5.1 虚拟机
• layeh.com/gopher-luar —— Go ↔ Lua 双向值桥接
• github.com/yuin/gluamapper —— Lua table ↔ Go struct 映射
• github.com/vadv/gopher-lua-libs —— 通用库扩展（json/http/regexp/db/...）
• github.com/tengattack/gluacrypto —— 加密 / 哈希扩展
• github.com/tx7do/go-scripts —— 根模块

快速开始

1. 引入模块

import (
    scriptEngine "github.com/tx7do/go-scripts"
    _ "github.com/tx7do/go-scripts/lua" // 注册 Lua 工厂
)

只要触发 init()，后续所有 scriptEngine.NewScriptEngine(scriptEngine.LuaType, ...) 调用都会返回本模块的 engine 实例。

2. 单实例使用

eng, err := scriptEngine.NewScriptEngine(scriptEngine.LuaType)
if err != nil {
    log.Fatal(err)
}
defer eng.Close()

ctx := context.Background()
if err := eng.Init(ctx); err != nil {
    log.Fatal(err)
}

// 注入变量（host -> Lua）
_ = eng.RegisterGlobal("answer", 42)

// 注入宿主函数（必须是 Lua.LGFunction）
_ = eng.RegisterFunction("say_hello", func(L *lua.LState) int {
    name := L.CheckString(1)
    fmt.Println("Hello,", name)
    return 0 // 返回值个数
})

// 执行内联脚本
_, err = eng.ExecuteString(ctx, "demo.lua", `
    say_hello("world")
    print(answer + 100)
`)

3. 引擎池（推荐生产用法）

// 固定大小池
pool, err := scriptEngine.NewEnginePool(8, scriptEngine.LuaType)

// 或：可自增池（初始 2，上限 16）
pool, err := scriptEngine.NewAutoGrowEnginePool(2, 16, scriptEngine.LuaType)
if err != nil {
    log.Fatal(err)
}
defer pool.Close()

ctx := context.Background()
_, _ = pool.ExecuteString(ctx, "init.lua", `app_name = "demo"`)

4. 配合 ScriptSource（统一脚本来源）

// 本地文件 + mtime 热更新检测
src := scriptEngine.NewFileSource()
eng.SetSource(src)

// 从 Source 加载并执行
_, err := eng.ExecuteFromKey(ctx, "/path/to/script.lua")

// 也可以直接走 engine pool 的 wrapper
pool.SetSource(src)
results, err := pool.ExecuteFromKeys(ctx, []string{"a.lua", "b.lua"})

也可使用 MemSource（纯内存，零 IO）或 MultiSource（多源聚合 / fallback）。

核心 API

Engine 接口提供的方法如下（节选，完整定义见 engine.go）：

生命周期

ScriptSource

脚本加载

脚本执行

全局变量 / 函数 / 模块

错误处理

宿主与脚本互操作

变量

支持三种访问模式：

• 单向只写：RegisterGlobal 把宿主变量注入脚本（基本类型 / map / slice）。
• 单向只读：GetGlobal 读取脚本中定义的变量。
• 双向可读可写：通过 luar 注入结构体指针，脚本对其字段的修改会反映到宿主。

type User struct {
    Name  string
    Token string
}

u := &User{Name: "Tim"}
_ = eng.RegisterGlobal("u", u)
_, _ = eng.ExecuteString(ctx, "", `u:SetToken("abcd")`)
fmt.Println(u.Token) // abcd

函数

Lua 函数签名要求：本模块的 RegisterFunction / RegisterModule 只接受 Lua.LGFunction（即 func(*lua.LState) int），其它类型会报错。

import Lua "github.com/yuin/gopher-lua"

// host -> Lua
_ = eng.RegisterFunction("add", func(L *Lua.LState) int {
    a := L.CheckInt(1)
    b := L.CheckInt(2)
    L.Push(Lua.LNumber(a + b))
    return 1 // 返回值个数
})

// Lua -> host
_, _ = eng.ExecuteString(ctx, "", `result = add(10, 20)`)
v, _ := eng.GetGlobal("result") // int64(30)

宿主调用脚本中定义的函数：

_, _ = eng.ExecuteString(ctx, "", `
    function multiply(a, b) return a * b end
`)
v, _ := eng.CallFunction(ctx, "multiply", 3, 4) // int64(12)

模块

RegisterModule 注册的是 Lua 模块 loader 函数（Lua.LGFunction 类型）：

modLoader := func(L *Lua.LState) int {
    mod := L.NewTable()
    L.SetField(mod, "pi", Lua.LNumber(3.14159))
    L.SetField(mod, "square", L.NewFunction(func(L *Lua.LState) int {
        x := L.CheckNumber(1)
        L.Push(Lua.LNumber(x * x))
        return 1
    }))
    L.Push(mod)
    return 1
}
_ = eng.RegisterModule("mathutil", modLoader)

-- 脚本侧
print(mathutil.pi)               -- 3.14159
print(mathutil.square(2))        -- 4

注意：上面的 RegisterModule 走的是 gopher-lua 自带的 loader 协议（L.NewFunction + L.Call），与 script/test_module.lua 中展示的"module 表 + return module"写法用于 require 加载场景。两者并不冲突，可以并存。

Lua 内置模块（已自动启用）

virtualMachine.init() 时自动开启以下库：

require 标准 Lua 写法可用：

-- script/test_module.lua
module = {}
module.constant = "这是一个常量"
function module.func3() print("hello") end
return module

-- script/main.lua
local m = require("test_module")
print(m.constant)
m.func3()

完整示例

package main

import (
    "context"
    "fmt"
    "log"

    scriptEngine "github.com/tx7do/go-scripts"
    _ "github.com/tx7do/go-scripts/lua"
    Lua "github.com/yuin/gopher-lua"
)

type User struct {
    Name  string
    Token string
}

func main() {
    pool, err := scriptEngine.NewEnginePool(4, scriptEngine.LuaType)
    if err != nil {
        log.Fatal(err)
    }
    defer pool.Close()

    ctx := context.Background()

    // 1. 注入结构体（脚本可修改其字段）
    u := &User{Name: "Tim"}
    _ = pool.RegisterGlobal("u", u)

    // 2. 注入宿主函数（必须是 Lua.LGFunction）
    _ = pool.RegisterFunction("say_hello", func(L *Lua.LState) int {
        name := L.CheckString(1)
        fmt.Println("Hello,", name)
        return 0
    })

    // 3. 执行内联脚本
    _, err = pool.ExecuteString(ctx, "app.lua", `
        say_hello(u.Name)
        u.Token = "abcd-1234"
        print("answer:", 6 * 7)
    `)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println("user token:", u.Token) // abcd-1234
}

LState 状态池

本模块内部维护一个 statePool：

• Borrow() —— 取空闲 LState，无则新建
• Return(L) —— 归还 LState，超过上限则 Close
• Shutdown() —— 关闭池，回收所有空闲 LState（仅用于全局清理，正常业务无需调用）

默认配置：

可通过 newStatePoolWithOptions(Lua.Options{...}) 自定义。

测试

cd lua
go test -v ./...

涵盖：

• 基础执行 + 全局变量读写 + 宿主函数注入
• 并发 CallFunction + GetGlobal 压测（50 goroutine × 200 loop）
• 并发 Init / Close 压测（40 goroutine × 200 op）
• Source 注入 + Load / LoadMulti / ExecuteFromKey / ExecuteFromKeys
• FileSource 端到端（t.TempDir() + 临时脚本文件）
• statePool Borrow / Return 基础功能
• Lua table ↔ Go struct 映射（gluamapper）

相关文档

• 根模块 README：../README.md
• Engine 接口定义：../engine.go
• ScriptSource 实现：../source.go
• 引擎池：../engine_pool.go / ../engine_pool_autogrow.go
• gopher-lua 文档：https://github.com/yuin/gopher-lua
• gopher-lua-libs 文档：https://github.com/vadv/gopher-lua-libs
• gluacrypto 文档：https://github.com/tengattack/gluacrypto