From 7156bbc82ffdf49e13f17e9da8a28d6e32b9a48c Mon Sep 17 00:00:00 2001 From: xfy Date: Fri, 10 Apr 2026 16:55:38 +0800 Subject: [PATCH] =?UTF-8?q?refactor(lua):=20=E6=94=B9=E8=BF=9B=E4=BB=A3?= =?UTF-8?q?=E7=A0=81=E9=A3=8E=E6=A0=BC=E5=92=8C=E6=96=87=E6=A1=A3=E6=B3=A8?= =?UTF-8?q?=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 为 LuaEngine/LuaContext/LuaCoroutine 添加命名说明注释 - 为 Phase 常量添加文档注释 - 规范 import 排序顺序 - 处理 Write 返回值避免 lint 警告 - 修复文件末尾换行符 Co-Authored-By: Claude Opus 4.6 --- internal/lua/cache.go | 7 +++++-- internal/lua/config.go | 2 +- internal/lua/constraints_test.go | 4 ++-- internal/lua/context.go | 13 +++++++++++-- internal/lua/coroutine.go | 17 +++++++++++++++-- internal/lua/engine.go | 15 ++++++++++----- internal/lua/lua_test.go | 4 ++-- internal/lua/security_test.go | 4 ++-- 8 files changed, 48 insertions(+), 18 deletions(-) diff --git a/internal/lua/cache.go b/internal/lua/cache.go index 81e175f..83b1f0d 100644 --- a/internal/lua/cache.go +++ b/internal/lua/cache.go @@ -19,9 +19,12 @@ import ( // CacheKeyType 缓存键类型 type CacheKeyType int +// 缓存键类型常量：内联脚本和文件脚本 const ( + // CacheKeyInline 内联脚本缓存键 CacheKeyInline CacheKeyType = iota // 内联脚本 - CacheKeyFile // 文件脚本 + // CacheKeyFile 文件脚本缓存键 + CacheKeyFile // 文件脚本 ) // CachedProto 缓存的字节码 @@ -260,4 +263,4 @@ func (c *CodeCache) Clear() { defer c.mu.Unlock() c.protos = make(map[string]*CachedProto) c.order = c.order[:0] -} \ No newline at end of file +} diff --git a/internal/lua/config.go b/internal/lua/config.go index 3e7c279..63d5b4a 100644 --- a/internal/lua/config.go +++ b/internal/lua/config.go @@ -41,4 +41,4 @@ func DefaultConfig() *Config { EnableIOLib: false, EnableLoadLib: false, } -} \ No newline at end of file +} diff --git a/internal/lua/constraints_test.go b/internal/lua/constraints_test.go index 5e9cd18..52839b2 100644 --- a/internal/lua/constraints_test.go +++ b/internal/lua/constraints_test.go @@ -4,9 +4,9 @@ package lua import ( "testing" - glua "github.com/yuin/gopher-lua" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + glua "github.com/yuin/gopher-lua" ) // TestNewEngine 测试引擎创建 @@ -207,4 +207,4 @@ func engineCodeToProto(src string) (*glua.FunctionProto, error) { } // Package-level helper for testing -var cacheGetOrCompile = NewCodeCache(100, 0, false).GetOrCompileInline \ No newline at end of file +var cacheGetOrCompile = NewCodeCache(100, 0, false).GetOrCompileInline diff --git a/internal/lua/context.go b/internal/lua/context.go index 068d766..e22da94 100644 --- a/internal/lua/context.go +++ b/internal/lua/context.go @@ -6,6 +6,11 @@ import ( ) // LuaContext 请求级 Lua 上下文 +// +// 类型命名说明：虽然 lua.LuaContext 存在 stuttering，但保持此命名以： +// 1) 与 LuaEngine/LuaCoroutine 保持一致的 API 命名风格 +// 2) 明确区分 Lua 上下文与其他上下文类型（如 context.Context） +// 3) 保持向后兼容性 type LuaContext struct { // 引擎引用 Engine *LuaEngine @@ -120,7 +125,11 @@ func (c *LuaContext) Release() { // FlushOutput 刷新输出到响应 func (c *LuaContext) FlushOutput() { if len(c.OutputBuffer) > 0 && c.RequestCtx != nil { - c.RequestCtx.Write(c.OutputBuffer) + // Write 返回写入的字节数和可能的错误 + // 在响应刷新场景中，我们选择忽略错误，因为： + // 1. fasthttp.RequestCtx.Write 内部已经处理了连接状态 + // 2. 此阶段出错时请求处理已完成，无法向客户端报告 + _, _ = c.RequestCtx.Write(c.OutputBuffer) c.OutputBuffer = c.OutputBuffer[:0] } -} \ No newline at end of file +} diff --git a/internal/lua/coroutine.go b/internal/lua/coroutine.go index 9cbda30..50d3cb7 100644 --- a/internal/lua/coroutine.go +++ b/internal/lua/coroutine.go @@ -7,20 +7,28 @@ import ( "sync/atomic" "time" - glua "github.com/yuin/gopher-lua" "github.com/valyala/fasthttp" + glua "github.com/yuin/gopher-lua" ) // Phase 处理阶段 type Phase int +// 处理阶段常量，对应 nginx 请求处理生命周期 const ( + // PhaseInit 初始化阶段 PhaseInit Phase = iota + // PhaseRewrite 重写阶段 PhaseRewrite + // PhaseAccess 访问控制阶段 PhaseAccess + // PhaseContent 内容生成阶段 PhaseContent + // PhaseLog 日志记录阶段 PhaseLog + // PhaseHeaderFilter 响应头过滤阶段 PhaseHeaderFilter + // PhaseBodyFilter 响应体过滤阶段 PhaseBodyFilter ) @@ -47,6 +55,11 @@ func (p Phase) String() string { // LuaCoroutine 请求级临时协程 // 注意：协程在 ResumeOK 后变成 dead 状态，不能复用 +// +// 类型命名说明：虽然 lua.LuaCoroutine 存在 stuttering，但保持此命名以： +// 1) 与 LuaEngine/LuaContext 保持一致的 API 命名风格 +// 2) 明确区分 Lua 运行时协程与 Go 协程概念 +// 3) 保持向后兼容性 type LuaCoroutine struct { // 所属引擎 Engine *LuaEngine @@ -232,4 +245,4 @@ func (c *LuaCoroutine) handleSleep(values []glua.LValue) ([]glua.LValue, error) // Close 关闭协程 func (c *LuaCoroutine) Close() { c.Engine.releaseCoroutine(c) -} \ No newline at end of file +} diff --git a/internal/lua/engine.go b/internal/lua/engine.go index b8fa76d..37e7330 100644 --- a/internal/lua/engine.go +++ b/internal/lua/engine.go @@ -8,12 +8,17 @@ import ( "sync/atomic" "time" - glua "github.com/yuin/gopher-lua" "github.com/valyala/fasthttp" + glua "github.com/yuin/gopher-lua" ) // LuaEngine 全局 Lua 引擎 // 每个 HTTP Server 实例持有一个 LuaEngine +// +// 类型命名说明：虽然 lua.LuaEngine 存在 stuttering，但保持此命名以： +// 1) 与 LuaContext/LuaCoroutine 保持一致的 API 命名风格 +// 2) 明确区分 Lua 引擎与其他引擎类型 +// 3) 保持向后兼容性 type LuaEngine struct { // 主 LState L *glua.LState @@ -25,9 +30,9 @@ type LuaEngine struct { codeCache *CodeCache // 协程管理 - activeCount int32 // 活跃协程数 - maxCoroutines int // 最大并发协程数 - coroutinePool sync.Pool // 协程对象池（注意：池中的协程已 dead，不可复用，仅复用内存） + activeCount int32 // 活跃协程数 + maxCoroutines int // 最大并发协程数 + coroutinePool sync.Pool // 协程对象池（注意：池中的协程已 dead，不可复用，仅复用内存） // 生命周期 ctx context.Context @@ -182,4 +187,4 @@ func (e *LuaEngine) Stats() EngineStats { // ActiveCoroutines 返回活跃协程数 func (e *LuaEngine) ActiveCoroutines() int32 { return atomic.LoadInt32(&e.activeCount) -} \ No newline at end of file +} diff --git a/internal/lua/lua_test.go b/internal/lua/lua_test.go index 2a41935..8dc24bf 100644 --- a/internal/lua/lua_test.go +++ b/internal/lua/lua_test.go @@ -340,7 +340,7 @@ func TestCodeCacheTTL(t *testing.T) { // 检查 stats：两次 miss，因为 TTL 过期后重新编译 hits, misses, _ := cache.Stats() - assert.Equal(t, uint64(0), hits) // 没有 hit + assert.Equal(t, uint64(0), hits) // 没有 hit assert.Equal(t, uint64(2), misses) // 两次 miss } @@ -455,4 +455,4 @@ func TestConfig(t *testing.T) { defer engine.Close() assert.Equal(t, 100, engine.maxCoroutines) -} \ No newline at end of file +} diff --git a/internal/lua/security_test.go b/internal/lua/security_test.go index 49afcc0..7376b30 100644 --- a/internal/lua/security_test.go +++ b/internal/lua/security_test.go @@ -4,9 +4,9 @@ package lua import ( "testing" - glua "github.com/yuin/gopher-lua" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + glua "github.com/yuin/gopher-lua" ) // TestSandboxBlocksCoroutineCreate 验证协程创建被阻止 @@ -152,4 +152,4 @@ func TestCoroutineRunningBlocked(t *testing.T) { err = coro.Execute(`coroutine.running()`) assert.Error(t, err) assert.Contains(t, err.Error(), "blocked") -} \ No newline at end of file +}