Merge pull request #3 from xfy911/improve-comments

docs: add comprehensive documentation comments

doc-report.md

@@ -0,0 +1,315 @@
+# Lolly 项目缺少文档注释的导出标识符检测报告
+
+## 概述
+
+使用 AST 静态分析扫描 `/root/projects/lolly`，共发现 **180** 个导出的函数/类型/常量/变量缺少以标识符名称开头的文档注释（GoDoc）。
+
+---
+
+## 一、公共 API（非 internal 包）
+
+| 文件 | 行号 | 类型 | 名称 |
+|------|------|------|------|
+| `gjson/gjson.go` | 35 | const | `ModuleName` |
+| `gjson/gjson.go` | 38 | const | `Version` |
+
+**说明**：`gjson` 是项目中唯一的非 internal 子包，其导出的 `ModuleName` 和 `Version` 常量缺少文档注释。
+
+---
+
+## 二、internal 包中的缺失（按文件分组）
+
+### internal/benchmark/tools/tools.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 13 | const | `Size100B` |
+| 14 | const | `Size1KB` |
+| 15 | const | `Size10KB` |
+| 16 | const | `Size100KB` |
+| 17 | const | `Size1MB` |
+| 36 | const | `ModeNormalResponse` |
+| 37 | const | `ModeRandomResponse` |
+| 38 | const | `ModeErrorResponse` |
+| 39 | const | `ModeDelayedResponse` |
+
+### internal/config/config.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 33 | const | `DefaultPprofPath` |
+| 44 | const | `ServerModeSingle` |
+| 46 | const | `ServerModeVHost` |
+| 48 | const | `ServerModeMultiServer` |
+| 50 | const | `ServerModeAuto` |
+
+### internal/converter/nginx/converter.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 28 | method | `Warning.String` |
+
+### internal/converter/nginx/parser.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 31 | method | `*ParseError.Error` |
+
+### internal/e2e/testutil/constants.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 18 | const | `ContainerStartupTimeout` |
+| 21 | const | `HealthCheckWaitTimeout` |
+| 24 | const | `HealthCheckDetectionTime` |
+| 27 | const | `CacheExpireBuffer` |
+| 30 | const | `DefaultTestTimeout` |
+| 33 | const | `DefaultClientTimeout` |
+| 36 | const | `ConcurrentRequestTimeout` |
+| 39 | const | `ShortTestTimeout` |
+| 42 | const | `MediumTestTimeout` |
+| 48 | const | `DefaultBackendCount` |
+| 51 | const | `DefaultConcurrentRequests` |
+| 54 | const | `HighConcurrentRequests` |
+| 57 | const | `CacheTestMaxAge` |
+| 60 | const | `CacheTestShortMaxAge` |
+| 66 | const | `TLSVersion12` |
+| 69 | const | `TLSVersion13` |
+
+### internal/e2e/testutil/websocket.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 41 | func | `WithWSHeaders` |
+
+### internal/lua/api_log.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 29 | const | `LogStderr` |
+| 30 | const | `LogEmerg` |
+| 31 | const | `LogAlert` |
+| 32 | const | `LogCrit` |
+| 33 | const | `LogErr` |
+| 34 | const | `LogWarn` |
+| 35 | const | `LogNotice` |
+| 36 | const | `LogInfo` |
+| 37 | const | `LogDebug` |
+| 42 | const | `HTTPContinue` |
+| 43 | const | `HTTPSwitchingProtocols` |
+| 44 | const | `HTTPOK` |
+| 45 | const | `HTTPCreated` |
+| 46 | const | `HTTPAccepted` |
+| 47 | const | `HTTPNoContent` |
+| 48 | const | `HTTPPartialContent` |
+| 49 | const | `HTTPMovedPermanently` |
+| 50 | const | `HTTPFound` |
+| 51 | const | `HTTPSeeOther` |
+| 52 | const | `HTTPNotModified` |
+| 53 | const | `HTTPTemporaryRedirect` |
+| 54 | const | `HTTPPermanentRedirect` |
+| 55 | const | `HTTPBadRequest` |
+| 56 | const | `HTTPUnauthorized` |
+| 57 | const | `HTTPForbidden` |
+| 58 | const | `HTTPNotFound` |
+| 59 | const | `HTTPMethodNotAllowed` |
+| 60 | const | `HTTPRequestTimeout` |
+| 61 | const | `HTTPConflict` |
+| 62 | const | `HTTPGone` |
+| 63 | const | `HTTPLengthRequired` |
+| 64 | const | `HTTPPayloadTooLarge` |
+| 65 | const | `HTTPURITooLong` |
+| 66 | const | `HTTPUnsupportedMedia` |
+| 67 | const | `HTTPRangeNotSatisfiable` |
+| 68 | const | `HTTPTooManyRequests` |
+| 69 | const | `HTTPInternalServerError` |
+| 70 | const | `HTTPNotImplemented` |
+| 71 | const | `HTTPBadGateway` |
+| 72 | const | `HTTPServiceUnavailable` |
+| 73 | const | `HTTPGatewayTimeout` |
+| 74 | const | `HTTPHTTPVersionNotSupported` |
+
+### internal/lua/api_req.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 36 | const | `APILayerDirect` |
+| 40 | const | `APILayerCompatible` |
+| 44 | const | `APILayerPseudoNonBlocking` |
+| 58 | method | `ngxReqAPILayer.String` |
+
+### internal/lua/cache.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 38 | const | `CacheKeyInline` |
+| 41 | const | `CacheKeyFile` |
+
+### internal/lua/coroutine.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 35 | const | `PhaseInit` |
+| 37 | const | `PhaseRewrite` |
+| 39 | const | `PhaseAccess` |
+| 41 | const | `PhaseContent` |
+| 43 | const | `PhaseLog` |
+| 45 | const | `PhaseHeaderFilter` |
+| 47 | const | `PhaseBodyFilter` |
+| 50 | method | `Phase.String` |
+
+### internal/lua/socket_manager.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 36 | const | `SocketStateIdle` |
+| 38 | const | `SocketStateConnecting` |
+| 40 | const | `SocketStateConnected` |
+| 42 | const | `SocketStateSending` |
+| 44 | const | `SocketStateReceiving` |
+| 46 | const | `SocketStateClosing` |
+| 48 | const | `SocketStateClosed` |
+| 50 | const | `SocketStateError` |
+| 83 | const | `OpConnect` |
+| 85 | const | `OpSend` |
+| 87 | const | `OpReceive` |
+| 89 | const | `OpClose` |
+
+### internal/matcher/location.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 257 | method | `*ConflictError.Error` |
+
+### internal/matcher/matcher.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 27 | const | `LocationTypeExact` |
+| 28 | const | `LocationTypePrefix` |
+| 29 | const | `LocationTypePrefixPriority` |
+| 30 | const | `LocationTypeRegex` |
+| 31 | const | `LocationTypeRegexCaseless` |
+| 32 | const | `LocationTypeNamed` |
+
+### internal/middleware/compression/compression.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 100 | const | `AlgorithmGzip` |
+| 102 | const | `AlgorithmBrotli` |
+
+### internal/middleware/limitrate/limitrate.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 15 | const | `LargeFileStrategySkip` |
+| 17 | const | `LargeFileStrategyCoarse` |
+
+### internal/middleware/rewrite/rewrite.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 41 | const | `FlagLast` |
+| 44 | const | `FlagRedirect` |
+| 47 | const | `FlagPermanent` |
+| 50 | const | `FlagBreak` |
+
+### internal/middleware/security/access.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 47 | const | `ActionAllow` |
+| 49 | const | `ActionDeny` |
+
+### internal/middleware/security/auth.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 52 | const | `HashBcrypt` |
+| 54 | const | `HashArgon2id` |
+
+### internal/resolver/resolver.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 446 | method | `*noopResolver.LookupHost` |
+| 450 | method | `*noopResolver.LookupHostWithCache` |
+| 454 | method | `*noopResolver.Refresh` |
+| 458 | method | `*noopResolver.Start` |
+| 462 | method | `*noopResolver.Stop` |
+| 466 | method | `*noopResolver.Stats` |
+
+### internal/ssl/client_verify.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 33 | const | `VerifyOff` |
+| 35 | const | `VerifyOn` |
+| 37 | const | `VerifyOptional` |
+| 39 | const | `VerifyOptionalNoCA` |
+
+### internal/stream/stream.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 82 | method | `*roundRobin.Select` |
+| 171 | method | `*weightedRoundRobin.Select` |
+| 244 | method | `*ipHash.Select` |
+| 248 | method | `*ipHash.SelectByIP` |
+
+### internal/utils/httperror.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 26 | var | `ErrNotFound` |
+| 27 | var | `ErrForbidden` |
+| 28 | var | `ErrUnauthorized` |
+| 29 | var | `ErrBadGateway` |
+| 30 | var | `ErrGatewayTimeout` |
+| 31 | var | `ErrInternalError` |
+| 32 | var | `ErrTooManyRequests` |
+| 33 | var | `ErrServiceUnavailable` |
+
+### internal/variable/builtin.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 19 | const | `VarHost` |
+| 20 | const | `VarRemoteAddr` |
+| 21 | const | `VarRemotePort` |
+| 22 | const | `VarRequestURI` |
+| 23 | const | `VarURI` |
+| 24 | const | `VarArgs` |
+| 25 | const | `VarRequestMethod` |
+| 26 | const | `VarScheme` |
+| 27 | const | `VarServerName` |
+| 28 | const | `VarServerPort` |
+| 29 | const | `VarStatus` |
+| 30 | const | `VarBodyBytesSent` |
+| 31 | const | `VarRequestTime` |
+| 32 | const | `VarTimeLocal` |
+| 33 | const | `VarTimeISO8601` |
+| 34 | const | `VarRequestID` |
+| 36 | const | `VarUpstreamAddr` |
+| 37 | const | `VarUpstreamStatus` |
+| 38 | const | `VarUpstreamResponseTime` |
+| 39 | const | `VarUpstreamConnectTime` |
+| 40 | const | `VarUpstreamHeaderTime` |
+
+### internal/variable/ssl.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 24 | const | `VarSSLClientVerify` |
+| 25 | const | `VarSSLClientSerial` |
+| 26 | const | `VarSSLClientSubject` |
+| 27 | const | `VarSSLClientIssuer` |
+| 28 | const | `VarSSLClientFingerprint` |
+| 29 | const | `VarSSLClientNotBefore` |
+| 30 | const | `VarSSLClientNotAfter` |
+| 31 | const | `VarSSLClientDNS` |
+| 32 | const | `VarSSLClientEmail` |
+
+### internal/version/version.go
+| 行号 | 类型 | 名称 |
+|------|------|------|
+| 9 | var | `Version` |
+| 11 | var | `GitCommit` |
+| 13 | var | `GitBranch` |
+| 15 | var | `BuildTime` |
+| 17 | var | `GoVersion` |
+| 19 | var | `BuildPlatform` |
+
+---
+
+## 统计汇总
+
+| 类别 | 数量 |
+|------|------|
+| 公共 API（非 internal） | 2 |
+| internal 常量 | 134 |
+| internal 变量 | 14 |
+| internal 方法 | 14 |
+| internal 函数 | 1 |
+| **总计** | **180** |
+
+---
+
+*检测规则：导出的标识符（首字母大写）必须紧跟以该标识符名称开头的 `//` 文档注释，才被视为已文档化。`_test.go` 和 vendor 目录已排除。*

gjson/gjson.go

@@ -23,7 +23,7 @@
 //   - Number precision control
 //   - Independent configuration instances via gjson.new()
 //
-// Author: xfy
+// 作者：xfy
 package gjson
 
 import (
@@ -31,10 +31,10 @@ import (
 )
 
 const (
-	// ModuleName is the Lua module name for require()
+	// ModuleName 模块名称。
 	ModuleName = "gjson"
 
-	// Version is the module version
+	// Version 模块版本号。
 	Version = "1.0.0"
 )
 

internal/app/app.go

@@ -1,5 +1,10 @@
 //go:build !windows
 
+// Package app 提供 Lolly 应用程序的生命周期管理和命令行入口。
+//
+// 包含应用生命周期管理和命令行入口相关的逻辑。
+//
+// 作者：xfy
 package app
 
 import (

internal/app/app_common.go

@@ -1,3 +1,8 @@
+// Package app 提供 Lolly 应用程序的生命周期管理和命令行入口。
+//
+// 包含应用通用逻辑相关的工具函数。
+//
+// 作者：xfy
 package app
 
 import (

internal/app/app_windows.go

@@ -2,6 +2,11 @@
 
 // Windows lacks POSIX signals (SIGUSR1, SIGUSR2, SIGHUP, SIGQUIT);
 // this file provides stub implementations for those Unix-specific signals.
+// Package app 提供 Lolly 应用程序的生命周期管理和命令行入口。
+//
+// 包含 Windows 平台特定的应用逻辑。
+//
+// 作者：xfy
 package app
 
 import (

internal/app/import.go

@@ -1,3 +1,8 @@
+// Package app 提供 Lolly 应用程序的生命周期管理和命令行入口。
+//
+// 包含配置导入相关的逻辑，用于导入 nginx 配置等外部配置。
+//
+// 作者：xfy
 package app
 
 import (

internal/app/testutil.go

@@ -1,5 +1,10 @@
 //go:build !windows
 
+// Package app 提供 Lolly 应用程序的生命周期管理和命令行入口。
+//
+// 包含测试工具函数，用于测试场景。
+//
+// 作者：xfy
 package app
 
 import (

internal/benchmark/tools/tools.go

@@ -1,4 +1,8 @@
 // Package tools 提供基准测试和集成测试的辅助工具。
+//
+// 包含 Mock 后端创建、测试数据生成等工具函数。
+//
+// 作者：xfy
 package tools
 
 import (
@@ -10,14 +14,19 @@ import (
 
 // 预定义的测试数据大小常量
 const (
+	// Size100B 100 字节测试数据。
 	Size100B = 100
+	// Size1KB 1KB 测试数据。
 	Size1KB = 1024
+	// Size10KB 10KB 测试数据。
 	Size10KB = 10 * 1024
+	// Size100KB 100KB 测试数据。
 	Size100KB = 100 * 1024
+	// Size1MB 1MB 测试数据。
 	Size1MB = 1024 * 1024
 )
 
-// MockBackendConfig Mock 后端配置
+// MockBackendConfig Mock 后端配置。
 type MockBackendConfig struct {
 	// Mode 运行模式
 	Mode string
@@ -33,9 +42,13 @@ type MockBackendConfig struct {
 
 // Mock 后端运行模式
 const (
+	// ModeNormalResponse 正常响应模式。
 	ModeNormalResponse = "normal"
+	// ModeRandomResponse 随机响应模式。
 	ModeRandomResponse = "random"
+	// ModeErrorResponse 错误响应模式。
 	ModeErrorResponse = "error"
+	// ModeDelayedResponse 延迟响应模式。
 	ModeDelayedResponse = "delayed"
 )
 

internal/config/cache_config.go

@@ -1,3 +1,8 @@
+// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。
+//
+// 包含缓存配置相关的结构体，用于控制代理缓存行为。
+//
+// 作者：xfy
 package config
 
 import "time"

internal/config/config.go

@@ -29,7 +29,7 @@ import (
 
 // 默认配置常量。
 const (
-	// DefaultPprofPath pprof 端点的默认路径。
+// DefaultPprofPath pprof 端点的默认路径。
 	DefaultPprofPath = "/debug/pprof"
 )
 
@@ -40,13 +40,13 @@ type ServerMode string
 
 // ServerMode 枚举值。
 const (
-	// ServerModeSingle 单服务器模式 - 只运行一个服务器实例。
+// ServerModeSingle 单服务器模式 - 只运行一个服务器实例。
 	ServerModeSingle ServerMode = "single"
-	// ServerModeVHost 虚拟主机模式 - 多个服务器共享相同的监听地址。
+// ServerModeVHost 虚拟主机模式 - 多个服务器共享相同的监听地址。
 	ServerModeVHost ServerMode = "vhost"
-	// ServerModeMultiServer 多服务器模式 - 多个服务器监听不同的地址。
+// ServerModeMultiServer 多服务器模式 - 多个服务器监听不同的地址。
 	ServerModeMultiServer ServerMode = "multi_server"
-	// ServerModeAuto 自动模式 - 根据配置自动推断运行模式。
+// ServerModeAuto 自动模式 - 根据配置自动推断运行模式。
 	ServerModeAuto ServerMode = "auto"
 )
 

internal/config/monitoring_config.go

@@ -1,3 +1,8 @@
+// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。
+//
+// 包含监控配置相关的结构体，用于配置服务状态监控和健康检查端点。
+//
+// 作者：xfy
 package config
 
 // MonitoringConfig 监控配置。

internal/config/performance_config.go

@@ -1,3 +1,8 @@
+// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。
+//
+// 包含性能配置相关的结构体，用于控制服务器性能优化参数。
+//
+// 作者：xfy
 package config
 
 import (

internal/config/proxy_config.go

@@ -1,3 +1,8 @@
+// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。
+//
+// 包含代理配置相关的结构体，用于配置反向代理行为。
+//
+// 作者：xfy
 package config
 
 import (

internal/config/security_config.go

@@ -1,3 +1,8 @@
+// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。
+//
+// 包含安全配置相关的结构体，用于配置访问控制、限流、认证和安全头部。
+//
+// 作者：xfy
 package config
 
 import "time"

internal/config/server_config.go

@@ -1,3 +1,8 @@
+// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。
+//
+// 包含服务器配置相关的结构体，用于配置监听地址、静态文件、代理、SSL 等设置。
+//
+// 作者：xfy
 package config
 
 import "time"

internal/config/ssl_config.go

@@ -1,3 +1,8 @@
+// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。
+//
+// 包含 SSL/TLS 配置相关的结构体，用于配置 HTTPS 加密参数。
+//
+// 作者：xfy
 package config
 
 import "time"

internal/config/variable_config.go

@@ -1,3 +1,8 @@
+// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。
+//
+// 包含变量配置相关的结构体，用于配置自定义变量和内置变量。
+//
+// 作者：xfy
 package config
 
 import "time"

internal/converter/nginx/converter.go

@@ -25,6 +25,7 @@ type Warning struct {
 	Message   string
 }
 
+// String 返回警告的字符串表示。
 func (w Warning) String() string {
 	return fmt.Sprintf("warning: %s:%d: %s", w.File, w.Line, w.Message)
 }

internal/converter/nginx/parser.go

@@ -28,6 +28,7 @@ type ParseError struct {
 	Message string
 }
 
+// Error 返回解析错误的字符串表示。
 func (e *ParseError) Error() string {
 	return fmt.Sprintf("%s:%d: %s", e.File, e.Line, e.Message)
 }

internal/e2e/testutil/websocket.go

@@ -38,6 +38,7 @@ type wsConfig struct {
 }
 
 // WithHeaders 设置请求头。
+// WithWSHeaders 设置 WebSocket 请求头。
 func WithWSHeaders(headers http.Header) WSOption {
 	return func(c *wsConfig) {
 		c.headers = headers

internal/loadbalance/random.go

@@ -1,3 +1,8 @@
+// Package loadbalance 提供多种负载均衡算法实现，支持随机、轮询、加权、一致性哈希等策略。
+//
+// 包含随机负载均衡算法相关的逻辑。
+//
+// 作者：xfy
 package loadbalance
 
 import (

internal/lua/api_log.go

@@ -26,51 +26,93 @@ import (
 
 // 日志级别常量（与 OpenResty/ngx_lua 兼容）
 const (
+// LogStderr 标准错误日志级别。
 	LogStderr = 0
+	// LogEmerg 紧急日志级别。
 	LogEmerg = 1
+	// LogAlert 警报日志级别。
 	LogAlert = 2
+	// LogCrit 严重日志级别。
 	LogCrit = 3
+	// LogErr 错误日志级别。
 	LogErr = 4
+	// LogWarn 警告日志级别。
 	LogWarn = 5
+	// LogNotice 通知日志级别。
 	LogNotice = 6
+	// LogInfo 信息日志级别。
 	LogInfo = 7
+	// LogDebug 调试日志级别。
 	LogDebug = 8
 )
 
 // HTTP 状态码常量
 const (
+// HTTPContinue HTTP 100 继续状态码。
 	HTTPContinue = 100
+	// HTTPSwitchingProtocols HTTP 101 切换协议状态码。
 	HTTPSwitchingProtocols = 101
+	// HTTPOK HTTP 200 成功状态码。
 	HTTPOK = 200
+	// HTTPCreated HTTP 201 已创建状态码。
 	HTTPCreated = 201
+	// HTTPAccepted HTTP 202 已接受状态码。
 	HTTPAccepted = 202
+	// HTTPNoContent HTTP 204 无内容状态码。
 	HTTPNoContent = 204
+	// HTTPPartialContent HTTP 206 部分内容状态码。
 	HTTPPartialContent = 206
+	// HTTPMovedPermanently HTTP 301 永久重定向状态码。
 	HTTPMovedPermanently = 301
+	// HTTPFound HTTP 302 找到状态码。
 	HTTPFound = 302
+	// HTTPSeeOther HTTP 303 查看其他状态码。
 	HTTPSeeOther = 303
+	// HTTPNotModified HTTP 304 未修改状态码。
 	HTTPNotModified = 304
+	// HTTPTemporaryRedirect HTTP 307 临时重定向状态码。
 	HTTPTemporaryRedirect = 307
+	// HTTPPermanentRedirect HTTP 308 永久重定向状态码。
 	HTTPPermanentRedirect = 308
+	// HTTPBadRequest HTTP 400 错误请求状态码。
 	HTTPBadRequest = 400
+	// HTTPUnauthorized HTTP 401 未授权状态码。
 	HTTPUnauthorized = 401
+	// HTTPForbidden HTTP 403 禁止访问状态码。
 	HTTPForbidden = 403
+	// HTTPNotFound HTTP 404 未找到状态码。
 	HTTPNotFound = 404
+	// HTTPMethodNotAllowed HTTP 405 方法不允许状态码。
 	HTTPMethodNotAllowed = 405
+	// HTTPRequestTimeout HTTP 408 请求超时状态码。
 	HTTPRequestTimeout = 408
+	// HTTPConflict HTTP 409 冲突状态码。
 	HTTPConflict = 409
+	// HTTPGone HTTP 410 已移除状态码。
 	HTTPGone = 410
+	// HTTPLengthRequired HTTP 411 需要长度状态码。
 	HTTPLengthRequired = 411
+	// HTTPPayloadTooLarge HTTP 413 请求实体过大状态码。
 	HTTPPayloadTooLarge = 413
+	// HTTPURITooLong HTTP 414 URI 过长状态码。
 	HTTPURITooLong = 414
+	// HTTPUnsupportedMedia HTTP 415 不支持的媒体类型状态码。
 	HTTPUnsupportedMedia = 415
+	// HTTPRangeNotSatisfiable HTTP 416 范围不可满足状态码。
 	HTTPRangeNotSatisfiable = 416
+	// HTTPTooManyRequests HTTP 429 请求过多状态码。
 	HTTPTooManyRequests = 429
+	// HTTPInternalServerError HTTP 500 内部服务器错误状态码。
 	HTTPInternalServerError = 500
+	// HTTPNotImplemented HTTP 501 未实现状态码。
 	HTTPNotImplemented = 501
+	// HTTPBadGateway HTTP 502 错误网关状态码。
 	HTTPBadGateway = 502
+	// HTTPServiceUnavailable HTTP 503 服务不可用状态码。
 	HTTPServiceUnavailable = 503
+	// HTTPGatewayTimeout HTTP 504 网关超时状态码。
 	HTTPGatewayTimeout = 504
+	// HTTPHTTPVersionNotSupported HTTP 505 HTTP 版本不支持状态码。
 	HTTPHTTPVersionNotSupported = 505
 )
 

internal/lua/api_req.go

@@ -55,6 +55,7 @@ const (
 	layerStringUnknown = "unknown"
 )
 
+// String 返回 API 层级的字符串表示。
 func (l ngxReqAPILayer) String() string {
 	switch l {
 	case APILayerDirect:

internal/lua/coroutine.go

@@ -47,6 +47,7 @@ const (
 	PhaseBodyFilter
 )
 
+// String 返回处理阶段的字符串表示。
 func (p Phase) String() string {
 	switch p {
 	case PhaseInit:

internal/lua/ip_guard.go

@@ -1,3 +1,8 @@
+// Package lua 提供 Lua 脚本扩展功能，支持 IP 黑白名单、请求处理等。
+//
+// 包含 IP 守卫相关的逻辑，用于处理 IP 黑白名单功能。
+//
+// 作者：xfy
 package lua
 
 import "net"

internal/matcher/location.go

@@ -254,6 +254,7 @@ type ConflictError struct {
 	NewType      string
 }
 
+// Error 返回路径冲突错误的字符串表示。
 func (e *ConflictError) Error() string {
 	return fmt.Sprintf("path conflict: '%s' already registered as '%s', trying to register as '%s'",
 		e.Path, e.ExistingType, e.NewType)

internal/matcher/matcher.go

@@ -24,12 +24,18 @@ import "github.com/valyala/fasthttp"
 
 // LocationType 常量定义，表示不同 location 匹配类型。
 const (
-	LocationTypeExact          = "exact"           // 精确匹配 =
+// LocationTypeExact 精确匹配类型（=）。
-	LocationTypePrefix         = "prefix"          // 普通前缀匹配
+	LocationTypeExact = "exact"
-	LocationTypePrefixPriority = "prefix_priority" // 前缀优先匹配 ^~
+	// LocationTypePrefix 前缀匹配类型。
-	LocationTypeRegex          = "regex"           // 正则匹配 ~
+	LocationTypePrefix = "prefix"
-	LocationTypeRegexCaseless  = "regex_caseless"  // 大小写不敏感正则匹配 ~*
+	// LocationTypePrefixPriority 前缀优先匹配类型（^~）。
-	LocationTypeNamed          = "named"           // 命名匹配 @name
+	LocationTypePrefixPriority = "prefix_priority"
+	// LocationTypeRegex 正则匹配类型（~）。
+	LocationTypeRegex = "regex"
+	// LocationTypeRegexCaseless 大小写不敏感正则匹配类型（~*）。
+	LocationTypeRegexCaseless = "regex_caseless"
+	// LocationTypeNamed 命名匹配类型（@name）。
+	LocationTypeNamed = "named"
 )
 
 // MatchResult 匹配结果。

internal/middleware/compression/compression.go

@@ -96,9 +96,9 @@ const streamingThreshold = 64 * 1024 // 64KB
 type Algorithm int
 
 const (
-	// AlgorithmGzip 使用 gzip 压缩。
+// AlgorithmGzip 使用 gzip 压缩算法。
 	AlgorithmGzip Algorithm = iota
-	// AlgorithmBrotli 使用 brotli 压缩。
+	// AlgorithmBrotli 使用 brotli 压缩算法。
 	AlgorithmBrotli
 
 	compressionGZIP = "gzip"

internal/middleware/limitrate/limitrate.go

@@ -1,3 +1,8 @@
+// Package limitrate 提供基于令牌桶算法的请求速率限制功能。
+//
+// 包含速率限制器相关的逻辑，用于控制请求处理速率。
+//
+// 作者：xfy
 package limitrate
 
 import (
@@ -6,9 +11,9 @@ import (
 )
 
 const (
-	// LargeFileStrategySkip 跳过大文件限速
+	// LargeFileStrategySkip 大文件策略：跳过（不限制）。
 	LargeFileStrategySkip = "skip"
-	// LargeFileStrategyCoarse 粗粒度限速
+	// LargeFileStrategyCoarse 大文件策略：粗略限制。
 	LargeFileStrategyCoarse = "coarse"
 )
 

internal/middleware/limitrate/writer.go

@@ -1,3 +1,8 @@
+// Package limitrate 提供基于令牌桶算法的请求速率限制功能。
+//
+// 包含速率限制响应写入器相关的逻辑，用于处理被限制的请求响应。
+//
+// 作者：xfy
 package limitrate
 
 import (

internal/middleware/rewrite/rewrite.go

@@ -29,14 +29,14 @@ import (
 	"rua.plus/lolly/internal/variable"
 )
 
-// MaxRewriteIterations URL重写最大迭代次数，防止无限循环
+// MaxRewriteIterations URL重写最大迭代次数，防止无限循环。
 const MaxRewriteIterations = 10
 
 // Flag 重写标志类型。
 type Flag int
 
 const (
-	// FlagLast 继续匹配其他规则（nginx 行为：重新从第一条规则开始匹配）。
+// FlagLast 继续匹配其他规则（nginx 行为：重新从第一条规则开始匹配）。
 	// 匹配到规则后会重新从第一条规则开始遍历，用于多规则链式重写。
 	FlagLast Flag = iota
 	// FlagRedirect 返回 302 临时重定向。

internal/middleware/security/access.go

@@ -43,9 +43,9 @@ import (
 type Action int
 
 const (
-	// ActionAllow 允许请求通过
+// ActionAllow 允许请求通过。
 	ActionAllow Action = iota
-	// ActionDeny 拒绝请求（返回 403 Forbidden）
+	// ActionDeny 拒绝请求（返回 403 Forbidden）。
 	ActionDeny
 
 	accessAllow     = "allow"

internal/middleware/security/auth.go

@@ -48,9 +48,9 @@ import (
 type HashAlgorithm int
 
 const (
-	// HashBcrypt bcrypt 算法（默认，推荐）
+// HashBcrypt bcrypt 哈希算法（默认，推荐）。
 	HashBcrypt HashAlgorithm = iota
-	// HashArgon2id Argon2id 算法（更安全，计算密集）
+	// HashArgon2id Argon2id 哈希算法（更安全，计算密集）。
 	HashArgon2id
 )
 

internal/proxy/cache_handler.go

@@ -1,3 +1,8 @@
+// Package proxy 提供反向代理的核心功能，支持请求转发、负载均衡、健康检查等特性。
+//
+// 包含缓存处理器相关的结构体，用于配置代理缓存行为。
+//
+// 作者：xfy
 package proxy
 
 import (

internal/proxy/header_modifier.go

@@ -1,3 +1,8 @@
+// Package proxy 提供反向代理的核心功能，支持请求转发、负载均衡、健康检查等特性。
+//
+// 包含请求头修改器相关的结构体，用于配置请求和响应头修改规则。
+//
+// 作者：xfy
 package proxy
 
 import (

internal/proxy/target_selector.go

@@ -1,3 +1,8 @@
+// Package proxy 提供反向代理的核心功能，支持请求转发、负载均衡、健康检查等特性。
+//
+// 包含代理配置相关的结构体，用于配置反向代理行为。
+//
+// 作者：xfy
 package proxy
 
 import (

internal/proxy/utils.go

@@ -1,3 +1,8 @@
+// Package proxy 提供反向代理的核心功能，支持请求转发、负载均衡、健康检查等特性。
+//
+// 包含代理工具函数，用于处理请求和响应的转换。
+//
+// 作者：xfy
 package proxy
 
 import (

internal/proxy/validate.go

@@ -1,3 +1,8 @@
+// Package proxy 提供反向代理的核心功能，支持请求转发、负载均衡、健康检查等特性。
+//
+// 包含代理验证相关的结构体，用于配置请求验证规则。
+//
+// 作者：xfy
 package proxy
 
 import "strings"

internal/resolver/resolver.go

@@ -443,26 +443,34 @@ func (r *DNSResolver) Stats() Stats {
 // noopResolver 是禁用状态下的空实现。
 type noopResolver struct{}
 
+// LookupHost 解析主机名（空实现）。
+// 在禁用状态下返回错误。
 func (n *noopResolver) LookupHost(_ context.Context, _ string) ([]string, error) {
 	return nil, fmt.Errorf("resolver is disabled")
 }
 
+// LookupHostWithCache 带缓存解析主机名（空实现）。
+// 直接委托给 LookupHost。
 func (n *noopResolver) LookupHostWithCache(ctx context.Context, host string) ([]string, error) {
 	return n.LookupHost(ctx, host)
 }
 
+// Refresh 刷新解析器缓存（空实现）。
 func (n *noopResolver) Refresh(_ string) error {
 	return nil
 }
 
+// Start 启动解析器（空实现）。
 func (n *noopResolver) Start() error {
 	return nil
 }
 
+// Stop 停止解析器（空实现）。
 func (n *noopResolver) Stop() error {
 	return nil
 }
 
+// Stats 返回解析器统计信息（空实现）。
 func (n *noopResolver) Stats() Stats {
 	return Stats{}
 }

internal/server/internal.go

@@ -1,3 +1,8 @@
+// Package server 提供 HTTP 服务器的核心实现，支持单服务器、虚拟主机和多服务器三种运行模式。
+//
+// 包含服务器内部工具函数，用于处理服务器运行时逻辑。
+//
+// 作者：xfy
 package server
 
 import (

internal/server/lifecycle.go

@@ -1,3 +1,8 @@
+// Package server 提供 HTTP 服务器的核心实现，支持单服务器、虚拟主机和多服务器三种运行模式。
+//
+// 包含服务器生命周期管理相关的逻辑，用于处理启动、停止和信号处理。
+//
+// 作者：xfy
 package server
 
 import (

internal/server/middleware_builder.go

@@ -1,3 +1,8 @@
+// Package server 提供 HTTP 服务器的核心实现，支持单服务器、虚拟主机和多服务器三种运行模式。
+//
+// 包含中间件构建器相关的逻辑，用于构建和管理 HTTP 中间件链。
+//
+// 作者：xfy
 package server
 
 import (

internal/server/router.go

@@ -1,3 +1,8 @@
+// Package server 提供 HTTP 服务器的核心实现，支持单服务器、虚拟主机和多服务器三种运行模式。
+//
+// 包含路由器相关的核心逻辑，用于管理 HTTP 请求的路由分发。
+//
+// 作者：xfy
 package server
 
 import (

internal/ssl/client_verify.go

@@ -29,13 +29,13 @@ import (
 type ClientVerifyMode int
 
 const (
-	// VerifyOff 不验证客户端证书
+// VerifyOff 不验证客户端证书。
 	VerifyOff ClientVerifyMode = iota
-	// VerifyOn 强制验证客户端证书
+	// VerifyOn 强制验证客户端证书。
 	VerifyOn
-	// VerifyOptional 可选验证（客户端可选择不提供证书）
+	// VerifyOptional 可选验证（客户端可选择不提供证书）。
 	VerifyOptional
-	// VerifyOptionalNoCA 可选验证但不验证 CA
+	// VerifyOptionalNoCA 可选验证但不验证 CA。
 	VerifyOptionalNoCA
 
 	// verifyModeOff 验证模式字符串常量

internal/stream/stream.go

@@ -79,6 +79,9 @@ func newRoundRobin() Balancer {
 	return rr
 }
 
+// Select 选择下一个目标（轮询算法）。
+//
+// 从健康目标列表中按轮询顺序选择。
 func (r *roundRobin) Select(targets []*Target) *Target {
 	// 从池中获取 healthy slice 并复用
 	healthyPtr := r.healthyPool.Get().(*[]*Target) //nolint:errcheck // pool always returns valid *[]*Target
@@ -168,6 +171,9 @@ func newWeightedRoundRobin() Balancer {
 	return w
 }
 
+// Select 选择下一个目标（加权轮询算法）。
+//
+// 从健康目标列表中按权重比例选择。
 func (w *weightedRoundRobin) Select(targets []*Target) *Target {
 	healthyPtr := w.healthyPool.Get().(*[]*Target) //nolint:errcheck // pool always returns valid *[]*Target
 	healthy := *healthyPtr
@@ -241,10 +247,17 @@ func newIPHash() Balancer {
 	return ih
 }
 
+// Select 选择下一个目标（IP 哈希算法）。
+//
+// 委托给 SelectByIP，使用空客户端 IP。
 func (i *ipHash) Select(targets []*Target) *Target {
 	return i.SelectByIP(targets, "")
 }
 
+// SelectByIP 根据客户端 IP 选择目标。
+//
+// 使用 FNV-64a 哈希算法对客户端 IP 进行哈希，从健康目标列表中选择对应的目标。
+// 如果 clientIP 为空，则回退到轮询选择。
 func (i *ipHash) SelectByIP(targets []*Target, clientIP string) *Target {
 	healthyPtr := i.healthyPool.Get().(*[]*Target) //nolint:errcheck // pool always returns valid *[]*Target
 	healthy := *healthyPtr

internal/utils/bytes.go

@@ -1,3 +1,8 @@
+// Package utils 提供通用的工具函数和辅助类型。
+//
+// 包含字节操作相关的工具函数，用于处理字节切片和缓冲区。
+//
+// 作者：xfy
 package utils
 
 import "unsafe"

internal/utils/etag.go

@@ -1,3 +1,8 @@
+// Package utils 提供通用的工具函数和辅助类型。
+//
+// 包含 ETag 生成相关的工具函数，用于处理缓存验证。
+//
+// 作者：xfy
 package utils
 
 import (

internal/utils/httperror.go

@@ -23,13 +23,21 @@ type HTTPError struct {
 
 // Predefined common HTTP errors.
 var (
+// ErrNotFound 资源未找到错误。
 	ErrNotFound           = HTTPError{Message: "Not Found", StatusCode: fasthttp.StatusNotFound}
+	// ErrForbidden 禁止访问错误。
 	ErrForbidden          = HTTPError{Message: "Forbidden", StatusCode: fasthttp.StatusForbidden}
+	// ErrUnauthorized 未授权错误。
 	ErrUnauthorized       = HTTPError{Message: "Unauthorized", StatusCode: fasthttp.StatusUnauthorized}
+	// ErrBadGateway 错误网关错误。
 	ErrBadGateway         = HTTPError{Message: "Bad Gateway", StatusCode: fasthttp.StatusBadGateway}
+	// ErrGatewayTimeout 网关超时错误。
 	ErrGatewayTimeout     = HTTPError{Message: "Gateway Timeout", StatusCode: fasthttp.StatusGatewayTimeout}
+	// ErrInternalError 内部服务器错误。
 	ErrInternalError      = HTTPError{Message: "Internal Server Error", StatusCode: fasthttp.StatusInternalServerError}
+	// ErrTooManyRequests 请求过多错误。
 	ErrTooManyRequests    = HTTPError{Message: "Too Many Requests", StatusCode: fasthttp.StatusTooManyRequests}
+	// ErrServiceUnavailable 服务不可用错误。
 	ErrServiceUnavailable = HTTPError{Message: "Service Unavailable", StatusCode: fasthttp.StatusServiceUnavailable}
 )
 

internal/utils/internal.go

@@ -1,3 +1,8 @@
+// Package utils 提供通用的工具函数和辅助类型。
+//
+// 包含内部工具函数，用于处理内部逻辑。
+//
+// 作者：xfy
 package utils
 
 import "github.com/valyala/fasthttp"

internal/variable/builtin.go

@@ -16,27 +16,48 @@ import (
 
 // 内置变量常量
 const (
+// VarHost 请求主机名变量。
 	VarHost = "host"
+	// VarRemoteAddr 客户端地址变量。
 	VarRemoteAddr = "remote_addr"
+	// VarRemotePort 客户端端口变量。
 	VarRemotePort = "remote_port"
+	// VarRequestURI 请求 URI 变量。
 	VarRequestURI = "request_uri"
+	// VarURI URI 变量。
 	VarURI = "uri"
+	// VarArgs 查询参数变量。
 	VarArgs = "args"
+	// VarRequestMethod 请求方法变量。
 	VarRequestMethod = "request_method"
+	// VarScheme 协议方案变量。
 	VarScheme = "scheme"
+	// VarServerName 服务器名称变量。
 	VarServerName = "server_name"
+	// VarServerPort 服务器端口变量。
 	VarServerPort = "server_port"
+	// VarStatus HTTP 状态码变量。
 	VarStatus = "status"
+	// VarBodyBytesSent 发送字节数变量。
 	VarBodyBytesSent = "body_bytes_sent"
+	// VarRequestTime 请求处理时间变量。
 	VarRequestTime = "request_time"
+	// VarTimeLocal 本地时间变量。
 	VarTimeLocal = "time_local"
+	// VarTimeISO8601 ISO8601 时间变量。
 	VarTimeISO8601 = "time_iso8601"
+	// VarRequestID 请求 ID 变量。
 	VarRequestID = "request_id"
 	// 上游变量
+	// VarUpstreamAddr 上游地址变量。
 	VarUpstreamAddr = "upstream_addr"
+	// VarUpstreamStatus 上游状态码变量。
 	VarUpstreamStatus = "upstream_status"
+	// VarUpstreamResponseTime 上游响应时间变量。
 	VarUpstreamResponseTime = "upstream_response_time"
+	// VarUpstreamConnectTime 上游连接时间变量。
 	VarUpstreamConnectTime = "upstream_connect_time"
+	// VarUpstreamHeaderTime 上游响应头时间变量。
 	VarUpstreamHeaderTime = "upstream_header_time"
 )
 

internal/variable/ssl.go

@@ -21,14 +21,23 @@ import (
 
 // SSL 变量常量
 const (
+// VarSSLClientVerify SSL 客户端证书验证结果变量。
 	VarSSLClientVerify      = "ssl_client_verify"
+	// VarSSLClientSerial SSL 客户端证书序列号变量。
 	VarSSLClientSerial      = "ssl_client_serial"
+	// VarSSLClientSubject SSL 客户端证书主题变量。
 	VarSSLClientSubject     = "ssl_client_subject"
+	// VarSSLClientIssuer SSL 客户端证书颁发者变量。
 	VarSSLClientIssuer      = "ssl_client_issuer"
+	// VarSSLClientFingerprint SSL 客户端证书指纹变量。
 	VarSSLClientFingerprint = "ssl_client_fingerprint"
+	// VarSSLClientNotBefore SSL 客户端证书生效时间变量。
 	VarSSLClientNotBefore   = "ssl_client_notbefore"
+	// VarSSLClientNotAfter SSL 客户端证书过期时间变量。
 	VarSSLClientNotAfter    = "ssl_client_notafter"
+	// VarSSLClientDNS SSL 客户端证书主题 DN 变量。
 	VarSSLClientDNS         = "ssl_client_s_dn"
+	// VarSSLClientEmail SSL 客户端证书邮箱变量。
 	VarSSLClientEmail       = "ssl_client_email"
 
 	sslProtocolNone = "NONE"