docs(proxy): 为反向代理模块添加标准化 godoc 注释

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

internal/proxy/headers.go

@@ -7,8 +7,9 @@
 //   - X-Forwarded-Proto: 原始请求协议（http/https）
 //
 // 主要用途：
-//   用于在代理转发时保留客户端原始请求信息，使后端服务能够获取
-//   客户端的真实 IP、Host 和协议。
+//
+//	用于在代理转发时保留客户端原始请求信息，使后端服务能够获取
+//	客户端的真实 IP、Host 和协议。
 //
 // 注意事项：
 //   - 所有函数均为非并发安全（无状态函数）

internal/proxy/proxy.go

@@ -17,8 +17,9 @@
 //   - 临时文件：大响应自动写入临时文件，避免内存溢出
 //
 // 主要用途：
-//   用于将客户端 HTTP 请求代理转发到后端服务器集群，实现负载均衡、缓存加速、
-//   协议转换等功能，适用于 API 网关、反向代理服务器等场景。
+//
+//	用于将客户端 HTTP 请求代理转发到后端服务器集群，实现负载均衡、缓存加速、
+//	协议转换等功能，适用于 API 网关、反向代理服务器等场景。
 //
 // 注意事项：
 //   - Proxy 实例的公开方法均为并发安全
@@ -86,19 +87,19 @@ var headersPool = sync.Pool{
 //   - 所有公开方法均为并发安全
 //   - 使用前需确保 targets 中至少有一个健康目标
 type Proxy struct {
-	balancer         loadbalance.Balancer    // 主负载均衡器
-	fallbackBalancer loadbalance.Balancer    // Lua 失败时的备用均衡器
-	resolver         resolver.Resolver       // DNS 解析器
+	balancer         loadbalance.Balancer            // 主负载均衡器
+	fallbackBalancer loadbalance.Balancer            // Lua 失败时的备用均衡器
+	resolver         resolver.Resolver               // DNS 解析器
 	clients          map[string]*fasthttp.HostClient // 后端连接池，key 为 target URL
-	config           *config.ProxyConfig     // 代理配置
-	cache            *cache.ProxyCache       // 代理缓存
-	healthChecker    *HealthChecker          // 健康检查器
-	luaEngine        *lua.LuaEngine          // Lua 引擎，用于 balancer_by_lua 功能
-	redirectRewriter *RedirectRewriter       // 重定向改写器
-	stopCh           chan struct{}           // 停止信号通道
-	targets          []*loadbalance.Target   // 后端目标列表
-	mu               sync.RWMutex            // 保护并发访问的读写锁
-	started          atomic.Bool             // 代理启动标志
+	config           *config.ProxyConfig             // 代理配置
+	cache            *cache.ProxyCache               // 代理缓存
+	healthChecker    *HealthChecker                  // 健康检查器
+	luaEngine        *lua.LuaEngine                  // Lua 引擎，用于 balancer_by_lua 功能
+	redirectRewriter *RedirectRewriter               // 重定向改写器
+	stopCh           chan struct{}                   // 停止信号通道
+	targets          []*loadbalance.Target           // 后端目标列表
+	mu               sync.RWMutex                    // 保护并发访问的读写锁
+	started          atomic.Bool                     // 代理启动标志
 }
 
 // NewProxy 使用给定的配置和后台目标创建一个新的反向代理实例。
@@ -244,7 +245,7 @@ func createBalancer(cfg *config.ProxyConfig) (loadbalance.Balancer, error) {
 // createHostClient 为指定的后端目标 URL 创建 fasthttp.HostClient。
 //
 // 从目标 URL 解析地址和 TLS 标志，应用 Transport 连接池配置
-//（空闲连接超时、最大连接数），以及上游 SSL 配置。
+// （空闲连接超时、最大连接数），以及上游 SSL 配置。
 //
 // 参数：
 //   - targetURL: 后端目标 URL（如 http://backend:8080）

internal/proxy/proxy_ssl.go

@@ -11,8 +11,9 @@
 //   - 跳过证书验证：仅测试环境使用
 //
 // 主要用途：
-//   用于代理与上游服务器之间的 TLS 连接配置，支持自签名证书、
-//   内部 CA 签发证书以及双向认证场景。
+//
+//	用于代理与上游服务器之间的 TLS 连接配置，支持自签名证书、
+//	内部 CA 签发证书以及双向认证场景。
 //
 // 注意事项：
 //   - InsecureSkipVerify 仅建议在测试环境使用

internal/proxy/redirect_rewrite.go

@@ -12,8 +12,9 @@
 //   - 变量展开：自定义规则中支持 Lolly 变量
 //
 // 主要用途：
-//   用于处理上游服务器返回的 3xx 重定向响应，确保客户端
-//   收到的是代理地址而非内部上游地址。
+//
+//	用于处理上游服务器返回的 3xx 重定向响应，确保客户端
+//	收到的是代理地址而非内部上游地址。
 //
 // 注意事项：
 //   - 调用位置：必须在 modifyResponseHeaders 之前调用
@@ -271,6 +272,7 @@ func (r *RedirectRewriter) rewriteDefault(headerValue string, ctx *fasthttp.Requ
 // 规则按定义顺序匹配，第一个成功的规则生效：
 //   - 正则匹配（~ 或 ~* 前缀）：支持大小写不敏感
 //   - 前缀匹配（无特殊前缀）：使用 HasPrefix 精确前缀匹配
+//
 // 替换模板支持 Lolly 变量展开。
 //
 // 参数：