From 65aaba4e5953eeaaf8d3356f4179d4df3fdbc6d7 Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 01/12] docs(config): add package comments for config module - Add package documentation for cache, monitoring, performance, proxy, security, server, ssl, and variable config files - Include author attribution (xfy) --- internal/config/cache_config.go | 5 +++++ internal/config/monitoring_config.go | 5 +++++ internal/config/performance_config.go | 5 +++++ internal/config/proxy_config.go | 5 +++++ internal/config/security_config.go | 5 +++++ internal/config/server_config.go | 5 +++++ internal/config/ssl_config.go | 5 +++++ internal/config/variable_config.go | 5 +++++ 8 files changed, 40 insertions(+) diff --git a/internal/config/cache_config.go b/internal/config/cache_config.go index 3b7e1e7..97bba9c 100644 --- a/internal/config/cache_config.go +++ b/internal/config/cache_config.go @@ -1,3 +1,8 @@ +// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。 +// +// 包含缓存配置相关的结构体，用于控制代理缓存行为。 +// +// 作者：xfy package config import "time" diff --git a/internal/config/monitoring_config.go b/internal/config/monitoring_config.go index 1aa16fc..f6869b1 100644 --- a/internal/config/monitoring_config.go +++ b/internal/config/monitoring_config.go @@ -1,3 +1,8 @@ +// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。 +// +// 包含监控配置相关的结构体，用于配置服务状态监控和健康检查端点。 +// +// 作者：xfy package config // MonitoringConfig 监控配置。 diff --git a/internal/config/performance_config.go b/internal/config/performance_config.go index b2926b0..6417f6c 100644 --- a/internal/config/performance_config.go +++ b/internal/config/performance_config.go @@ -1,3 +1,8 @@ +// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。 +// +// 包含性能配置相关的结构体，用于控制服务器性能优化参数。 +// +// 作者：xfy package config import ( diff --git a/internal/config/proxy_config.go b/internal/config/proxy_config.go index 6bfa6be..06af244 100644 --- a/internal/config/proxy_config.go +++ b/internal/config/proxy_config.go @@ -1,3 +1,8 @@ +// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。 +// +// 包含代理配置相关的结构体，用于配置反向代理行为。 +// +// 作者：xfy package config import ( diff --git a/internal/config/security_config.go b/internal/config/security_config.go index b0bbfdc..0c34838 100644 --- a/internal/config/security_config.go +++ b/internal/config/security_config.go @@ -1,3 +1,8 @@ +// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。 +// +// 包含安全配置相关的结构体，用于配置访问控制、限流、认证和安全头部。 +// +// 作者：xfy package config import "time" diff --git a/internal/config/server_config.go b/internal/config/server_config.go index 88e41b1..87d4fa8 100644 --- a/internal/config/server_config.go +++ b/internal/config/server_config.go @@ -1,3 +1,8 @@ +// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。 +// +// 包含服务器配置相关的结构体，用于配置监听地址、静态文件、代理、SSL 等设置。 +// +// 作者：xfy package config import "time" diff --git a/internal/config/ssl_config.go b/internal/config/ssl_config.go index 8f0c962..9f27c63 100644 --- a/internal/config/ssl_config.go +++ b/internal/config/ssl_config.go @@ -1,3 +1,8 @@ +// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。 +// +// 包含 SSL/TLS 配置相关的结构体，用于配置 HTTPS 加密参数。 +// +// 作者：xfy package config import "time" diff --git a/internal/config/variable_config.go b/internal/config/variable_config.go index a59935f..d7b19da 100644 --- a/internal/config/variable_config.go +++ b/internal/config/variable_config.go @@ -1,3 +1,8 @@ +// Package config 提供 YAML 配置文件的解析、验证和默认配置生成功能。 +// +// 包含变量配置相关的结构体，用于配置自定义变量和内置变量。 +// +// 作者：xfy package config import "time" From dc54d3822f946d4f4dd80f717263a4ff1a8b3f43 Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 02/12] docs(proxy): add package comments for proxy module - Add package documentation for target_selector, utils, validate, cache_handler, and header_modifier files - Include author attribution (xfy) --- internal/proxy/cache_handler.go | 5 +++++ internal/proxy/header_modifier.go | 5 +++++ internal/proxy/target_selector.go | 5 +++++ internal/proxy/utils.go | 5 +++++ internal/proxy/validate.go | 5 +++++ 5 files changed, 25 insertions(+) diff --git a/internal/proxy/cache_handler.go b/internal/proxy/cache_handler.go index f43062b..f646686 100644 --- a/internal/proxy/cache_handler.go +++ b/internal/proxy/cache_handler.go @@ -1,3 +1,8 @@ +// Package proxy 提供反向代理的核心功能，支持请求转发、负载均衡、健康检查等特性。 +// +// 包含缓存处理器相关的结构体，用于配置代理缓存行为。 +// +// 作者：xfy package proxy import ( diff --git a/internal/proxy/header_modifier.go b/internal/proxy/header_modifier.go index 6e988ba..08b5601 100644 --- a/internal/proxy/header_modifier.go +++ b/internal/proxy/header_modifier.go @@ -1,3 +1,8 @@ +// Package proxy 提供反向代理的核心功能，支持请求转发、负载均衡、健康检查等特性。 +// +// 包含请求头修改器相关的结构体，用于配置请求和响应头修改规则。 +// +// 作者：xfy package proxy import ( diff --git a/internal/proxy/target_selector.go b/internal/proxy/target_selector.go index 6393707..79a2f24 100644 --- a/internal/proxy/target_selector.go +++ b/internal/proxy/target_selector.go @@ -1,3 +1,8 @@ +// Package proxy 提供反向代理的核心功能，支持请求转发、负载均衡、健康检查等特性。 +// +// 包含代理配置相关的结构体，用于配置反向代理行为。 +// +// 作者：xfy package proxy import ( diff --git a/internal/proxy/utils.go b/internal/proxy/utils.go index b75de49..52514cb 100644 --- a/internal/proxy/utils.go +++ b/internal/proxy/utils.go @@ -1,3 +1,8 @@ +// Package proxy 提供反向代理的核心功能，支持请求转发、负载均衡、健康检查等特性。 +// +// 包含代理工具函数，用于处理请求和响应的转换。 +// +// 作者：xfy package proxy import ( diff --git a/internal/proxy/validate.go b/internal/proxy/validate.go index edee1b6..31057e8 100644 --- a/internal/proxy/validate.go +++ b/internal/proxy/validate.go @@ -1,3 +1,8 @@ +// Package proxy 提供反向代理的核心功能，支持请求转发、负载均衡、健康检查等特性。 +// +// 包含代理验证相关的结构体，用于配置请求验证规则。 +// +// 作者：xfy package proxy import "strings" From 05f434d5e558f8c132c727e0c69337729811a60a Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 03/12] docs(server): add package comments for server module - Add package documentation for router, internal, lifecycle, and middleware_builder files - Include author attribution (xfy) --- internal/server/internal.go | 5 +++++ internal/server/lifecycle.go | 5 +++++ internal/server/middleware_builder.go | 5 +++++ internal/server/router.go | 5 +++++ 4 files changed, 20 insertions(+) diff --git a/internal/server/internal.go b/internal/server/internal.go index d6483cd..f0f6c5f 100644 --- a/internal/server/internal.go +++ b/internal/server/internal.go @@ -1,3 +1,8 @@ +// Package server 提供 HTTP 服务器的核心实现，支持单服务器、虚拟主机和多服务器三种运行模式。 +// +// 包含服务器内部工具函数，用于处理服务器运行时逻辑。 +// +// 作者：xfy package server import ( diff --git a/internal/server/lifecycle.go b/internal/server/lifecycle.go index b3b6770..41b169b 100644 --- a/internal/server/lifecycle.go +++ b/internal/server/lifecycle.go @@ -1,3 +1,8 @@ +// Package server 提供 HTTP 服务器的核心实现，支持单服务器、虚拟主机和多服务器三种运行模式。 +// +// 包含服务器生命周期管理相关的逻辑，用于处理启动、停止和信号处理。 +// +// 作者：xfy package server import ( diff --git a/internal/server/middleware_builder.go b/internal/server/middleware_builder.go index e65e13d..19fe81d 100644 --- a/internal/server/middleware_builder.go +++ b/internal/server/middleware_builder.go @@ -1,3 +1,8 @@ +// Package server 提供 HTTP 服务器的核心实现，支持单服务器、虚拟主机和多服务器三种运行模式。 +// +// 包含中间件构建器相关的逻辑，用于构建和管理 HTTP 中间件链。 +// +// 作者：xfy package server import ( diff --git a/internal/server/router.go b/internal/server/router.go index 54c5290..d79bf48 100644 --- a/internal/server/router.go +++ b/internal/server/router.go @@ -1,3 +1,8 @@ +// Package server 提供 HTTP 服务器的核心实现，支持单服务器、虚拟主机和多服务器三种运行模式。 +// +// 包含路由器相关的核心逻辑，用于管理 HTTP 请求的路由分发。 +// +// 作者：xfy package server import ( From c33adeb29622cbfc25680388cb7fa779f2be2f80 Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 04/12] docs(middleware/limitrate): add package comments for rate limiter - Add package documentation for limitrate and writer files - Include author attribution (xfy) --- internal/middleware/limitrate/limitrate.go | 5 +++++ internal/middleware/limitrate/writer.go | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/internal/middleware/limitrate/limitrate.go b/internal/middleware/limitrate/limitrate.go index 0767a43..d19e9cf 100644 --- a/internal/middleware/limitrate/limitrate.go +++ b/internal/middleware/limitrate/limitrate.go @@ -1,3 +1,8 @@ +// Package limitrate 提供基于令牌桶算法的请求速率限制功能。 +// +// 包含速率限制器相关的逻辑，用于控制请求处理速率。 +// +// 作者：xfy package limitrate import ( diff --git a/internal/middleware/limitrate/writer.go b/internal/middleware/limitrate/writer.go index a148c53..ae2437b 100644 --- a/internal/middleware/limitrate/writer.go +++ b/internal/middleware/limitrate/writer.go @@ -1,3 +1,8 @@ +// Package limitrate 提供基于令牌桶算法的请求速率限制功能。 +// +// 包含速率限制响应写入器相关的逻辑，用于处理被限制的请求响应。 +// +// 作者：xfy package limitrate import ( From 4a53d3032aa508c7a74d53cbdbdc5724fa66030e Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 05/12] docs(utils): add package comments for utils module - Add package documentation for internal, etag, and bytes files - Include author attribution (xfy) --- internal/utils/bytes.go | 5 +++++ internal/utils/etag.go | 5 +++++ internal/utils/internal.go | 5 +++++ 3 files changed, 15 insertions(+) diff --git a/internal/utils/bytes.go b/internal/utils/bytes.go index 1741fea..bc890a8 100644 --- a/internal/utils/bytes.go +++ b/internal/utils/bytes.go @@ -1,3 +1,8 @@ +// Package utils 提供通用的工具函数和辅助类型。 +// +// 包含字节操作相关的工具函数，用于处理字节切片和缓冲区。 +// +// 作者：xfy package utils import "unsafe" diff --git a/internal/utils/etag.go b/internal/utils/etag.go index 3385b15..3c6ab37 100644 --- a/internal/utils/etag.go +++ b/internal/utils/etag.go @@ -1,3 +1,8 @@ +// Package utils 提供通用的工具函数和辅助类型。 +// +// 包含 ETag 生成相关的工具函数，用于处理缓存验证。 +// +// 作者：xfy package utils import ( diff --git a/internal/utils/internal.go b/internal/utils/internal.go index 835bf20..62b3f9b 100644 --- a/internal/utils/internal.go +++ b/internal/utils/internal.go @@ -1,3 +1,8 @@ +// Package utils 提供通用的工具函数和辅助类型。 +// +// 包含内部工具函数，用于处理内部逻辑。 +// +// 作者：xfy package utils import "github.com/valyala/fasthttp" From 63ce8ecd2a56ccbc47b3ca9f893d9ee5cd12280c Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 06/12] docs(lua): add package comments for lua module - Add package documentation for ip_guard file - Include author attribution (xfy) --- internal/lua/ip_guard.go | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/internal/lua/ip_guard.go b/internal/lua/ip_guard.go index ec2d5a5..96ffd42 100644 --- a/internal/lua/ip_guard.go +++ b/internal/lua/ip_guard.go @@ -1,3 +1,8 @@ +// Package lua 提供 Lua 脚本扩展功能，支持 IP 黑白名单、请求处理等。 +// +// 包含 IP 守卫相关的逻辑，用于处理 IP 黑白名单功能。 +// +// 作者：xfy package lua import "net" From 57d4d3ba3cc15a628dac2adaab9599b2817ad694 Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 07/12] docs(app): add package comments for app module - Add package documentation for app, app_common, import, app_windows, and testutil files - Include author attribution (xfy) --- internal/app/app.go | 5 +++++ internal/app/app_common.go | 5 +++++ internal/app/app_windows.go | 5 +++++ internal/app/import.go | 5 +++++ internal/app/testutil.go | 5 +++++ 5 files changed, 25 insertions(+) diff --git a/internal/app/app.go b/internal/app/app.go index aa47e68..39208a1 100644 --- a/internal/app/app.go +++ b/internal/app/app.go @@ -1,5 +1,10 @@ //go:build !windows +// Package app 提供 Lolly 应用程序的生命周期管理和命令行入口。 +// +// 包含应用生命周期管理和命令行入口相关的逻辑。 +// +// 作者：xfy package app import ( diff --git a/internal/app/app_common.go b/internal/app/app_common.go index 82fe474..86b924a 100644 --- a/internal/app/app_common.go +++ b/internal/app/app_common.go @@ -1,3 +1,8 @@ +// Package app 提供 Lolly 应用程序的生命周期管理和命令行入口。 +// +// 包含应用通用逻辑相关的工具函数。 +// +// 作者：xfy package app import ( diff --git a/internal/app/app_windows.go b/internal/app/app_windows.go index 9d150f6..c2dcd99 100644 --- a/internal/app/app_windows.go +++ b/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 ( diff --git a/internal/app/import.go b/internal/app/import.go index 0df1198..8a8a743 100644 --- a/internal/app/import.go +++ b/internal/app/import.go @@ -1,3 +1,8 @@ +// Package app 提供 Lolly 应用程序的生命周期管理和命令行入口。 +// +// 包含配置导入相关的逻辑，用于导入 nginx 配置等外部配置。 +// +// 作者：xfy package app import ( diff --git a/internal/app/testutil.go b/internal/app/testutil.go index 6fc58ff..b7f36b5 100644 --- a/internal/app/testutil.go +++ b/internal/app/testutil.go @@ -1,5 +1,10 @@ //go:build !windows +// Package app 提供 Lolly 应用程序的生命周期管理和命令行入口。 +// +// 包含测试工具函数，用于测试场景。 +// +// 作者：xfy package app import ( From 0b5b0eb74705070f580bd7fd66c9f2833a9cd5b5 Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 08/12] docs(loadbalance): add package comments for loadbalance module - Add package documentation for random load balancing file - Include author attribution (xfy) --- internal/loadbalance/random.go | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/internal/loadbalance/random.go b/internal/loadbalance/random.go index 02acbeb..04bead9 100644 --- a/internal/loadbalance/random.go +++ b/internal/loadbalance/random.go @@ -1,3 +1,8 @@ +// Package loadbalance 提供多种负载均衡算法实现，支持随机、轮询、加权、一致性哈希等策略。 +// +// 包含随机负载均衡算法相关的逻辑。 +// +// 作者：xfy package loadbalance import ( From 396a466de113925a4331e391f8fdd64e9487d147 Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 09/12] docs: add documentation comments for exported constants and variables - Add comments for lua/api_log.go HTTP status codes and log levels - Add comments for variable/builtin.go and ssl.go constants - Add comments for utils/httperror.go error variables - Add comments for matcher/matcher.go location types - Add comments for compression/compression.go algorithms - Include author attribution (xfy) --- doc-report.md | 315 ++++++++++++++++++ gjson/gjson.go | 7 +- internal/lua/api_log.go | 84 ++--- internal/matcher/matcher.go | 18 +- .../middleware/compression/compression.go | 4 +- internal/utils/httperror.go | 16 +- internal/variable/builtin.go | 42 +-- internal/variable/ssl.go | 9 + 8 files changed, 414 insertions(+), 81 deletions(-) create mode 100644 doc-report.md diff --git a/doc-report.md b/doc-report.md new file mode 100644 index 0000000..bd3e7c4 --- /dev/null +++ b/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 目录已排除。* diff --git a/gjson/gjson.go b/gjson/gjson.go index eb632d5..80741e1 100644 --- a/gjson/gjson.go +++ b/gjson/gjson.go @@ -24,6 +24,9 @@ // - Independent configuration instances via gjson.new() // // Author: xfy +// Package gjson 提供 Go 模块信息。 +// +// 作者：xfy package gjson import ( @@ -32,10 +35,10 @@ import ( const ( // ModuleName is the Lua module name for require() - ModuleName = "gjson" +// ModuleName 模块名称。 = "gjson" // Version is the module version - Version = "1.0.0" +// Version 模块版本号。 = "1.0.0" ) // Preload registers the gjson module as a preload in the given LState. diff --git a/internal/lua/api_log.go b/internal/lua/api_log.go index f9e8967..a362c23 100644 --- a/internal/lua/api_log.go +++ b/internal/lua/api_log.go @@ -26,52 +26,52 @@ import ( // 日志级别常量（与 OpenResty/ngx_lua 兼容） const ( - LogStderr = 0 - LogEmerg = 1 - LogAlert = 2 - LogCrit = 3 - LogErr = 4 - LogWarn = 5 - LogNotice = 6 - LogInfo = 7 - LogDebug = 8 +// LogStderr 标准错误日志级别。 = 0 +// LogEmerg 紧急日志级别。 = 1 +// LogAlert 警报日志级别。 = 2 +// LogCrit 严重日志级别。 = 3 +// LogErr 错误日志级别。 = 4 +// LogWarn 警告日志级别。 = 5 +// LogNotice 通知日志级别。 = 6 +// LogInfo 信息日志级别。 = 7 +// LogDebug 调试日志级别。 = 8 ) // HTTP 状态码常量 const ( - HTTPContinue = 100 - HTTPSwitchingProtocols = 101 - HTTPOK = 200 - HTTPCreated = 201 - HTTPAccepted = 202 - HTTPNoContent = 204 - HTTPPartialContent = 206 - HTTPMovedPermanently = 301 - HTTPFound = 302 - HTTPSeeOther = 303 - HTTPNotModified = 304 - HTTPTemporaryRedirect = 307 - HTTPPermanentRedirect = 308 - HTTPBadRequest = 400 - HTTPUnauthorized = 401 - HTTPForbidden = 403 - HTTPNotFound = 404 - HTTPMethodNotAllowed = 405 - HTTPRequestTimeout = 408 - HTTPConflict = 409 - HTTPGone = 410 - HTTPLengthRequired = 411 - HTTPPayloadTooLarge = 413 - HTTPURITooLong = 414 - HTTPUnsupportedMedia = 415 - HTTPRangeNotSatisfiable = 416 - HTTPTooManyRequests = 429 - HTTPInternalServerError = 500 - HTTPNotImplemented = 501 - HTTPBadGateway = 502 - HTTPServiceUnavailable = 503 - HTTPGatewayTimeout = 504 - HTTPHTTPVersionNotSupported = 505 +// HTTPContinue HTTP 100 继续状态码。 = 100 +// HTTPSwitchingProtocols HTTP 101 切换协议状态码。 = 101 +// HTTPOK HTTP 200 成功状态码。 = 200 +// HTTPCreated HTTP 201 已创建状态码。 = 201 +// HTTPAccepted HTTP 202 已接受状态码。 = 202 +// HTTPNoContent HTTP 204 无内容状态码。 = 204 +// HTTPPartialContent HTTP 206 部分内容状态码。 = 206 +// HTTPMovedPermanently HTTP 301 永久重定向状态码。 = 301 +// HTTPFound HTTP 302 找到状态码。 = 302 +// HTTPSeeOther HTTP 303 查看其他状态码。 = 303 +// HTTPNotModified HTTP 304 未修改状态码。 = 304 +// HTTPTemporaryRedirect HTTP 307 临时重定向状态码。 = 307 +// HTTPPermanentRedirect HTTP 308 永久重定向状态码。 = 308 +// HTTPBadRequest HTTP 400 错误请求状态码。 = 400 +// HTTPUnauthorized HTTP 401 未授权状态码。 = 401 +// HTTPForbidden HTTP 403 禁止访问状态码。 = 403 +// HTTPNotFound HTTP 404 未找到状态码。 = 404 +// HTTPMethodNotAllowed HTTP 405 方法不允许状态码。 = 405 +// HTTPRequestTimeout HTTP 408 请求超时状态码。 = 408 +// HTTPConflict HTTP 409 冲突状态码。 = 409 +// HTTPGone HTTP 410 已移除状态码。 = 410 +// HTTPLengthRequired HTTP 411 需要长度状态码。 = 411 +// HTTPPayloadTooLarge HTTP 413 请求实体过大状态码。 = 413 +// HTTPURITooLong HTTP 414 URI 过长状态码。 = 414 +// HTTPUnsupportedMedia HTTP 415 不支持的媒体类型状态码。 = 415 +// HTTPRangeNotSatisfiable HTTP 416 范围不可满足状态码。 = 416 +// HTTPTooManyRequests HTTP 429 请求过多状态码。 = 429 +// HTTPInternalServerError HTTP 500 内部服务器错误状态码。 = 500 +// HTTPNotImplemented HTTP 501 未实现状态码。 = 501 +// HTTPBadGateway HTTP 502 错误网关状态码。 = 502 +// HTTPServiceUnavailable HTTP 503 服务不可用状态码。 = 503 +// HTTPGatewayTimeout HTTP 504 网关超时状态码。 = 504 +// HTTPHTTPVersionNotSupported HTTP 505 HTTP 版本不支持状态码。 = 505 ) // ngxLogAPI 封装 ngx.log 和输出控制相关的 API。 diff --git a/internal/matcher/matcher.go b/internal/matcher/matcher.go index d69f9d1..8a70540 100644 --- a/internal/matcher/matcher.go +++ b/internal/matcher/matcher.go @@ -24,12 +24,18 @@ import "github.com/valyala/fasthttp" // LocationType 常量定义，表示不同 location 匹配类型。 const ( - LocationTypeExact = "exact" // 精确匹配 = - LocationTypePrefix = "prefix" // 普通前缀匹配 - LocationTypePrefixPriority = "prefix_priority" // 前缀优先匹配 ^~ - LocationTypeRegex = "regex" // 正则匹配 ~ - LocationTypeRegexCaseless = "regex_caseless" // 大小写不敏感正则匹配 ~* - LocationTypeNamed = "named" // 命名匹配 @name +// LocationTypeExact 精确匹配类型（=）。 + LocationTypeExact = "exact" +// LocationTypePrefix 前缀匹配类型。 + LocationTypePrefix = "prefix" +// LocationTypePrefixPriority 前缀优先匹配类型（^~）。 + LocationTypePrefixPriority = "prefix_priority" +// LocationTypeRegex 正则匹配类型（~）。 + LocationTypeRegex = "regex" +// LocationTypeRegexCaseless 大小写不敏感正则匹配类型（~*）。 + LocationTypeRegexCaseless = "regex_caseless" +// LocationTypeNamed 命名匹配类型（@name）。 + LocationTypeNamed = "named" ) // MatchResult 匹配结果。 diff --git a/internal/middleware/compression/compression.go b/internal/middleware/compression/compression.go index 2ee19d3..c50919f 100644 --- a/internal/middleware/compression/compression.go +++ b/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" diff --git a/internal/utils/httperror.go b/internal/utils/httperror.go index d2c3aab..a32ccfa 100644 --- a/internal/utils/httperror.go +++ b/internal/utils/httperror.go @@ -23,14 +23,14 @@ type HTTPError struct { // Predefined common HTTP errors. var ( - ErrNotFound = HTTPError{Message: "Not Found", StatusCode: fasthttp.StatusNotFound} - ErrForbidden = HTTPError{Message: "Forbidden", StatusCode: fasthttp.StatusForbidden} - ErrUnauthorized = HTTPError{Message: "Unauthorized", StatusCode: fasthttp.StatusUnauthorized} - ErrBadGateway = HTTPError{Message: "Bad Gateway", StatusCode: fasthttp.StatusBadGateway} - ErrGatewayTimeout = HTTPError{Message: "Gateway Timeout", StatusCode: fasthttp.StatusGatewayTimeout} - ErrInternalError = HTTPError{Message: "Internal Server Error", StatusCode: fasthttp.StatusInternalServerError} - ErrTooManyRequests = HTTPError{Message: "Too Many Requests", StatusCode: fasthttp.StatusTooManyRequests} - ErrServiceUnavailable = HTTPError{Message: "Service Unavailable", StatusCode: fasthttp.StatusServiceUnavailable} +// ErrNotFound 资源未找到错误。 = HTTPError{Message: "Not Found", StatusCode: fasthttp.StatusNotFound} +// ErrForbidden 禁止访问错误。 = HTTPError{Message: "Forbidden", StatusCode: fasthttp.StatusForbidden} +// ErrUnauthorized 未授权错误。 = HTTPError{Message: "Unauthorized", StatusCode: fasthttp.StatusUnauthorized} +// ErrBadGateway 错误网关错误。 = HTTPError{Message: "Bad Gateway", StatusCode: fasthttp.StatusBadGateway} +// ErrGatewayTimeout 网关超时错误。 = HTTPError{Message: "Gateway Timeout", StatusCode: fasthttp.StatusGatewayTimeout} +// ErrInternalError 内部服务器错误。 = HTTPError{Message: "Internal Server Error", StatusCode: fasthttp.StatusInternalServerError} +// ErrTooManyRequests 请求过多错误。 = HTTPError{Message: "Too Many Requests", StatusCode: fasthttp.StatusTooManyRequests} +// ErrServiceUnavailable 服务不可用错误。 = HTTPError{Message: "Service Unavailable", StatusCode: fasthttp.StatusServiceUnavailable} ) // SendError sends an HTTP error response to the client. diff --git a/internal/variable/builtin.go b/internal/variable/builtin.go index ec246a2..ab249fd 100644 --- a/internal/variable/builtin.go +++ b/internal/variable/builtin.go @@ -16,28 +16,28 @@ import ( // 内置变量常量 const ( - VarHost = "host" - VarRemoteAddr = "remote_addr" - VarRemotePort = "remote_port" - VarRequestURI = "request_uri" - VarURI = "uri" - VarArgs = "args" - VarRequestMethod = "request_method" - VarScheme = "scheme" - VarServerName = "server_name" - VarServerPort = "server_port" - VarStatus = "status" - VarBodyBytesSent = "body_bytes_sent" - VarRequestTime = "request_time" - VarTimeLocal = "time_local" - VarTimeISO8601 = "time_iso8601" - VarRequestID = "request_id" +// VarHost 请求主机名变量。 = "host" +// VarRemoteAddr 客户端地址变量。 = "remote_addr" +// VarRemotePort 客户端端口变量。 = "remote_port" +// VarRequestURI 请求 URI 变量。 = "request_uri" +// VarURI URI 变量。 = "uri" +// VarArgs 查询参数变量。 = "args" +// VarRequestMethod 请求方法变量。 = "request_method" +// VarScheme 协议方案变量。 = "scheme" +// VarServerName 服务器名称变量。 = "server_name" +// VarServerPort 服务器端口变量。 = "server_port" +// VarStatus HTTP 状态码变量。 = "status" +// VarBodyBytesSent 发送字节数变量。 = "body_bytes_sent" +// VarRequestTime 请求处理时间变量。 = "request_time" +// VarTimeLocal 本地时间变量。 = "time_local" +// VarTimeISO8601 ISO8601 时间变量。 = "time_iso8601" +// VarRequestID 请求 ID 变量。 = "request_id" // 上游变量 - VarUpstreamAddr = "upstream_addr" - VarUpstreamStatus = "upstream_status" - VarUpstreamResponseTime = "upstream_response_time" - VarUpstreamConnectTime = "upstream_connect_time" - VarUpstreamHeaderTime = "upstream_header_time" +// VarUpstreamAddr 上游地址变量。 = "upstream_addr" +// VarUpstreamStatus 上游状态码变量。 = "upstream_status" +// VarUpstreamResponseTime 上游响应时间变量。 = "upstream_response_time" +// VarUpstreamConnectTime 上游连接时间变量。 = "upstream_connect_time" +// VarUpstreamHeaderTime 上游响应头时间变量。 = "upstream_header_time" ) // init 注册所有内置变量 diff --git a/internal/variable/ssl.go b/internal/variable/ssl.go index f7ddb7c..03bec03 100644 --- a/internal/variable/ssl.go +++ b/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" From fc1de2d4453dc2d9506eeac9c5d975da2fd06bb2 Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 10/12] docs: add documentation comments for more exported constants and variables - Add comments for ssl/client_verify.go verification modes - Add comments for security/auth.go hash algorithms - Add comments for rewrite/rewrite.go flags - Add comments for compression/compression.go algorithms - Add comments for limitrate/limitrate.go strategies - Include author attribution (xfy) --- internal/config/config.go | 10 +++++----- internal/middleware/limitrate/limitrate.go | 2 ++ internal/middleware/rewrite/rewrite.go | 8 ++++---- internal/middleware/security/access.go | 4 ++-- internal/middleware/security/auth.go | 4 ++-- internal/ssl/client_verify.go | 8 ++++---- 6 files changed, 19 insertions(+), 17 deletions(-) diff --git a/internal/config/config.go b/internal/config/config.go index b790326..b550485 100644 --- a/internal/config/config.go +++ b/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" ) diff --git a/internal/middleware/limitrate/limitrate.go b/internal/middleware/limitrate/limitrate.go index d19e9cf..d8b1628 100644 --- a/internal/middleware/limitrate/limitrate.go +++ b/internal/middleware/limitrate/limitrate.go @@ -12,8 +12,10 @@ import ( const ( // LargeFileStrategySkip 跳过大文件限速 +// LargeFileStrategySkip 大文件策略：跳过（不限制）。 LargeFileStrategySkip = "skip" // LargeFileStrategyCoarse 粗粒度限速 +// LargeFileStrategyCoarse 大文件策略：粗略限制。 LargeFileStrategyCoarse = "coarse" ) diff --git a/internal/middleware/rewrite/rewrite.go b/internal/middleware/rewrite/rewrite.go index e9db6ea..eade247 100644 --- a/internal/middleware/rewrite/rewrite.go +++ b/internal/middleware/rewrite/rewrite.go @@ -36,16 +36,16 @@ const MaxRewriteIterations = 10 type Flag int const ( - // FlagLast 继续匹配其他规则（nginx 行为：重新从第一条规则开始匹配）。 +// FlagLast 继续匹配其他规则（nginx 行为：重新从第一条规则开始匹配）。 // 匹配到规则后会重新从第一条规则开始遍历，用于多规则链式重写。 FlagLast Flag = iota - // FlagRedirect 返回 302 临时重定向。 +// FlagRedirect 返回 302 临时重定向。 // 客户端收到 302 响应后重新请求新 URL，不会继续匹配后续规则。 FlagRedirect - // FlagPermanent 返回 301 永久重定向。 +// FlagPermanent 返回 301 永久重定向。 // 客户端收到 301 响应后永久重定向到新 URL，不会继续匹配后续规则。 FlagPermanent - // FlagBreak 停止匹配规则。 +// FlagBreak 停止匹配规则。 // 修改请求路径后终止重写流程，直接进入下一个处理器。 FlagBreak ) diff --git a/internal/middleware/security/access.go b/internal/middleware/security/access.go index 919b616..393d199 100644 --- a/internal/middleware/security/access.go +++ b/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" diff --git a/internal/middleware/security/auth.go b/internal/middleware/security/auth.go index fbf2b61..dd7e046 100644 --- a/internal/middleware/security/auth.go +++ b/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 ) diff --git a/internal/ssl/client_verify.go b/internal/ssl/client_verify.go index 43cb2ea..af99a40 100644 --- a/internal/ssl/client_verify.go +++ b/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 验证模式字符串常量 From a136b07bb95d2cf12e59a5f892d1adf411af3f00 Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 11/12] docs: add documentation comments for exported constants and variables - Fix gjson/gjson.go package comments and constant documentation - Fix internal/config/config.go constant documentation - Fix internal/utils/httperror.go variable documentation - Fix internal/matcher/matcher.go constant documentation - Fix internal/middleware/compression/compression.go constant documentation - Fix internal/middleware/limitrate/limitrate.go constant documentation - Fix internal/middleware/rewrite/rewrite.go constant documentation - Fix internal/middleware/security/access.go and auth.go constant documentation - Fix internal/ssl/client_verify.go constant documentation - Fix internal/variable/builtin.go and ssl.go constant documentation - Fix internal/lua/api_log.go HTTP and log level constant documentation - Fix internal/benchmark/tools/tools.go constant documentation - Include author attribution (xfy) --- gjson/gjson.go | 11 +- internal/benchmark/tools/tools.go | 29 ++-- internal/lua/api_log.go | 126 ++++++++++++------ internal/matcher/matcher.go | 10 +- .../middleware/compression/compression.go | 2 +- internal/middleware/limitrate/limitrate.go | 6 +- internal/middleware/rewrite/rewrite.go | 8 +- internal/middleware/security/access.go | 2 +- internal/middleware/security/auth.go | 2 +- internal/ssl/client_verify.go | 6 +- internal/utils/httperror.go | 24 ++-- internal/variable/builtin.go | 63 ++++++--- internal/variable/ssl.go | 16 +-- 13 files changed, 192 insertions(+), 113 deletions(-) diff --git a/gjson/gjson.go b/gjson/gjson.go index 80741e1..e60c632 100644 --- a/gjson/gjson.go +++ b/gjson/gjson.go @@ -23,9 +23,6 @@ // - Number precision control // - Independent configuration instances via gjson.new() // -// Author: xfy -// Package gjson 提供 Go 模块信息。 -// // 作者：xfy package gjson @@ -34,11 +31,11 @@ import ( ) const ( - // ModuleName is the Lua module name for require() -// ModuleName 模块名称。 = "gjson" + // ModuleName 模块名称。 + ModuleName = "gjson" - // Version is the module version -// Version 模块版本号。 = "1.0.0" + // Version 模块版本号。 + Version = "1.0.0" ) // Preload registers the gjson module as a preload in the given LState. diff --git a/internal/benchmark/tools/tools.go b/internal/benchmark/tools/tools.go index 79be0cf..706a1a8 100644 --- a/internal/benchmark/tools/tools.go +++ b/internal/benchmark/tools/tools.go @@ -1,4 +1,8 @@ // Package tools 提供基准测试和集成测试的辅助工具。 +// +// 包含 Mock 后端创建、测试数据生成等工具函数。 +// +// 作者：xfy package tools import ( @@ -10,14 +14,19 @@ import ( // 预定义的测试数据大小常量 const ( - Size100B = 100 - Size1KB = 1024 - Size10KB = 10 * 1024 + // Size100B 100 字节测试数据。 + Size100B = 100 + // Size1KB 1KB 测试数据。 + Size1KB = 1024 + // Size10KB 10KB 测试数据。 + Size10KB = 10 * 1024 + // Size100KB 100KB 测试数据。 Size100KB = 100 * 1024 - Size1MB = 1024 * 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 = "normal" - ModeRandomResponse = "random" - ModeErrorResponse = "error" + // ModeNormalResponse 正常响应模式。 + ModeNormalResponse = "normal" + // ModeRandomResponse 随机响应模式。 + ModeRandomResponse = "random" + // ModeErrorResponse 错误响应模式。 + ModeErrorResponse = "error" + // ModeDelayedResponse 延迟响应模式。 ModeDelayedResponse = "delayed" ) diff --git a/internal/lua/api_log.go b/internal/lua/api_log.go index a362c23..98b8e7b 100644 --- a/internal/lua/api_log.go +++ b/internal/lua/api_log.go @@ -26,52 +26,94 @@ import ( // 日志级别常量（与 OpenResty/ngx_lua 兼容） const ( -// LogStderr 标准错误日志级别。 = 0 -// LogEmerg 紧急日志级别。 = 1 -// LogAlert 警报日志级别。 = 2 -// LogCrit 严重日志级别。 = 3 -// LogErr 错误日志级别。 = 4 -// LogWarn 警告日志级别。 = 5 -// LogNotice 通知日志级别。 = 6 -// LogInfo 信息日志级别。 = 7 -// LogDebug 调试日志级别。 = 8 +// 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 继续状态码。 = 100 -// HTTPSwitchingProtocols HTTP 101 切换协议状态码。 = 101 -// HTTPOK HTTP 200 成功状态码。 = 200 -// HTTPCreated HTTP 201 已创建状态码。 = 201 -// HTTPAccepted HTTP 202 已接受状态码。 = 202 -// HTTPNoContent HTTP 204 无内容状态码。 = 204 -// HTTPPartialContent HTTP 206 部分内容状态码。 = 206 -// HTTPMovedPermanently HTTP 301 永久重定向状态码。 = 301 -// HTTPFound HTTP 302 找到状态码。 = 302 -// HTTPSeeOther HTTP 303 查看其他状态码。 = 303 -// HTTPNotModified HTTP 304 未修改状态码。 = 304 -// HTTPTemporaryRedirect HTTP 307 临时重定向状态码。 = 307 -// HTTPPermanentRedirect HTTP 308 永久重定向状态码。 = 308 -// HTTPBadRequest HTTP 400 错误请求状态码。 = 400 -// HTTPUnauthorized HTTP 401 未授权状态码。 = 401 -// HTTPForbidden HTTP 403 禁止访问状态码。 = 403 -// HTTPNotFound HTTP 404 未找到状态码。 = 404 -// HTTPMethodNotAllowed HTTP 405 方法不允许状态码。 = 405 -// HTTPRequestTimeout HTTP 408 请求超时状态码。 = 408 -// HTTPConflict HTTP 409 冲突状态码。 = 409 -// HTTPGone HTTP 410 已移除状态码。 = 410 -// HTTPLengthRequired HTTP 411 需要长度状态码。 = 411 -// HTTPPayloadTooLarge HTTP 413 请求实体过大状态码。 = 413 -// HTTPURITooLong HTTP 414 URI 过长状态码。 = 414 -// HTTPUnsupportedMedia HTTP 415 不支持的媒体类型状态码。 = 415 -// HTTPRangeNotSatisfiable HTTP 416 范围不可满足状态码。 = 416 -// HTTPTooManyRequests HTTP 429 请求过多状态码。 = 429 -// HTTPInternalServerError HTTP 500 内部服务器错误状态码。 = 500 -// HTTPNotImplemented HTTP 501 未实现状态码。 = 501 -// HTTPBadGateway HTTP 502 错误网关状态码。 = 502 -// HTTPServiceUnavailable HTTP 503 服务不可用状态码。 = 503 -// HTTPGatewayTimeout HTTP 504 网关超时状态码。 = 504 -// HTTPHTTPVersionNotSupported HTTP 505 HTTP 版本不支持状态码。 = 505 +// 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 ) // ngxLogAPI 封装 ngx.log 和输出控制相关的 API。 diff --git a/internal/matcher/matcher.go b/internal/matcher/matcher.go index 8a70540..324094f 100644 --- a/internal/matcher/matcher.go +++ b/internal/matcher/matcher.go @@ -26,15 +26,15 @@ import "github.com/valyala/fasthttp" const ( // LocationTypeExact 精确匹配类型（=）。 LocationTypeExact = "exact" -// LocationTypePrefix 前缀匹配类型。 + // LocationTypePrefix 前缀匹配类型。 LocationTypePrefix = "prefix" -// LocationTypePrefixPriority 前缀优先匹配类型（^~）。 + // LocationTypePrefixPriority 前缀优先匹配类型（^~）。 LocationTypePrefixPriority = "prefix_priority" -// LocationTypeRegex 正则匹配类型（~）。 + // LocationTypeRegex 正则匹配类型（~）。 LocationTypeRegex = "regex" -// LocationTypeRegexCaseless 大小写不敏感正则匹配类型（~*）。 + // LocationTypeRegexCaseless 大小写不敏感正则匹配类型（~*）。 LocationTypeRegexCaseless = "regex_caseless" -// LocationTypeNamed 命名匹配类型（@name）。 + // LocationTypeNamed 命名匹配类型（@name）。 LocationTypeNamed = "named" ) diff --git a/internal/middleware/compression/compression.go b/internal/middleware/compression/compression.go index c50919f..1f20b92 100644 --- a/internal/middleware/compression/compression.go +++ b/internal/middleware/compression/compression.go @@ -98,7 +98,7 @@ type Algorithm int const ( // AlgorithmGzip 使用 gzip 压缩算法。 AlgorithmGzip Algorithm = iota -// AlgorithmBrotli 使用 brotli 压缩算法。 + // AlgorithmBrotli 使用 brotli 压缩算法。 AlgorithmBrotli compressionGZIP = "gzip" diff --git a/internal/middleware/limitrate/limitrate.go b/internal/middleware/limitrate/limitrate.go index d8b1628..ca4b2f7 100644 --- a/internal/middleware/limitrate/limitrate.go +++ b/internal/middleware/limitrate/limitrate.go @@ -11,11 +11,9 @@ import ( ) const ( - // LargeFileStrategySkip 跳过大文件限速 -// LargeFileStrategySkip 大文件策略：跳过（不限制）。 + // LargeFileStrategySkip 大文件策略：跳过（不限制）。 LargeFileStrategySkip = "skip" - // LargeFileStrategyCoarse 粗粒度限速 -// LargeFileStrategyCoarse 大文件策略：粗略限制。 + // LargeFileStrategyCoarse 大文件策略：粗略限制。 LargeFileStrategyCoarse = "coarse" ) diff --git a/internal/middleware/rewrite/rewrite.go b/internal/middleware/rewrite/rewrite.go index eade247..8501650 100644 --- a/internal/middleware/rewrite/rewrite.go +++ b/internal/middleware/rewrite/rewrite.go @@ -29,7 +29,7 @@ import ( "rua.plus/lolly/internal/variable" ) -// MaxRewriteIterations URL重写最大迭代次数，防止无限循环 +// MaxRewriteIterations URL重写最大迭代次数，防止无限循环。 const MaxRewriteIterations = 10 // Flag 重写标志类型。 @@ -39,13 +39,13 @@ const ( // FlagLast 继续匹配其他规则（nginx 行为：重新从第一条规则开始匹配）。 // 匹配到规则后会重新从第一条规则开始遍历，用于多规则链式重写。 FlagLast Flag = iota -// FlagRedirect 返回 302 临时重定向。 + // FlagRedirect 返回 302 临时重定向。 // 客户端收到 302 响应后重新请求新 URL，不会继续匹配后续规则。 FlagRedirect -// FlagPermanent 返回 301 永久重定向。 + // FlagPermanent 返回 301 永久重定向。 // 客户端收到 301 响应后永久重定向到新 URL，不会继续匹配后续规则。 FlagPermanent -// FlagBreak 停止匹配规则。 + // FlagBreak 停止匹配规则。 // 修改请求路径后终止重写流程，直接进入下一个处理器。 FlagBreak ) diff --git a/internal/middleware/security/access.go b/internal/middleware/security/access.go index 393d199..7679030 100644 --- a/internal/middleware/security/access.go +++ b/internal/middleware/security/access.go @@ -45,7 +45,7 @@ type Action int const ( // ActionAllow 允许请求通过。 ActionAllow Action = iota -// ActionDeny 拒绝请求（返回 403 Forbidden）。 + // ActionDeny 拒绝请求（返回 403 Forbidden）。 ActionDeny accessAllow = "allow" diff --git a/internal/middleware/security/auth.go b/internal/middleware/security/auth.go index dd7e046..0349f7b 100644 --- a/internal/middleware/security/auth.go +++ b/internal/middleware/security/auth.go @@ -50,7 +50,7 @@ type HashAlgorithm int const ( // HashBcrypt bcrypt 哈希算法（默认，推荐）。 HashBcrypt HashAlgorithm = iota -// HashArgon2id Argon2id 哈希算法（更安全，计算密集）。 + // HashArgon2id Argon2id 哈希算法（更安全，计算密集）。 HashArgon2id ) diff --git a/internal/ssl/client_verify.go b/internal/ssl/client_verify.go index af99a40..f5dbc77 100644 --- a/internal/ssl/client_verify.go +++ b/internal/ssl/client_verify.go @@ -31,11 +31,11 @@ type ClientVerifyMode int const ( // VerifyOff 不验证客户端证书。 VerifyOff ClientVerifyMode = iota -// VerifyOn 强制验证客户端证书。 + // VerifyOn 强制验证客户端证书。 VerifyOn -// VerifyOptional 可选验证（客户端可选择不提供证书）。 + // VerifyOptional 可选验证（客户端可选择不提供证书）。 VerifyOptional -// VerifyOptionalNoCA 可选验证但不验证 CA。 + // VerifyOptionalNoCA 可选验证但不验证 CA。 VerifyOptionalNoCA // verifyModeOff 验证模式字符串常量 diff --git a/internal/utils/httperror.go b/internal/utils/httperror.go index a32ccfa..9348ba4 100644 --- a/internal/utils/httperror.go +++ b/internal/utils/httperror.go @@ -23,14 +23,22 @@ type HTTPError struct { // Predefined common HTTP errors. var ( -// ErrNotFound 资源未找到错误。 = HTTPError{Message: "Not Found", StatusCode: fasthttp.StatusNotFound} -// ErrForbidden 禁止访问错误。 = HTTPError{Message: "Forbidden", StatusCode: fasthttp.StatusForbidden} -// ErrUnauthorized 未授权错误。 = HTTPError{Message: "Unauthorized", StatusCode: fasthttp.StatusUnauthorized} -// ErrBadGateway 错误网关错误。 = HTTPError{Message: "Bad Gateway", StatusCode: fasthttp.StatusBadGateway} -// ErrGatewayTimeout 网关超时错误。 = HTTPError{Message: "Gateway Timeout", StatusCode: fasthttp.StatusGatewayTimeout} -// ErrInternalError 内部服务器错误。 = HTTPError{Message: "Internal Server Error", StatusCode: fasthttp.StatusInternalServerError} -// ErrTooManyRequests 请求过多错误。 = HTTPError{Message: "Too Many Requests", StatusCode: fasthttp.StatusTooManyRequests} -// ErrServiceUnavailable 服务不可用错误。 = HTTPError{Message: "Service Unavailable", StatusCode: fasthttp.StatusServiceUnavailable} +// 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} ) // SendError sends an HTTP error response to the client. diff --git a/internal/variable/builtin.go b/internal/variable/builtin.go index ab249fd..4d7e6ae 100644 --- a/internal/variable/builtin.go +++ b/internal/variable/builtin.go @@ -16,28 +16,49 @@ import ( // 内置变量常量 const ( -// VarHost 请求主机名变量。 = "host" -// VarRemoteAddr 客户端地址变量。 = "remote_addr" -// VarRemotePort 客户端端口变量。 = "remote_port" -// VarRequestURI 请求 URI 变量。 = "request_uri" -// VarURI URI 变量。 = "uri" -// VarArgs 查询参数变量。 = "args" -// VarRequestMethod 请求方法变量。 = "request_method" -// VarScheme 协议方案变量。 = "scheme" -// VarServerName 服务器名称变量。 = "server_name" -// VarServerPort 服务器端口变量。 = "server_port" -// VarStatus HTTP 状态码变量。 = "status" -// VarBodyBytesSent 发送字节数变量。 = "body_bytes_sent" -// VarRequestTime 请求处理时间变量。 = "request_time" -// VarTimeLocal 本地时间变量。 = "time_local" -// VarTimeISO8601 ISO8601 时间变量。 = "time_iso8601" -// VarRequestID 请求 ID 变量。 = "request_id" +// 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 上游地址变量。 = "upstream_addr" -// VarUpstreamStatus 上游状态码变量。 = "upstream_status" -// VarUpstreamResponseTime 上游响应时间变量。 = "upstream_response_time" -// VarUpstreamConnectTime 上游连接时间变量。 = "upstream_connect_time" -// VarUpstreamHeaderTime 上游响应头时间变量。 = "upstream_header_time" + // VarUpstreamAddr 上游地址变量。 + VarUpstreamAddr = "upstream_addr" + // VarUpstreamStatus 上游状态码变量。 + VarUpstreamStatus = "upstream_status" + // VarUpstreamResponseTime 上游响应时间变量。 + VarUpstreamResponseTime = "upstream_response_time" + // VarUpstreamConnectTime 上游连接时间变量。 + VarUpstreamConnectTime = "upstream_connect_time" + // VarUpstreamHeaderTime 上游响应头时间变量。 + VarUpstreamHeaderTime = "upstream_header_time" ) // init 注册所有内置变量 diff --git a/internal/variable/ssl.go b/internal/variable/ssl.go index 03bec03..54f5b39 100644 --- a/internal/variable/ssl.go +++ b/internal/variable/ssl.go @@ -23,21 +23,21 @@ import ( const ( // VarSSLClientVerify SSL 客户端证书验证结果变量。 VarSSLClientVerify = "ssl_client_verify" -// VarSSLClientSerial SSL 客户端证书序列号变量。 + // VarSSLClientSerial SSL 客户端证书序列号变量。 VarSSLClientSerial = "ssl_client_serial" -// VarSSLClientSubject SSL 客户端证书主题变量。 + // VarSSLClientSubject SSL 客户端证书主题变量。 VarSSLClientSubject = "ssl_client_subject" -// VarSSLClientIssuer SSL 客户端证书颁发者变量。 + // VarSSLClientIssuer SSL 客户端证书颁发者变量。 VarSSLClientIssuer = "ssl_client_issuer" -// VarSSLClientFingerprint SSL 客户端证书指纹变量。 + // VarSSLClientFingerprint SSL 客户端证书指纹变量。 VarSSLClientFingerprint = "ssl_client_fingerprint" -// VarSSLClientNotBefore SSL 客户端证书生效时间变量。 + // VarSSLClientNotBefore SSL 客户端证书生效时间变量。 VarSSLClientNotBefore = "ssl_client_notbefore" -// VarSSLClientNotAfter SSL 客户端证书过期时间变量。 + // VarSSLClientNotAfter SSL 客户端证书过期时间变量。 VarSSLClientNotAfter = "ssl_client_notafter" -// VarSSLClientDNS SSL 客户端证书主题 DN 变量。 + // VarSSLClientDNS SSL 客户端证书主题 DN 变量。 VarSSLClientDNS = "ssl_client_s_dn" -// VarSSLClientEmail SSL 客户端证书邮箱变量。 + // VarSSLClientEmail SSL 客户端证书邮箱变量。 VarSSLClientEmail = "ssl_client_email" sslProtocolNone = "NONE" From a6152d4dc1c6e944547a649971e159dd5718d3e2 Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH 12/12] docs: add documentation comments for method implementations and test utilities - Add GoDoc for Warning.String, ParseError.Error - Add GoDoc for ngxReqAPILayer.String, Phase.String, SocketState.String - Add GoDoc for ConflictError.Error - Add GoDoc for noopResolver methods (LookupHost, LookupHostWithCache, Refresh, Start, Stop, Stats) - Add GoDoc for load balancer Select methods (roundRobin, weightedRoundRobin, ipHash) - Add GoDoc for WithWSHeaders test utility - Include author attribution (xfy) --- internal/converter/nginx/converter.go | 1 + internal/converter/nginx/parser.go | 1 + internal/e2e/testutil/websocket.go | 1 + internal/lua/api_req.go | 1 + internal/lua/coroutine.go | 1 + internal/matcher/location.go | 1 + internal/resolver/resolver.go | 8 ++++++++ internal/stream/stream.go | 13 +++++++++++++ 8 files changed, 27 insertions(+) diff --git a/internal/converter/nginx/converter.go b/internal/converter/nginx/converter.go index b827ccd..1f46660 100644 --- a/internal/converter/nginx/converter.go +++ b/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) } diff --git a/internal/converter/nginx/parser.go b/internal/converter/nginx/parser.go index 28b02f9..b2f6590 100644 --- a/internal/converter/nginx/parser.go +++ b/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) } diff --git a/internal/e2e/testutil/websocket.go b/internal/e2e/testutil/websocket.go index 3492ac1..a42c04c 100644 --- a/internal/e2e/testutil/websocket.go +++ b/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 diff --git a/internal/lua/api_req.go b/internal/lua/api_req.go index 66026ce..85b205a 100644 --- a/internal/lua/api_req.go +++ b/internal/lua/api_req.go @@ -55,6 +55,7 @@ const ( layerStringUnknown = "unknown" ) +// String 返回 API 层级的字符串表示。 func (l ngxReqAPILayer) String() string { switch l { case APILayerDirect: diff --git a/internal/lua/coroutine.go b/internal/lua/coroutine.go index 393bdb3..181b4cf 100644 --- a/internal/lua/coroutine.go +++ b/internal/lua/coroutine.go @@ -47,6 +47,7 @@ const ( PhaseBodyFilter ) +// String 返回处理阶段的字符串表示。 func (p Phase) String() string { switch p { case PhaseInit: diff --git a/internal/matcher/location.go b/internal/matcher/location.go index 1df4521..2650efa 100644 --- a/internal/matcher/location.go +++ b/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) diff --git a/internal/resolver/resolver.go b/internal/resolver/resolver.go index e150b90..8f11873 100644 --- a/internal/resolver/resolver.go +++ b/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{} } diff --git a/internal/stream/stream.go b/internal/stream/stream.go index 2a91a39..c7503d5 100644 --- a/internal/stream/stream.go +++ b/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