From 2122067efb1a2ffeb3f8f9f0c4f0e6a61b078c11 Mon Sep 17 00:00:00 2001 From: xfy Date: Fri, 24 Apr 2026 18:24:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20AGENTS.md=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E6=B7=BB=E5=8A=A0=E6=96=B0=E6=A8=A1?= =?UTF-8?q?=E5=9D=97=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 更新所有 AGENTS.md 时间戳至 2026-04-24 - 添加 converter、e2e、testutil 模块文档 - 更新 README.md：nginx 配置导入、stale 缓存功能说明 - 更新项目统计：132 Go 文件，157 测试文件 Co-Authored-By: Claude Opus 4.7 --- AGENTS.md | 2 +- README.md | 32 +++++++++++-- internal/AGENTS.md | 16 ++++--- internal/app/AGENTS.md | 7 ++- internal/converter/AGENTS.md | 35 +++++++++++++++ internal/converter/nginx/AGENTS.md | 70 +++++++++++++++++++++++++++++ internal/e2e/AGENTS.md | 72 ++++++++++++++++++++++++++++++ internal/e2e/testutil/AGENTS.md | 60 +++++++++++++++++++++++++ internal/http2/AGENTS.md | 3 +- internal/lua/AGENTS.md | 4 +- 10 files changed, 287 insertions(+), 14 deletions(-) create mode 100644 internal/converter/AGENTS.md create mode 100644 internal/converter/nginx/AGENTS.md create mode 100644 internal/e2e/AGENTS.md create mode 100644 internal/e2e/testutil/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index d95c9f0..9fb5fe0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ - + # lolly diff --git a/README.md b/README.md index 29a3981..82f4859 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ ### 核心功能 -- **静态文件服务** - 零拷贝传输（sendfile）、文件缓存、预压缩支持、try_files 配置、符号链接安全检查 +- **静态文件服务** - 零拷贝传输（sendfile）、文件缓存、预压缩支持、try_files 配置、符号链接安全检查、ETag 和 304 Not Modified 支持 - **反向代理** - 完整的代理功能，支持请求头/响应头修改、超时控制、故障转移（next_upstream）、Location/Refresh 头改写 - **HTTP/3 (QUIC)** - 基于 quic-go，支持 0-RTT 连接 - **WebSocket** - 完整的 WebSocket 代理支持 @@ -24,6 +24,7 @@ - **Lua 脚本** - 基于 gopher-lua 的可编程扩展，支持 nginx-lua 兼容 API（ngx.var/ngx.ctx/ngx.req/ngx.resp/ngx.timer/ngx.location.capture/ngx.shared.DICT） - **GeoIP 过滤** - 基于 MaxMind GeoIP2 的国家/地区访问控制 - **自定义错误页面** - 支持为特定状态码配置自定义错误页面 +- **nginx 配置导入** - 支持将 nginx 配置文件转换为 lolly YAML 配置 ### 负载均衡 @@ -116,10 +117,33 @@ make build-all # 生成默认配置 ./bin/lolly --generate-config -o lolly.yaml +# 导入 nginx 配置 +./bin/lolly --import /etc/nginx/nginx.conf -o lolly.yaml +./bin/lolly -i nginx.conf # 简写形式 + # 显示版本 ./bin/lolly -v ``` +### nginx 配置导入 + +lolly 支持将 nginx 配置文件转换为 YAML 格式： + +```bash +# 导入 nginx 配置并输出到文件 +./bin/lolly --import nginx.conf -o lolly.yaml + +# 导入后会显示转换警告（不支持的指令） +``` + +支持的 nginx 指令： +- `server` 块：listen、server_name、ssl_certificate、ssl_certificate_key +- `location` 块：proxy_pass、root、alias、index、try_files +- `upstream` 块：server（含 weight、max_fails、fail_timeout、backup、down）、least_conn、ip_hash、hash、random +- 其他：gzip、gzip_types、gzip_min_length、client_max_body_size、access_log、error_log、rewrite、return（301/302）、error_page、auth_basic + +不支持的指令会在转换时显示警告，需要手动处理。 + ## 配置 配置文件使用 YAML 格式。以下是完整配置示例： @@ -441,6 +465,8 @@ type Balancer interface { - **缓存锁**（cache_lock）- 防止缓存击穿，同一缓存键只允许一个请求访问后端 - **过期复用**（stale-while-revalidate）- 允许在后台刷新时返回过期缓存 - **后台刷新** - 异步更新缓存，不影响请求响应时间 +- **错误回退**（stale-if-error）- 后端错误时返回过期缓存 +- **超时回退**（stale-if-timeout）- 后端超时时返回过期缓存 ## Lua 脚本 @@ -968,8 +994,8 @@ make lint ### 项目统计 -- Go 文件：110 -- 测试文件：113 +- Go 文件：132 +- 测试文件：157 - 核心模块均有完整测试和性能基准测试 - 中文代码注释 diff --git a/internal/AGENTS.md b/internal/AGENTS.md index 0a00f53..13f8b9e 100644 --- a/internal/AGENTS.md +++ b/internal/AGENTS.md @@ -1,5 +1,5 @@ - + # internal @@ -10,26 +10,30 @@ | Directory | Purpose | |-----------|---------| -| `app/` | 应用程序入口和运行逻辑（启动、信号处理、版本信息） | +| `app/` | 应用程序入口和运行逻辑（启动、信号处理、版本信息、nginx 配置导入） | | `benchmark/` | 基准测试基础设施（Mock 后端、负载生成器、回归检测） | -| `cache/` | 文件缓存模块（缓存存储、过期管理） | +| `cache/` | 文件缓存模块（缓存存储、过期管理、stale 回退） | | `config/` | 配置解析、验证和默认值生成 | -| `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile） | +| `converter/` | 配置转换器（nginx 配置导入） | +| `e2e/` | 端到端测试（完整功能验证、容器化测试） | +| `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile、ETag） | | `http2/` | HTTP/2 协议支持（ALPN 协商、fasthttp 适配） | | `http3/` | HTTP/3 (QUIC) 协议支持（fasthttp 适配、0-RTT） | | `integration/` | 集成测试（多模块端到端协作验证） | | `loadbalance/` | 负载均衡策略（轮询、最少连接、健康检查） | | `logging/` | 日志系统（zerolog 初始化、访问日志） | | `lua/` | Lua 脚本引擎（OpenResty 风格沙箱、ngx API） | +| `matcher/` | 路径匹配器（精确、前缀、正则匹配） | | `middleware/` | 中间件框架（接口定义、链式组合） | | `mimeutil/` | MIME 类型检测（扩展名映射、类型推断） | | `netutil/` | 网络工具函数（客户端 IP 提取、URL 解析） | -| `proxy/` | 反向代理模块（HTTP/WebSocket 代理） | +| `proxy/` | 反向代理模块（HTTP/WebSocket 代理、DNS 解析） | | `resolver/` | DNS 解析器（缓存、后台刷新、域名动态解析） | | `server/` | HTTP 服务器核心、虚拟主机、热升级、状态监控 | -| `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling） | +| `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling、Session Tickets） | | `sslutil/` | SSL 工具函数（证书池加载、CA 信任链） | | `stream/` | TCP/UDP Stream 代理模块 | +| `testutil/` | 测试工具函数（Mock、断言助手） | | `utils/` | HTTP 错误处理（统一错误响应助手） | | `variable/` | 变量系统（nginx 风格变量展开、日志格式模板） | diff --git a/internal/app/AGENTS.md b/internal/app/AGENTS.md index 4cc0471..2b5da1c 100644 --- a/internal/app/AGENTS.md +++ b/internal/app/AGENTS.md @@ -1,16 +1,17 @@ - + # app ## Purpose -应用程序入口包，提供启动逻辑、信号处理、版本信息显示和配置生成功能。 +应用程序入口包，提供启动逻辑、信号处理、版本信息显示、配置生成和 nginx 配置导入功能。 ## Key Files | File | Description | |------|-------------| | `app.go` | 核心逻辑：Run 入口、startServer、printVersion、generateConfig | +| `import.go` | nginx 配置导入：ImportNginxConfig、转换警告处理 | | `app_test.go` | 单元测试：版本显示、配置生成、服务器启动测试 | ## For AI Agents @@ -20,6 +21,7 @@ - `Run()` 是程序入口函数，返回退出码 - 信号处理：SIGTERM/SIGINT 快速停止，SIGQUIT 优雅停止（等待 30s） - `generateConfig()` 生成默认 YAML 配置，调用 `config.DefaultConfig()` +- `ImportNginxConfig()` 将 nginx 配置转换为 lolly YAML 格式 ### Testing Requirements - 测试文件 `app_test.go` 包含启动逻辑测试 @@ -36,5 +38,6 @@ ### Internal - `../config/` - 配置加载和验证 - `../server/` - HTTP 服务器创建和启动 +- `../converter/nginx/` - nginx 配置转换器 \ No newline at end of file diff --git a/internal/converter/AGENTS.md b/internal/converter/AGENTS.md new file mode 100644 index 0000000..e86a040 --- /dev/null +++ b/internal/converter/AGENTS.md @@ -0,0 +1,35 @@ + + + +# converter + +## Purpose +配置转换器模块，提供外部配置格式到 lolly YAML 配置的转换能力。 + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `nginx/` | nginx 配置转换器（nginx.conf → lolly.yaml） | + +## For AI Agents + +### Working In This Directory +- 转换器将外部配置格式解析为 `config.Config` 结构体 +- 转换过程中可能产生警告（不支持的指令），需要收集并展示给用户 +- 每种外部格式有独立的子包实现 + +### Testing Requirements +- 运行测试：`go test ./internal/converter/...` +- 测试应覆盖各种配置场景和边界情况 + +### Common Patterns +- 转换器返回 `(*config.Config, []Warning, error)` 三元组 +- 警告信息包含文件名、行号和描述 + +## Dependencies + +### Internal +- `../config/` - 配置结构体定义 + + diff --git a/internal/converter/nginx/AGENTS.md b/internal/converter/nginx/AGENTS.md new file mode 100644 index 0000000..e5f12ec --- /dev/null +++ b/internal/converter/nginx/AGENTS.md @@ -0,0 +1,70 @@ + + + +# nginx + +## Purpose +nginx 配置转换器，将 nginx.conf 格式转换为 lolly YAML 配置。支持 server、location、upstream、proxy_pass 等核心指令。 + +## Key Files + +| File | Description | +|------|-------------| +| `parser.go` | nginx 配置解析器：词法分析、语法树构建 | +| `converter.go` | 配置转换器：nginx AST → lolly Config | +| `parser_test.go` | 解析器测试：各种 nginx 配置格式 | +| `converter_test.go` | 转换器测试：指令映射、警告生成 | + +## For AI Agents + +### Working In This Directory +- 解析器将 nginx 配置文本解析为 `NginxConfig` AST +- 转换器遍历 AST 生成 `config.Config` 结构体 +- 不支持的指令会生成 `Warning` 而非错误，允许部分转换 +- location 匹配类型映射：`=` → `exact`，`^~` → `prefix_priority`，`~` → `regex`，`~*` → `regex_caseless` + +### Testing Requirements +- 运行测试：`go test ./internal/converter/nginx/...` +- 测试覆盖：完整配置、部分配置、错误处理 + +### Common Patterns +```go +// 解析 nginx 配置 +parser := nginx.NewParser(content) +cfg, err := parser.Parse() + +// 转换为 lolly 配置 +result, err := nginx.Convert(cfg) +// result.Config - 转换后的配置 +// result.Warnings - 转换警告 +``` + +### 支持的 nginx 指令 + +| 指令 | 转换说明 | +|------|----------| +| `server` | 转换为 `ServerConfig` | +| `listen` | 转换为 `listen` 字段 | +| `server_name` | 转换为 `name`/`server_names` | +| `location` | 转换为 `ProxyConfig` 或 `StaticConfig` | +| `proxy_pass` | 转换为代理目标 | +| `root`/`alias` | 转换为静态文件根目录 | +| `upstream` | 转换为负载均衡目标列表 | +| `gzip` | 转换为压缩配置 | +| `ssl_certificate` | 转换为 SSL 证书配置 | +| `rewrite` | 转换为 URL 重写规则 | +| `return 301/302` | 转换为重定向规则 | + +### 不支持的指令（生成警告） + +- `if`、`map`、`set` - 条件逻辑不支持 +- `limit_req`、`limit_conn` - 使用 `rate_limit` 配置替代 +- `add_header` - 使用 `security.headers` 配置替代 +- `auth_request` - 使用 `security.auth_request` 配置替代 + +## Dependencies + +### Internal +- `../../config/` - 配置结构体定义 + + diff --git a/internal/e2e/AGENTS.md b/internal/e2e/AGENTS.md new file mode 100644 index 0000000..f469700 --- /dev/null +++ b/internal/e2e/AGENTS.md @@ -0,0 +1,72 @@ + + + +# e2e + +## Purpose +端到端测试模块，验证完整功能的集成测试。使用 testcontainers 启动真实后端服务进行测试。 + +## Key Files + +| File | Description | +|------|-------------| +| `e2e_test.go` | 测试入口和通用测试辅助函数 | +| `cache_e2e_test.go` | 代理缓存端到端测试 | +| `healthcheck_e2e_test.go` | 健康检查端到端测试 | +| `http2_e2e_test.go` | HTTP/2 端到端测试 | +| `loadbalance_e2e_test.go` | 负载均衡端到端测试 | +| `proxy_e2e_test.go` | 反向代理端到端测试 | +| `ssl_e2e_test.go` | SSL/TLS 端到端测试 | +| `static_e2e_test.go` | 静态文件服务端到端测试 | +| `websocket_e2e_test.go` | WebSocket 代理端到端测试 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `testutil/` | 测试工具函数（容器、配置、证书） | +| `certs/` | 测试用 TLS 证书 | +| `configs/` | 测试用配置文件 | + +## For AI Agents + +### Working In This Directory +- 端到端测试需要 Docker 环境运行 testcontainers +- 测试启动真实 lolly 服务器和 mock 后端 +- 使用 `testutil` 包提供的辅助函数创建测试环境 +- 测试名称遵循 `TestE2E_<功能>_<场景>` 格式 + +### Testing Requirements +- 运行测试：`go test ./internal/e2e/... -tags=e2e` +- 需要 Docker 运行 +- 测试可能需要较长时间（启动容器） + +### Common Patterns +```go +// 创建测试环境 +env := testutil.NewTestEnv(t) +defer env.Cleanup() + +// 启动 lolly 服务器 +env.StartServer(config) +defer env.StopServer() + +// 启动 mock 后端 +backend := env.StartMockBackend() +defer backend.Close() + +// 发送测试请求 +resp := env.Request("GET", "/api/test", nil) +``` + +## Dependencies + +### Internal +- `./testutil/` - 测试工具函数 +- `../server/` - HTTP 服务器 +- `../config/` - 配置加载 + +### External +- `github.com/testcontainers/testcontainers-go` - 容器化测试 + + diff --git a/internal/e2e/testutil/AGENTS.md b/internal/e2e/testutil/AGENTS.md new file mode 100644 index 0000000..de3fe0c --- /dev/null +++ b/internal/e2e/testutil/AGENTS.md @@ -0,0 +1,60 @@ + + + +# testutil + +## Purpose +端到端测试工具包，提供测试环境搭建、容器管理、证书生成、配置辅助等功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `setup.go` | 测试环境初始化：NewTestEnv、Cleanup | +| `config.go` | 配置辅助：创建测试配置、临时文件 | +| `constants.go` | 测试常量：默认端口、超时时间 | +| `container.go` | 容器管理：启动 mock 后端、清理容器 | +| `container_test.go` | 容器管理测试 | +| `certs.go` | 证书生成：自签名证书、CA 证书 | +| `ssl.go` | SSL 辅助：TLS 配置、证书验证 | +| `websocket.go` | WebSocket 辅助：WS 客户端、消息收发 | +| `concurrent.go` | 并发测试辅助：并发请求、结果收集 | + +## For AI Agents + +### Working In This Directory +- `NewTestEnv(t)` 创建测试环境，返回清理函数 +- 测试环境自动管理临时文件和端口分配 +- 容器化测试需要 Docker 运行 +- 证书生成用于 TLS 测试 + +### Testing Requirements +- 运行测试：`go test ./internal/e2e/testutil/...` +- 部分测试需要 Docker + +### Common Patterns +```go +// 创建测试环境 +env := testutil.NewTestEnv(t) +defer env.Cleanup() + +// 创建临时配置文件 +cfgPath := env.CreateConfig(serverConfig) + +// 启动容器化后端 +container := env.StartContainer(containerConfig) +defer container.Terminate() + +// 生成测试证书 +cert, key := env.GenerateCertificate() +``` + +## Dependencies + +### Internal +- `../../config/` - 配置结构体 + +### External +- `github.com/testcontainers/testcontainers-go` - 容器管理 + + diff --git a/internal/http2/AGENTS.md b/internal/http2/AGENTS.md index bc2e5e2..db6dda8 100644 --- a/internal/http2/AGENTS.md +++ b/internal/http2/AGENTS.md @@ -1,5 +1,5 @@ - + # http2 @@ -15,6 +15,7 @@ HTTP/2 协议支持模块，基于 golang.org/x/net/http2 实现，提供 ALPN | `server_test.go` | 服务器测试：创建、启动、关闭测试 | | `adapter_test.go` | 适配器测试：头部转换、请求体处理测试 | | `integration_test.go` | 集成测试：端到端 HTTP/2 请求处理 | +| `integration_tls_test.go` | TLS 集成测试：HTTPS 连接测试 | ## For AI Agents diff --git a/internal/lua/AGENTS.md b/internal/lua/AGENTS.md index 246608c..37216ca 100644 --- a/internal/lua/AGENTS.md +++ b/internal/lua/AGENTS.md @@ -1,5 +1,5 @@ - + # lua @@ -22,6 +22,8 @@ Lua 脚本嵌入引擎，提供类似 OpenResty 的 Lua 沙箱环境，支持请 | `cache.go` | 字节码缓存：预编译脚本缓存 | | `register.go` | API 注册：ngx 表初始化 | | `filter_writer.go` | 响应过滤器：body_filter_by_lua | +| `boundary_test.go` | 边界条件测试：错误处理、资源限制 | +| `scheduler_test.go` | 调度器测试：定时器、协程调度 | | `api_*.go` | ngx API 实现：req、resp、ctx、var、log、timer、socket、location、shared_dict | ## For AI Agents