From 2688ed6a9c2f1250b6fe69d8a40195459c6e7f10 Mon Sep 17 00:00:00 2001 From: xfy Date: Tue, 7 Apr 2026 17:51: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=96=B0=E5=A2=9E=20benchmark/netut?= =?UTF-8?q?il/scripts=20=E7=9B=AE=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 根目录新增 scripts/ 和 .github/ 目录说明 - internal 新增 benchmark/ 和 netutil/ 目录说明 - middleware 新增 bodylimit/ 和 errorintercept/ 目录说明 - 更新日期为 2026-04-07 Co-Authored-By: Claude Opus 4.6 --- .github/AGENTS.md | 37 +++++++++++++++++++++++++ .github/workflows/AGENTS.md | 41 ++++++++++++++++++++++++++++ AGENTS.md | 4 ++- docs/update-prompts.md | 2 ++ internal/AGENTS.md | 4 ++- internal/benchmark/AGENTS.md | 43 ++++++++++++++++++++++++++++++ internal/benchmark/tools/AGENTS.md | 42 +++++++++++++++++++++++++++++ internal/middleware/AGENTS.md | 4 ++- internal/netutil/AGENTS.md | 41 ++++++++++++++++++++++++++++ scripts/AGENTS.md | 39 +++++++++++++++++++++++++++ 10 files changed, 254 insertions(+), 3 deletions(-) create mode 100644 .github/AGENTS.md create mode 100644 .github/workflows/AGENTS.md create mode 100644 internal/benchmark/AGENTS.md create mode 100644 internal/benchmark/tools/AGENTS.md create mode 100644 internal/netutil/AGENTS.md create mode 100644 scripts/AGENTS.md diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 0000000..3bc207b --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,37 @@ + + + +# .github + +## Purpose +GitHub 配置目录，包含 CI/CD 工作流定义，自动化构建、测试和基准测试回归检测。 + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `workflows/` | GitHub Actions 工作流定义 | + +## For AI Agents + +### Working In This Directory +- CI 工作流在 PR 和推送时自动触发 +- 基准测试回归检测防止性能退化合并 +- 工作流使用 Makefile 命令执行任务 + +### Testing Requirements +- CI 自动运行测试，无需手动触发 +- 本地可通过 `make check` 预验证 + +### Common Patterns +- 工作流触发条件：push 到 master、PR 创建/更新 +- 测试步骤：fmt → lint → test → benchmark +- 回归检测：比较基准测试结果差异 + +## Dependencies + +### Internal +- `../Makefile` - 构建命令定义 +- `../scripts/` - 辅助脚本 + + \ No newline at end of file diff --git a/.github/workflows/AGENTS.md b/.github/workflows/AGENTS.md new file mode 100644 index 0000000..6d18ebc --- /dev/null +++ b/.github/workflows/AGENTS.md @@ -0,0 +1,41 @@ + + + +# workflows + +## Purpose +GitHub Actions 工作流定义，自动化构建、测试和基准测试回归检测流程。 + +## Key Files + +| File | Description | +|------|-------------| +| `benchmark.yml` | 基准测试工作流，运行性能测试并检测回归 | + +## For AI Agents + +### Working In This Directory +- 工作流使用 Go 最新稳定版本 +- 基准测试结果存储用于历史比较 +- 回归检测失败会阻止 PR 合并 + +### Testing Requirements +- 工作流自动执行，本地可通过 `make benchmark` 预运行 +- 回归阈值在 `scripts/check_regression.py` 中定义 + +### Common Patterns +- 触发条件：`on: push, pull_request` +- 步骤：checkout → setup-go → make benchmark → check_regression +- 失败处理：输出报告，标记 PR 检查失败 + +## Dependencies + +### Internal +- `../../Makefile` - 构建命令 +- `../../scripts/check_regression.py` - 回归检测脚本 + +### External +- GitHub Actions - 运行环境 +- Go toolchain - 编译和测试 + + \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index 63a76d3..0695e53 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,4 +1,4 @@ - + # lolly @@ -24,6 +24,8 @@ | `internal/` | 核心业务代码（不可被外部导入） | | `bin/` | 编译输出目录 | | `docs/` | 项目文档和实现计划 | +| `scripts/` | 构建/测试辅助脚本（回归检测） | +| `.github/` | CI/CD 工作流定义 | ## For AI Agents diff --git a/docs/update-prompts.md b/docs/update-prompts.md index 95bb9a5..04a0cdc 100644 --- a/docs/update-prompts.md +++ b/docs/update-prompts.md @@ -28,3 +28,5 @@ /ultrawork 深度分析下，有没有重复的逻辑/代码，或者冗余的东西 /ultrawork 运行 make lint，并修复 + +/ultrawork 深度分析下当前项目的性能 \ No newline at end of file diff --git a/internal/AGENTS.md b/internal/AGENTS.md index c3f6d0f..9fc5f24 100644 --- a/internal/AGENTS.md +++ b/internal/AGENTS.md @@ -1,5 +1,5 @@ - + # internal @@ -11,6 +11,7 @@ | Directory | Purpose | |-----------|---------| | `app/` | 应用程序入口和运行逻辑（启动、信号处理、版本信息） | +| `benchmark/` | 基准测试基础设施（Mock 后端、负载生成器、回归检测） | | `cache/` | 文件缓存模块（缓存存储、过期管理） | | `config/` | 配置解析、验证和默认值生成 | | `handler/` | HTTP 请求处理器（路由、静态文件、Sendfile） | @@ -18,6 +19,7 @@ | `loadbalance/` | 负载均衡策略（轮询、最少连接、健康检查） | | `logging/` | 日志系统（zerolog 初始化、访问日志） | | `middleware/` | 中间件框架（接口定义、链式组合） | +| `netutil/` | 网络工具函数（客户端 IP 提取、URL 解析） | | `proxy/` | 反向代理模块（HTTP/WebSocket 代理） | | `server/` | HTTP 服务器核心、虚拟主机、热升级、状态监控 | | `ssl/` | SSL/TLS 管理（证书加载、OCSP Stapling） | diff --git a/internal/benchmark/AGENTS.md b/internal/benchmark/AGENTS.md new file mode 100644 index 0000000..0650768 --- /dev/null +++ b/internal/benchmark/AGENTS.md @@ -0,0 +1,43 @@ + + + +# benchmark + +## Purpose +基准测试基础设施目录，提供负载生成、Mock 后端和测试数据生成工具，用于验证服务器性能和回归检测。 + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `tools/` | 基准测试工具集（Mock 后端、负载生成器、测试数据生成） | + +## For AI Agents + +### Working In This Directory +- 基准测试使用 Go 的 testing.B 框架 +- Mock 后端使用 fasthttputil.InmemoryListener 进行内存通信 +- 负载生成器支持并发请求和延迟统计 + +### Testing Requirements +- 运行基准测试：`go test -bench=. ./internal/benchmark/...` +- 基准测试文件使用 `_bench_test.go` 后缀 +- 使用 `make benchmark` 运行完整基准测试套件 + +### Common Patterns +- 使用 `fasthttputil.NewInmemoryListener` 避免网络开销 +- 统计收集：QPS、P50/P90/P99 延迟、错误率 +- 回归检测通过 `scripts/check_regression.py` 自动执行 + +## Dependencies + +### Internal +- `rua.plus/lolly/internal/proxy` - 代理模块基准测试 +- `rua.plus/lolly/internal/cache` - 缓存模块基准测试 +- `rua.plus/lolly/internal/loadbalance` - 负载均衡基准测试 + +### External +- `github.com/valyala/fasthttp` - HTTP 客户端/服务器 +- `github.com/valyala/fasthttp/fasthttputil` - 内存测试工具 + + \ No newline at end of file diff --git a/internal/benchmark/tools/AGENTS.md b/internal/benchmark/tools/AGENTS.md new file mode 100644 index 0000000..b204270 --- /dev/null +++ b/internal/benchmark/tools/AGENTS.md @@ -0,0 +1,42 @@ + + + +# tools + +## Purpose +基准测试工具集，提供 Mock 后端服务器、负载生成器和测试数据生成功能，支持各种测试场景（延迟、错误、随机响应）。 + +## Key Files + +| File | Description | +|------|-------------| +| `mock_backend.go` | Mock 后端实现，支持多种响应模式（固定、延迟、错误、随机） | +| `loadgen.go` | 负载生成器，收集 QPS、延迟分布（P50/P90/P99）统计 | +| `testdata.go` | 测试数据生成，支持多种预定义大小（1KB~10MB） | + +## For AI Agents + +### Working In This Directory +- Mock 后端使用 `fasthttputil.InmemoryListener` 进行零网络开销测试 +- `BackendMode` 支持四种模式：ModeFixed、ModeDelay、ModeError、ModeRandomResponse +- 负载生成器支持并发执行和百分位延迟统计 +- 测试数据使用随机字节填充，适合压缩测试 + +### Testing Requirements +- 工具本身无独立测试，作为其他模块基准测试的基础设施 +- 使用示例见 `internal/proxy/proxy_bench_test.go` + +### Common Patterns +- 创建简单后端：`SimpleMockBackend(statusCode, body)` +- 创建延迟后端：`DelayedMockBackend(delay, body)` +- 创建错误后端：`ErrorMockBackend(errorRate, body)` +- 创建加权目标：`CreateWeightedTestTargets(n)` +- 运行负载测试：`loadGen.Run(n, concurrency)` + +## Dependencies + +### External +- `github.com/valyala/fasthttp` - HTTP 框架 +- `github.com/valyala/fasthttp/fasthttputil` - 内存监听器 + + \ No newline at end of file diff --git a/internal/middleware/AGENTS.md b/internal/middleware/AGENTS.md index e9ec788..12460e5 100644 --- a/internal/middleware/AGENTS.md +++ b/internal/middleware/AGENTS.md @@ -1,5 +1,5 @@ - + # middleware @@ -17,7 +17,9 @@ | Directory | Purpose | |-----------|---------| | `accesslog/` | 访问日志中间件（请求记录、响应统计） | +| `bodylimit/` | 请求体大小限制中间件（超限返回 413） | | `compression/` | 响应压缩中间件（Gzip、Deflate） | +| `errorintercept/` | 错误拦截中间件（自定义错误页面） | | `rewrite/` | URL 重写中间件（正则替换、路径转换） | | `security/` | 安全中间件（访问控制、认证、限流、安全头部） | diff --git a/internal/netutil/AGENTS.md b/internal/netutil/AGENTS.md new file mode 100644 index 0000000..50fb2e4 --- /dev/null +++ b/internal/netutil/AGENTS.md @@ -0,0 +1,41 @@ + + + +# netutil + +## Purpose +网络相关的通用工具函数包，提供客户端 IP 提取、URL 解析等功能，供 proxy、middleware、server 等模块共享使用。 + +## Key Files + +| File | Description | +|------|-------------| +| `ip.go` | 客户端 IP 提取函数，支持 X-Forwarded-For、X-Real-IP 头 | +| `url.go` | URL 解析函数，提取主机地址和 TLS 标志 | +| `ip_test.go` | IP 提取函数单元测试 | +| `url_test.go` | URL 解析函数单元测试 | + +## For AI Agents + +### Working In This Directory +- IP 提取顺序：X-Forwarded-For 第一个 IP → X-Real-IP → RemoteAddr +- `ExtractClientIP` 返回字符串，适用于日志记录 +- `ExtractClientIPNet` 返回 net.IP，适用于 CIDR 匹配等网络操作 +- URL 解析支持 http:// 和 https:// 前缀，自动添加默认端口 + +### Testing Requirements +- 运行测试：`go test ./internal/netutil/...` +- 测试覆盖：各种代理头组合、URL 格式解析 + +### Common Patterns +- 提取客户端 IP：`ExtractClientIP(ctx)` → "192.168.1.1" +- 提取 net.IP：`ExtractClientIPNet(ctx)` → net.IP 对象 +- 解析 URL：`ParseTargetURL("https://api.example.com", true)` → ("api.example.com:443", true) +- 提取主机：`ExtractHost("http://backend:8080/path")` → "backend:8080" + +## Dependencies + +### External +- `github.com/valyala/fasthttp` - HTTP 请求上下文 + + \ No newline at end of file diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md new file mode 100644 index 0000000..ee21b26 --- /dev/null +++ b/scripts/AGENTS.md @@ -0,0 +1,39 @@ + + + +# scripts + +## Purpose +构建和测试辅助脚本目录，包含回归检测、CI/CD 相关的自动化脚本。 + +## Key Files + +| File | Description | +|------|-------------| +| `check_regression.py` | 基准测试回归检测脚本，比较新旧结果检测性能退化 | + +## For AI Agents + +### Working In This Directory +- 回归检测脚本用于 CI/CD 流程中自动检测性能退化 +- Python 脚本需要依赖环境配置 +- 脚本通过 Makefile 命令调用 + +### Testing Requirements +- 无独立测试，作为 CI/CD 工具使用 +- 通过 `make benchmark-regression` 执行回归检测 + +### Common Patterns +- 回归检测比较基准测试结果的 QPS 和延迟变化 +- 配置阈值定义可接受的性能波动范围 +- 输出报告用于 PR 审核和决策 + +## Dependencies + +### Internal +- `../internal/benchmark/` - 基准测试结果数据源 + +### External +- Python 3.x - 脚本运行环境 + + \ No newline at end of file