From 392d0b3449e2ff6413907e99a2b05668681f5c0c Mon Sep 17 00:00:00 2001 From: xfy Date: Thu, 9 Apr 2026 13:35:29 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=E6=A8=A1=E5=9D=97=20?= =?UTF-8?q?AGENTS.md=20=E6=96=87=E6=A1=A3=EF=BC=8C=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E7=9B=AE=E5=BD=95=E7=B4=A2=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 http2、integration、resolver、variable 模块 AGENTS.md - 更新 internal/AGENTS.md 目录表，补充新模块条目 - 更新 docs/prompts.md 添加 generate-config 缺失项分析提示 - 同步更新日期戳至 2026-04-09 Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 2 +- docs/prompts.md | 4 ++- internal/AGENTS.md | 6 ++++- internal/http2/AGENTS.md | 49 ++++++++++++++++++++++++++++++++++ internal/integration/AGENTS.md | 43 +++++++++++++++++++++++++++++ internal/resolver/AGENTS.md | 47 ++++++++++++++++++++++++++++++++ internal/variable/AGENTS.md | 48 +++++++++++++++++++++++++++++++++ 7 files changed, 196 insertions(+), 3 deletions(-) create mode 100644 internal/http2/AGENTS.md create mode 100644 internal/integration/AGENTS.md create mode 100644 internal/resolver/AGENTS.md create mode 100644 internal/variable/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 0695e53..04c0b8a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ - + # lolly diff --git a/docs/prompts.md b/docs/prompts.md index 564fcf8..111f526 100644 --- a/docs/prompts.md +++ b/docs/prompts.md @@ -7,7 +7,9 @@ ulw 深度分析下 @docs/ 下的 nginx 文档，看看当前项目实现的怎 ulw 深度分析 https://nginx.org/en/docs/ nginx 的功能，@docs/ 目录下已经有一些分析过的文档了，看看有没有能完善的 -ulw 深度分析下当前的 --generate-config，是否有配置文件描述了，但代码未实现的功能。同时也分析下有没有代码实现了，但是配置文件缺失的地方 +ulw 深度分析下当前的 --generate-config，是否有配置文件描述了，但代码未实现的功能。 + +ulw 深度分析下有没有代码实现了，但是 --generate-config 缺失的地方 ulw 逐行分析下当前的 --generate-config，看看代码中是否都实现了 diff --git a/internal/AGENTS.md b/internal/AGENTS.md index 9fc5f24..dac2b27 100644 --- a/internal/AGENTS.md +++ b/internal/AGENTS.md @@ -1,5 +1,5 @@ - + # internal @@ -15,15 +15,19 @@ | `cache/` | 文件缓存模块（缓存存储、过期管理） | | `config/` | 配置解析、验证和默认值生成 | | `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile） | +| `http2/` | HTTP/2 协议支持（ALPN 协商、fasthttp 适配） | | `http3/` | HTTP/3 (QUIC) 协议支持（fasthttp 适配、0-RTT） | +| `integration/` | 集成测试（多模块端到端协作验证） | | `loadbalance/` | 负载均衡策略（轮询、最少连接、健康检查） | | `logging/` | 日志系统（zerolog 初始化、访问日志） | | `middleware/` | 中间件框架（接口定义、链式组合） | | `netutil/` | 网络工具函数（客户端 IP 提取、URL 解析） | | `proxy/` | 反向代理模块（HTTP/WebSocket 代理） | +| `resolver/` | DNS 解析器（缓存、后台刷新、域名动态解析） | | `server/` | HTTP 服务器核心、虚拟主机、热升级、状态监控 | | `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling） | | `stream/` | TCP/UDP Stream 代理模块 | +| `variable/` | 变量系统（nginx 风格变量展开、日志格式模板） | ## For AI Agents diff --git a/internal/http2/AGENTS.md b/internal/http2/AGENTS.md new file mode 100644 index 0000000..bc2e5e2 --- /dev/null +++ b/internal/http2/AGENTS.md @@ -0,0 +1,49 @@ + + + +# http2 + +## Purpose +HTTP/2 协议支持模块，基于 golang.org/x/net/http2 实现，提供 ALPN 协议协商、与 fasthttp handler 的集成、优雅关闭支持。 + +## Key Files + +| File | Description | +|------|-------------| +| `server.go` | HTTP/2 服务器核心：Server 结构、NewServer、Start、GracefulStop | +| `adapter.go` | fasthttp 适配层：FastHTTPHandlerAdapter、零拷贝头部转换、流式请求体处理 | +| `server_test.go` | 服务器测试：创建、启动、关闭测试 | +| `adapter_test.go` | 适配器测试：头部转换、请求体处理测试 | +| `integration_test.go` | 集成测试：端到端 HTTP/2 请求处理 | + +## For AI Agents + +### Working In This Directory +- HTTP/2 服务器使用标准库 http.Handler 接口 +- 通过适配层转换 fasthttp.RequestHandler → http.Handler +- 需要 TLS 配置进行 ALPN 协商（h2 协议标识） +- 使用 sync.Pool 复用缓冲区实现零拷贝优化 +- 预估每请求 5-10µs 适配开销 + +### Testing Requirements +- 运行测试：`go test ./internal/http2/...` +- 测试需要 TLS 配置（部分测试） +- 集成测试验证完整请求流程 + +### Common Patterns +- NewServer(cfg, handler, tlsConfig) 创建服务器 +- Start() 在现有 TCP 监听器上启动 +- GracefulStop() 优雅关闭等待请求完成 +- FastHTTPHandlerAdapter.ServeHTTP 实现标准库接口 + +## Dependencies + +### Internal +- `../config/` - HTTP2Config 配置结构体 +- `../logging/` - 日志模块 + +### External +- `golang.org/x/net/http2` - HTTP/2 协议实现 +- `github.com/valyala/fasthttp` - fasthttp handler 类型 + + \ No newline at end of file diff --git a/internal/integration/AGENTS.md b/internal/integration/AGENTS.md new file mode 100644 index 0000000..892d01e --- /dev/null +++ b/internal/integration/AGENTS.md @@ -0,0 +1,43 @@ + + + +# integration + +## Purpose +集成测试目录，测试多个模块之间的端到端协作，验证组件间的正确集成。 + +## Key Files + +| File | Description | +|------|-------------| +| `resolver_test.go` | DNS 解析器集成测试：基本解析、缓存功能、网络依赖测试 | +| `variable_test.go` | 变量系统集成测试：变量在日志、代理、重写中的端到端使用 | + +## For AI Agents + +### Working In This Directory +- 集成测试验证多模块协作，不同于单元测试 +- 测试依赖真实网络环境（DNS 解析测试） +- 测试可能因网络原因跳过（Skip） +- 变量系统测试覆盖 nginx 风格格式展开 + +### Testing Requirements +- 运行测试：`go test ./internal/integration/...` +- 网络测试可能需要外部环境支持 +- 测试验证端到端流程而非单个函数 + +### Common Patterns +- 使用真实配置结构体初始化测试 +- 模拟 fasthttp.RequestCtx 进行请求测试 +- Skip 处理网络不可用情况 + +## Dependencies + +### Internal +- `../resolver/` - DNS 解析器模块 +- `../variable/` - 变量系统模块 +- `../config/` - 配置模块 +- `../logging/` - 日志模块 +- `../middleware/rewrite/` - URL 重写中间件 + + \ No newline at end of file diff --git a/internal/resolver/AGENTS.md b/internal/resolver/AGENTS.md new file mode 100644 index 0000000..5beda3b --- /dev/null +++ b/internal/resolver/AGENTS.md @@ -0,0 +1,47 @@ + + + +# resolver + +## Purpose +DNS 解析器模块，提供带缓存的 DNS 解析功能，支持动态解析后端服务域名、TTL 缓存、后台刷新。 + +## Key Files + +| File | Description | +|------|-------------| +| `resolver.go` | DNS 解析器核心：Resolver 接口、DNSResolver 实现、LookupHost 方法 | +| `cache.go` | DNS 缓存管理：缓存条目结构、TTL 过期、缓存命中统计 | +| `stats.go` | 统计信息：ResolverStats 结构、缓存命中率、解析延迟追踪 | +| `resolver_test.go` | 单元测试：解析功能、缓存行为、错误处理测试 | + +## For AI Agents + +### Working In This Directory +- Resolver 接口定义：LookupHost、LookupHostWithCache、Refresh、Start、Stop +- 使用 sync.Map 实现并发安全缓存 +- 后台刷新需要调用 Start() 启动 +- 停止使用时应调用 Stop() 释放资源 +- 用于代理模块动态解析 upstream 域名 + +### Testing Requirements +- 运行测试：`go test ./internal/resolver/...` +- 测试覆盖缓存逻辑和错误处理 +- 集成测试在 `../integration/` 目录 + +### Common Patterns +- 接口设计支持多种解析器实现 +- 缓存条目包含 TTL 和过期时间 +- 统计信息使用 atomic 计数器 + +## Dependencies + +### Internal +- `../config/` - ResolverConfig 配置结构体 + +### External +- `net` - Go 标准库 DNS 解析 +- `sync` - 并发安全 +- `context` - 上下文超时控制 + + \ No newline at end of file diff --git a/internal/variable/AGENTS.md b/internal/variable/AGENTS.md new file mode 100644 index 0000000..6103c6f --- /dev/null +++ b/internal/variable/AGENTS.md @@ -0,0 +1,48 @@ + + + +# variable + +## Purpose +高性能变量系统，提供 nginx 风格的变量展开功能。用于访问日志格式模板、代理请求头设置、URL 重写规则。 + +## Key Files + +| File | Description | +|------|-------------| +| `variable.go` | 变量系统核心：VariableContext 结构、Expand 方法、变量存储接口 | +| `builtin.go` | 内置变量定义：$remote_addr、$request_uri、$status、$time_local 等nginx 风格变量 | +| `pool.go` | sync.Pool 复用：PoolGet、PoolPut、池统计信息 | +| `ssl.go` | SSL 相关变量：$ssl_protocol、$ssl_cipher、$ssl_client_sni 等 | +| `variable_test.go` | 单元测试：变量展开、内置变量获取、自定义变量 | +| `variable_bench_test.go` | 基准测试：展开性能、池性能 | + +## For AI Agents + +### Working In This Directory +- 支持两种变量格式：$var 和 ${var}（用于变量后有字符） +- 使用快速字符串扫描（非正则表达式）提升性能 +- sync.Pool 复用 VariableContext 减少 GC 压力 +- 内置变量惰性求值并缓存结果 +- 自定义变量通过 Set 方法设置 + +### Testing Requirements +- 运行测试：`go test ./internal/variable/...` +- 基准测试验证展开性能：`go test -bench=. ./internal/variable/...` +- 集成测试在 `../integration/` 目录 + +### Common Patterns +- VariableContext 绑定到单个请求 +- 从池获取：PoolGet(ctx)，放回：PoolPut(vc) +- 全局变量通过 SetGlobalVariables 设置 +- 上游变量：$upstream_addr、$upstream_status、$upstream_response_time + +## Dependencies + +### Internal +- 无内部依赖，底层模块 + +### External +- `github.com/valyala/fasthttp` - RequestCtx 类型 + + \ No newline at end of file