refactor(lua): 改进代码风格和文档注释

- 为 LuaEngine/LuaContext/LuaCoroutine 添加命名说明注释
- 为 Phase 常量添加文档注释
- 规范 import 排序顺序
- 处理 Write 返回值避免 lint 警告
- 修复文件末尾换行符

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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]
-}
+}

internal/lua/config.go

@@ -41,4 +41,4 @@ func DefaultConfig() *Config {
 		EnableIOLib:             false,
 		EnableLoadLib:           false,
 	}
-}
+}

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
+var cacheGetOrCompile = NewCodeCache(100, 0, false).GetOrCompileInline

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]
 	}
-}
+}

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)
-}
+}

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)
-}
+}

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)
-}
+}

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")
-}
+}