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 缓存的字节码

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 测试引擎创建

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

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         // 活跃协程数
+	activeCount   int32     // 活跃协程数
-	maxCoroutines int           // 最大并发协程数
+	maxCoroutines int       // 最大并发协程数
-	coroutinePool sync.Pool     // 协程对象池（注意：池中的协程已 dead，不可复用，仅复用内存）
+	coroutinePool sync.Pool // 协程对象池（注意：池中的协程已 dead，不可复用，仅复用内存）
 
 	// 生命周期
 	ctx    context.Context

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
 }
 

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 验证协程创建被阻止