From a6152d4dc1c6e944547a649971e159dd5718d3e2 Mon Sep 17 00:00:00 2001 From: xfy911 Date: Wed, 3 Jun 2026 15:28:53 +0800 Subject: [PATCH] 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