From 95030cd68a4fca5c4653959fe9dd4aa38c668a84 Mon Sep 17 00:00:00 2001 From: xfy Date: Fri, 3 Apr 2026 14:07:42 +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?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加各模块的 AGENTS.md 文档文件，记录模块职责和代码结构 Co-Authored-By: Claude --- AGENTS.md | 3 +- docs/AGENTS.md | 13 ++++++- docs/update-prompts.md | 2 + internal/AGENTS.md | 11 ++++-- internal/cache/AGENTS.md | 38 +++++++++++++++++++ internal/handler/AGENTS.md | 3 +- internal/loadbalance/AGENTS.md | 44 ++++++++++++++++++++++ internal/middleware/AGENTS.md | 13 ++++++- internal/middleware/accesslog/AGENTS.md | 43 +++++++++++++++++++++ internal/middleware/compression/AGENTS.md | 42 +++++++++++++++++++++ internal/middleware/rewrite/AGENTS.md | 39 +++++++++++++++++++ internal/middleware/security/AGENTS.md | 46 +++++++++++++++++++++++ internal/proxy/AGENTS.md | 45 ++++++++++++++++++++++ internal/server/AGENTS.md | 5 ++- internal/ssl/AGENTS.md | 44 ++++++++++++++++++++++ internal/stream/AGENTS.md | 39 +++++++++++++++++++ 16 files changed, 421 insertions(+), 9 deletions(-) create mode 100644 internal/cache/AGENTS.md create mode 100644 internal/loadbalance/AGENTS.md create mode 100644 internal/middleware/accesslog/AGENTS.md create mode 100644 internal/middleware/compression/AGENTS.md create mode 100644 internal/middleware/rewrite/AGENTS.md create mode 100644 internal/middleware/security/AGENTS.md create mode 100644 internal/proxy/AGENTS.md create mode 100644 internal/ssl/AGENTS.md create mode 100644 internal/stream/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 9444c27..63a76d3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ - + # lolly @@ -14,6 +14,7 @@ | `go.sum` | 依赖版本锁定 | | `Makefile` | 构建脚本，支持多平台编译、测试、覆盖率 | | `lolly.yaml` | 默认配置文件示例 | +| `config.example.yaml` | 完整配置文件示例（所有字段枚举） | | `.gitignore` | Git 忽略规则 | ## Subdirectories diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 16c80bd..0c6fc16 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -1,5 +1,5 @@ - + # docs @@ -32,6 +32,17 @@ | `10-nginx-stream-tcp-udp.md` | TCP/UDP Stream 代理参考 | | `11-nginx-mail-proxy.md` | 邮件代理参考 | | `12-nginx-performance-tuning.md` | 性能调优参考 | +| `14-nginx-grpc-uwsgi.md` | gRPC/uWSGI/SCGI 代理参考 | +| `15-nginx-advanced-features.md` | 高级特性参考 | +| `16-nginx-internal-redirect.md` | 内部重定向参考 | +| `17-nginx-mirror-slice.md` | 镜像与切片参考 | +| `18-nginx-memcached.md` | Memcached 集成参考 | +| `19-nginx-http-modules-detail.md` | HTTP 功能模块详解 | +| `20-nginx-rate-limiting.md` | 限流与连接控制参考 | +| `21-nginx-http2-http3.md` | HTTP/2 与 HTTP/3 参考 | +| `22-nginx-third-party-modules.md` | 第三方扩展模块参考 | +| `23-nginx-special-modules.md` | 特殊功能模块参考 | +| `24-nginx-core-events.md` | 核心与事件模块参考 | ## For AI Agents diff --git a/docs/update-prompts.md b/docs/update-prompts.md index 9ccf1c1..8e339a6 100644 --- a/docs/update-prompts.md +++ b/docs/update-prompts.md @@ -9,6 +9,8 @@ ## 单元测试 +/ultrawork 分析下当前测试覆盖率 + ## 注释 /ultrawork 参考 @docs/comments.md，分析项目注释是否完善 diff --git a/internal/AGENTS.md b/internal/AGENTS.md index a631380..a516f9d 100644 --- a/internal/AGENTS.md +++ b/internal/AGENTS.md @@ -1,5 +1,5 @@ - + # internal @@ -11,11 +11,16 @@ | Directory | Purpose | |-----------|---------| | `app/` | 应用程序入口和运行逻辑（启动、信号处理、版本信息） | +| `cache/` | 文件缓存模块（缓存存储、过期管理） | | `config/` | 配置解析、验证和默认值生成 | -| `handler/` | HTTP 请求处理器（路由、静态文件） | +| `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile） | +| `loadbalance/` | 负载均衡策略（轮询、最少连接、健康检查） | | `logging/` | 日志系统（zerolog 初始化、访问日志） | | `middleware/` | 中间件框架（接口定义、链式组合） | -| `server/` | HTTP 服务器核心和虚拟主机管理 | +| `proxy/` | 反向代理模块（HTTP/WebSocket 代理） | +| `server/` | HTTP 服务器核心、虚拟主机、热升级、状态监控 | +| `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling） | +| `stream/` | TCP/UDP Stream 代理模块 | ## For AI Agents diff --git a/internal/cache/AGENTS.md b/internal/cache/AGENTS.md new file mode 100644 index 0000000..c37a427 --- /dev/null +++ b/internal/cache/AGENTS.md @@ -0,0 +1,38 @@ + + + +# cache + +## Purpose +文件缓存模块，提供静态文件的内存缓存和过期管理功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `file_cache.go` | 文件缓存核心：FileCache 结构体、Get/Set/Delete、TTL 管理、LRU 淘汰 | +| `cache_test.go` | 缓存单元测试 | + +## For AI Agents + +### Working In This Directory +- 缓存项包含文件内容、MIME 类型、最后修改时间 +- TTL 默认 5 分钟，可配置 +- LRU 淘汰策略，最大缓存大小可配置 +- 支持缓存失效和手动清除 + +### Testing Requirements +- 运行测试：`go test ./internal/cache/...` +- 测试缓存存取、过期淘汰、并发安全 + +### Common Patterns +- 使用 `sync.RWMutex` 保证并发安全 +- 缓存键为文件路径的哈希值 +- 缓存命中时直接返回内容，避免磁盘 I/O + +## Dependencies + +### Internal +- `../config/` - 缓存配置参数 + + \ No newline at end of file diff --git a/internal/handler/AGENTS.md b/internal/handler/AGENTS.md index 9ec9f18..3ab6ddc 100644 --- a/internal/handler/AGENTS.md +++ b/internal/handler/AGENTS.md @@ -1,5 +1,5 @@ - + # handler @@ -12,6 +12,7 @@ HTTP 请求处理器，包含路由管理和静态文件服务功能。 |------|-------------| | `router.go` | 路由器封装：基于 fasthttp/router，支持 GET/POST/PUT/DELETE/HEAD | | `static.go` | 静态文件处理器：文件路径安全检查、索引文件支持 | +| `sendfile.go` | Sendfile 支持：X-Sendfile 头处理、高效文件传输 | ## For AI Agents diff --git a/internal/loadbalance/AGENTS.md b/internal/loadbalance/AGENTS.md new file mode 100644 index 0000000..bfb3496 --- /dev/null +++ b/internal/loadbalance/AGENTS.md @@ -0,0 +1,44 @@ + + + +# loadbalance + +## Purpose +负载均衡模块，提供多种负载均衡策略和健康检查功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `balancer.go` | 负载均衡核心：Balancer 接口、Upstream、Target 管理 | +| `algorithms.go` | 负载均衡算法：RoundRobin、LeastConn、Weighted | +| `health.go` | 健康检查：HealthChecker、被动/主动检查 | +| `balancer_test.go` | 负载均衡测试 | +| `health_test.go` | 健康检查测试 | + +## For AI Agents + +### Working In This Directory +- `Balancer` 接口定义：Select()、AddTarget()、RemoveTarget() +- 支持 RoundRobin（轮询）、LeastConn（最少连接）、Weighted（加权） +- 健康检查支持被动（请求失败计数）和主动（定期探测） +- 不健康 Target 自动剔除，恢复后自动加入 + +### Testing Requirements +- 运行测试：`go test ./internal/loadbalance/...` +- 测试各算法的正确性、健康检查逻辑 + +### Common Patterns +- Target 权重默认为 1 +- 健康检查间隔默认 10 秒 +- 不健康阈值：连续 3 次失败 + +## Dependencies + +### Internal +- `../config/` - 负载均衡配置 + +### External +- `github.com/valyala/fasthttp` - HTTP 客户端用于健康探测 + + \ No newline at end of file diff --git a/internal/middleware/AGENTS.md b/internal/middleware/AGENTS.md index 71d31ae..e9ec788 100644 --- a/internal/middleware/AGENTS.md +++ b/internal/middleware/AGENTS.md @@ -1,10 +1,10 @@ - + # middleware ## Purpose -中间件框架，定义统一的中间件接口和链式组合机制。 +中间件框架，定义统一的中间件接口和链式组合机制，包含多个具体中间件实现。 ## Key Files @@ -12,6 +12,15 @@ |------|-------------| | `middleware.go` | 中间件接口和链：Middleware 接口、Chain 结构体、Apply 方法 | +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `accesslog/` | 访问日志中间件（请求记录、响应统计） | +| `compression/` | 响应压缩中间件（Gzip、Deflate） | +| `rewrite/` | URL 重写中间件（正则替换、路径转换） | +| `security/` | 安全中间件（访问控制、认证、限流、安全头部） | + ## For AI Agents ### Working In This Directory diff --git a/internal/middleware/accesslog/AGENTS.md b/internal/middleware/accesslog/AGENTS.md new file mode 100644 index 0000000..82ce2ca --- /dev/null +++ b/internal/middleware/accesslog/AGENTS.md @@ -0,0 +1,43 @@ + + + +# accesslog + +## Purpose +访问日志中间件，记录每个请求的详细信息，包括方法、路径、状态码、响应时间和客户端地址。 + +## Key Files + +| File | Description | +|------|-------------| +| `accesslog.go` | 访问日志中间件：AccessLog 结构体、Process() 方法、日志格式化 | +| `accesslog_test.go` | 访问日志测试 | + +## For AI Agents + +### Working In This Directory +- 记录请求信息：method、path、status、size、duration、remote_addr +- 支持自定义日志格式 +- 响应时间单位为毫秒 +- 日志级别为 info + +### Testing Requirements +- 运行测试：`go test ./internal/middleware/accesslog/...` +- 测试日志格式化、字段提取 + +### Common Patterns +- 使用 zerolog 的链式 API +- duration 通过 ctx.Time() 获取 +- 可配置排除路径（如健康检查） + +## Dependencies + +### Internal +- `../` - 中间件接口定义 +- `../../logging/` - 日志实例 + +### External +- `github.com/rs/zerolog` - 日志库 +- `github.com/valyala/fasthttp` - HTTP 框架 + + \ No newline at end of file diff --git a/internal/middleware/compression/AGENTS.md b/internal/middleware/compression/AGENTS.md new file mode 100644 index 0000000..4d074a5 --- /dev/null +++ b/internal/middleware/compression/AGENTS.md @@ -0,0 +1,42 @@ + + + +# compression + +## Purpose +响应压缩中间件，支持 Gzip 和 Deflate 压缩，自动根据 Accept-Encoding 头选择压缩方式。 + +## Key Files + +| File | Description | +|------|-------------| +| `compression.go` | 压缩中间件：Compression 结构体、Process() 方法、压缩级别配置 | +| `compression_test.go` | 压缩测试 | + +## For AI Agents + +### Working In This Directory +- 支持 Gzip 和 Deflate 压缩 +- 自动检测 Accept-Encoding 头选择压缩方式 +- 压缩级别可配置（1-9，默认 6） +- 小于 1KB 的响应不压缩 + +### Testing Requirements +- 运行测试：`go test ./internal/middleware/compression/...` +- 测试压缩检测、响应处理、级别配置 + +### Common Patterns +- 使用 fasthttp 的内置压缩支持 +- Content-Type 过滤：仅压缩 text/* 和 application/json +- Vary: Accept-Encoding 头自动添加 + +## Dependencies + +### Internal +- `../` - 中间件接口定义 +- `../../config/` - 压缩配置 + +### External +- `github.com/valyala/fasthttp` - HTTP 框架（内置压缩） + + \ No newline at end of file diff --git a/internal/middleware/rewrite/AGENTS.md b/internal/middleware/rewrite/AGENTS.md new file mode 100644 index 0000000..7987cbd --- /dev/null +++ b/internal/middleware/rewrite/AGENTS.md @@ -0,0 +1,39 @@ + + + +# rewrite + +## Purpose +URL 重写中间件，支持正则表达式匹配和替换，实现 URL 路径转换。 + +## Key Files + +| File | Description | +|------|-------------| +| `rewrite.go` | 重写中间件：Rewrite 结构体、Rule 定义、正则匹配替换 | +| `rewrite_test.go` | 重写测试 | + +## For AI Agents + +### Working In This Directory +- 使用正则表达式匹配 URL 路径 +- 支持捕获组替换（$1、$2 等） +- 重写后继续处理，不终止请求 +- 可配置多条规则，按顺序匹配 + +### Testing Requirements +- 运行测试：`go test ./internal/middleware/rewrite/...` +- 测试正则匹配、捕获组替换、多规则处理 + +### Common Patterns +- 规则格式：Pattern（正则）→ Replacement（替换字符串） +- 重写后更新 ctx.Path()，不影响路由匹配 +- 匹配失败时跳过该规则 + +## Dependencies + +### Internal +- `../` - 中间件接口定义 +- `../../config/` - 重写规则配置 + + \ No newline at end of file diff --git a/internal/middleware/security/AGENTS.md b/internal/middleware/security/AGENTS.md new file mode 100644 index 0000000..7c28a0c --- /dev/null +++ b/internal/middleware/security/AGENTS.md @@ -0,0 +1,46 @@ + + + +# security + +## Purpose +安全中间件集合，提供访问控制、认证、限流和安全头部功能，保护服务器免受常见攻击。 + +## Key Files + +| File | Description | +|------|-------------| +| `access.go` | 访问控制：IP 白名单/黑名单、地理位置限制、allow/deny 规则 | +| `auth.go` | 认证中间件：Basic Auth、Bearer Token、JWT 验证 | +| `ratelimit.go` | 限流中间件：请求限流、连接限流、令牌桶算法 | +| `headers.go` | 安全头部：X-Frame-Options、X-Content-Type-Options、CSP、HSTS | +| `*_test.go` | 各模块单元测试 | + +## For AI Agents + +### Working In This Directory +- 访问控制支持 CIDR 格式 IP 范围 +- Basic Auth 使用 bcrypt 密码哈希 +- 限流使用令牌桶算法，支持按 IP/全局限流 +- 安全头部可配置启用/禁用 + +### Testing Requirements +- 运行测试：`go test ./internal/middleware/security/...` +- 测试 IP 匹配、密码验证、限流逻辑、头部设置 + +### Common Patterns +- 访问控制按顺序匹配：先检查黑名单，再检查白名单 +- 限流阈值：请求速率（req/s）、并发连接数 +- 认证失败返回 401，限流触发返回 429 + +## Dependencies + +### Internal +- `../` - 中间件接口定义 +- `../../config/` - 安全配置 + +### External +- `golang.org/x/crypto/bcrypt` - 密码哈希 +- `github.com/valyala/fasthttp` - HTTP 框架 + + \ No newline at end of file diff --git a/internal/proxy/AGENTS.md b/internal/proxy/AGENTS.md new file mode 100644 index 0000000..19b9ae0 --- /dev/null +++ b/internal/proxy/AGENTS.md @@ -0,0 +1,45 @@ + + + +# proxy + +## Purpose +反向代理模块，提供 HTTP 和 WebSocket 代理功能，支持连接池和超时控制。 + +## Key Files + +| File | Description | +|------|-------------| +| `proxy.go` | HTTP 反向代理核心：Proxy 结构体、Forward()、请求/响应处理 | +| `websocket.go` | WebSocket 代理：握手升级、双向数据转发、连接管理 | +| `health.go` | 健康检查集成：与 loadbalance 模块协作 | +| `proxy_test.go` | HTTP 代理测试 | +| `health_test.go` | 健康检查测试 | + +## For AI Agents + +### Working In This Directory +- HTTP 代理使用 fasthttp 的 HostClient 进行转发 +- WebSocket 代理支持双向数据流，处理 Upgrade 请求 +- 连接池配置：MaxConns、MaxIdleConnDuration +- 超时配置：ReadTimeout、WriteTimeout、IdleTimeout + +### Testing Requirements +- 运行测试：`go test ./internal/proxy/...` +- 测试请求转发、WebSocket 升级、超时处理 + +### Common Patterns +- 代理请求时复制原始头部，添加 X-Forwarded-For +- WebSocket 使用 goroutine 双向转发 +- 错误响应返回 502（Bad Gateway）或 504（Gateway Timeout） + +## Dependencies + +### Internal +- `../loadbalance/` - 目标选择和健康检查 +- `../config/` - 代理配置 + +### External +- `github.com/valyala/fasthttp` - HTTP 客户端/服务器 + + \ No newline at end of file diff --git a/internal/server/AGENTS.md b/internal/server/AGENTS.md index 37de9f7..0dc054e 100644 --- a/internal/server/AGENTS.md +++ b/internal/server/AGENTS.md @@ -1,5 +1,5 @@ - + # server @@ -12,6 +12,9 @@ HTTP 服务器核心，提供服务器创建、启动、停止和虚拟主机管 |------|-------------| | `server.go` | 服务器核心：Server 结构体、Start()、Stop()、GracefulStop() | | `vhost.go` | 虚拟主机管理：VHostManager、VirtualHost、按 Host 头匹配 | +| `pool.go` | 连接池管理：Worker 池、连接复用、并发控制 | +| `upgrade.go` | 热升级：UpgradeManager、USR2 信号处理、平滑交接 | +| `status.go` | 状态监控：健康端点、统计信息、Prometheus 格式 | ## For AI Agents diff --git a/internal/ssl/AGENTS.md b/internal/ssl/AGENTS.md new file mode 100644 index 0000000..91a88e5 --- /dev/null +++ b/internal/ssl/AGENTS.md @@ -0,0 +1,44 @@ + + + +# ssl + +## Purpose +SSL/TLS 模块，提供证书加载、OCSP Stapling 和 TLS 配置管理功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `ssl.go` | SSL/TLS 核心：证书加载、TLS 配置、SNI 支持、会话缓存 | +| `ocsp.go` | OCSP Stapling：在线证书状态查询、缓存、自动刷新 | +| `ssl_test.go` | SSL/TLS 测试 | +| `ocsp_test.go` | OCSP 测试 | + +## For AI Agents + +### Working In This Directory +- 支持多证书加载，按 SNI 匹配 +- OCSP Stapling 提升 TLS 握手性能 +- TLS 配置强制使用安全参数（TLS 1.2+、强密码套件） +- 会话缓存减少握手开销 + +### Testing Requirements +- 运行测试：`go test ./internal/ssl/...` +- 测试证书加载、OCSP 查询、TLS 配置 + +### Common Patterns +- 证书格式支持 PEM +- OCSP 响应缓存 1 小时 +- 会话票据自动轮换 + +## Dependencies + +### Internal +- `../config/` - SSL 配置 + +### External +- `crypto/tls` - Go 标准库 TLS 实现 +- `golang.org/x/crypto/ocsp` - OCSP 协议支持 + + \ No newline at end of file diff --git a/internal/stream/AGENTS.md b/internal/stream/AGENTS.md new file mode 100644 index 0000000..b18630f --- /dev/null +++ b/internal/stream/AGENTS.md @@ -0,0 +1,39 @@ + + + +# stream + +## Purpose +TCP/UDP Stream 代理模块，支持四层代理和会话管理。 + +## Key Files + +| File | Description | +|------|-------------| +| `stream.go` | Stream 代理核心：TCP/UDP 服务器、连接转发、会话管理 | +| `stream_test.go` | Stream 代理测试 | + +## For AI Agents + +### Working In This Directory +- TCP 代理：监听端口、转发连接、支持多上游 +- UDP 代理：会话管理、超时控制、NAT 穿透 +- 会话跟踪：源地址+端口作为键 +- 超时配置：连接超时、空闲超时 + +### Testing Requirements +- 运行测试：`go test ./internal/stream/...` +- 测试 TCP/UDP 监听、连接转发、会话管理 + +### Common Patterns +- TCP 使用 net.Conn 进行双向数据拷贝 +- UDP 使用会话映射表管理客户端连接 +- 负载均衡策略与 HTTP 代理共享 + +## Dependencies + +### Internal +- `../loadbalance/` - 目标选择 +- `../config/` - Stream 配置 + + \ No newline at end of file