From 179aacac04a2629eb83f50e6acbb6a13aa80a13b Mon Sep 17 00:00:00 2001 From: xfy Date: Thu, 2 Apr 2026 16:25:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E6=A8=A1=E5=9D=97?= =?UTF-8?q?=E4=B8=8A=E4=B8=8B=E6=96=87=E6=96=87=E6=A1=A3=20(AGENTS.md)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 为各模块添加上下文文档，帮助 AI 助手理解代码结构： - AGENTS.md: 项目根目录上下文 - docs/AGENTS.md: 文档目录说明 - internal/AGENTS.md: 内部包结构概览 - 各子模块 AGENTS.md: 模块特定上下文和约定 Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 56 ++++++++++++++++++++++++++++++++++ docs/AGENTS.md | 57 +++++++++++++++++++++++++++++++++++ docs/plan.md | 37 ++++++++++++++--------- internal/AGENTS.md | 47 +++++++++++++++++++++++++++++ internal/app/AGENTS.md | 40 ++++++++++++++++++++++++ internal/config/AGENTS.md | 45 +++++++++++++++++++++++++++ internal/handler/AGENTS.md | 39 ++++++++++++++++++++++++ internal/logging/AGENTS.md | 38 +++++++++++++++++++++++ internal/middleware/AGENTS.md | 37 +++++++++++++++++++++++ internal/server/AGENTS.md | 46 ++++++++++++++++++++++++++++ 10 files changed, 428 insertions(+), 14 deletions(-) create mode 100644 AGENTS.md create mode 100644 docs/AGENTS.md create mode 100644 internal/AGENTS.md create mode 100644 internal/app/AGENTS.md create mode 100644 internal/config/AGENTS.md create mode 100644 internal/handler/AGENTS.md create mode 100644 internal/logging/AGENTS.md create mode 100644 internal/middleware/AGENTS.md create mode 100644 internal/server/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..9444c27 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,56 @@ + + +# lolly + +## Purpose +高性能 HTTP 服务器，类似 nginx 的纯 Go 实现。使用 YAML 配置，单二进制运行，支持静态文件服务、反向代理、负载均衡、SSL/TLS、安全控制等功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `main.go` | 程序入口，CLI 参数解析和启动逻辑 | +| `go.mod` | Go 模块定义，依赖 fasthttp、zerolog、yaml.v3 | +| `go.sum` | 依赖版本锁定 | +| `Makefile` | 构建脚本，支持多平台编译、测试、覆盖率 | +| `lolly.yaml` | 默认配置文件示例 | +| `.gitignore` | Git 忽略规则 | + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `internal/` | 核心业务代码（不可被外部导入） | +| `bin/` | 编译输出目录 | +| `docs/` | 项目文档和实现计划 | + +## For AI Agents + +### Working In This Directory +- 这是 Go 项目，使用 `go mod` 管理依赖 +- 使用 `make build` 构建二进制文件到 `bin/` 目录 +- 使用 `make test` 运行测试，`make test-cover` 生成覆盖率报告 +- 配置文件使用 YAML 格式，结构定义在 `internal/config/config.go` +- HTTP 库使用 fasthttp（比 net/http 快 6 倍），路由使用 fasthttp/router +- 日志库使用 zerolog（零分配，JSON 输出） + +### Testing Requirements +- 运行测试前确保依赖已下载：`go mod download` +- 测试覆盖率目标 >80% +- 使用 `make check` 运行完整检查（fmt + lint + test） + +### Common Patterns +- 配置结构体使用 `yaml` 标签，通过 `gopkg.in/yaml.v3` 解析 +- 中间件使用 `fasthttp.RequestHandler` 函数签名 +- 版本信息通过 `-ldflags` 在编译时注入 +- 信号处理：SIGTERM/SIGINT 快速停止，SIGQUIT 优雅停止 + +## Dependencies + +### External +- `github.com/valyala/fasthttp` - 高性能 HTTP 服务器 +- `github.com/fasthttp/router` - 基于 radix tree 的路由器 +- `github.com/rs/zerolog` - 零分配 JSON 日志库 +- `gopkg.in/yaml.v3` - YAML 解析库 + + \ No newline at end of file diff --git a/docs/AGENTS.md b/docs/AGENTS.md new file mode 100644 index 0000000..16c80bd --- /dev/null +++ b/docs/AGENTS.md @@ -0,0 +1,57 @@ + + + +# docs + +## Purpose +项目文档目录，包含实现计划、nginx 功能参考文档、代码规范和开发指南。 + +## Key Files + +| File | Description | +|------|-------------| +| `plan.md` | 实现计划，定义 6 个开发阶段和任务列表（关键文件，高频访问） | +| `README.md` | 项目概述文档 | +| `prompts.md` | 开发提示和 AI 交互指南 | +| `comments.md` | 代码注释规范（必须遵循） | +| `13-git-commit-guide.md` | Git 提交规范指南 | + +### nginx 功能参考文档 + +| File | Description | +|------|-------------| +| `01-nginx-overview.md` | nginx 概述和架构介绍 | +| `02-nginx-installation.md` | nginx 安装指南 | +| `03-nginx-http-core.md` | HTTP 核心功能参考 | +| `04-nginx-proxy-loadbalancing.md` | 反向代理和负载均衡参考 | +| `05-nginx-ssl-https.md` | SSL/HTTPS 配置参考 | +| `06-nginx-rewrite.md` | URL 重写规则参考 | +| `07-nginx-compression-caching.md` | 压缩和缓存配置参考 | +| `08-nginx-logging-monitoring.md` | 日志和监控配置参考 | +| `09-nginx-security.md` | 安全控制参考 | +| `10-nginx-stream-tcp-udp.md` | TCP/UDP Stream 代理参考 | +| `11-nginx-mail-proxy.md` | 邮件代理参考 | +| `12-nginx-performance-tuning.md` | 性能调优参考 | + +## For AI Agents + +### Working In This Directory +- `plan.md` 是开发的核心参考，定义了各阶段的任务和验证方法 +- 修改代码前应先查阅对应的 nginx 参考文档了解功能需求 +- 代码注释必须遵循 `comments.md` 规范 +- Git 提交格式遵循 `13-git-commit-guide.md` + +### Testing Requirements +- 文档无测试要求，但修改代码后需按 `plan.md` 中的验证方法测试 + +### Common Patterns +- 参考文档采用 nginx 配置对比方式说明功能 +- plan.md 使用阶段划分（Phase 1-6）组织任务 +- 每个阶段有明确的任务列表和验证方法 + +## Dependencies + +### Internal +- `../internal/` - 实现代码目录，文档描述的功能在此实现 + + \ No newline at end of file diff --git a/docs/plan.md b/docs/plan.md index 8d8a35b..e11435b 100644 --- a/docs/plan.md +++ b/docs/plan.md @@ -489,32 +489,37 @@ curl http://localhost:8080/api/health # 应返回 404（代理未实现） #### 3.1 反向代理核心 -**实现**： +**实现**（基于 fasthttp）： ```go // internal/proxy/proxy.go +import "github.com/valyala/fasthttp" + // Proxy 反向代理 type Proxy struct { targets []*Target - transport *http.Transport - bufferPool *bufferPool + clients map[string]*fasthttp.HostClient // 每个目标一个 HostClient + balancer Balancer } // Target 后端目标 type Target struct { - URL *url.URL - Weight int - Healthy bool - Connections int + URL string // 目标地址，如 "http://backend1:8080" + Weight int + Healthy bool + Connections int64 // 当前连接数（原子操作） } + +// HostClient fasthttp 客户端（连接池） +// 每个 Target 对应一个 HostClient，自动管理连接池 ``` **功能清单**： - 请求转发：修改请求头、请求体 - 响应处理：修改响应头 -- 超时配置：连接超时、响应超时 +- 超时配置：连接超时、响应超时（fasthttp.HostClient 配置） - WebSocket 支持：Upgrade 协议检测和转发 - 错误处理：后端不可用时的响应 @@ -1423,12 +1428,16 @@ Phase 6: | 阶段 | 状态 | 主要功能 | | ------- | ------ | ------------------------- | -| Phase 1 | 待开始 | 项目骨架、配置系统 | -| Phase 2 | 待开始 | HTTP 核心、静态文件、路由 | -| Phase 3 | 待开始 | 反向代理、负载均衡 | -| Phase 4 | 待开始 | SSL/TLS、安全控制 | -| Phase 5 | 待开始 | 重写、压缩、缓存、日志 | -| Phase 6 | 待开始 | Stream、性能优化 | +| Phase 1 | ✅ 完成 | 项目骨架、配置系统 | +| Phase 2 | ✅ 完成 | HTTP 核心、静态文件、路由 | +| Phase 3 | ⏳ 待开始 | 反向代理、负载均衡 | +| Phase 4 | ⏳ 待开始 | SSL/TLS、安全控制 | +| Phase 5 | ⏳ 待开始 | 重写、压缩、缓存、日志 | +| Phase 6 | ⏳ 待开始 | Stream、性能优化 | + +**Phase 2 技术选型变更**： +- HTTP 库：使用 [fasthttp](https://github.com/valyala/fasthttp) 替代 `net/http`（性能提升 6 倍） +- 日志库：使用 [zerolog](https://github.com/rs/zerolog)（零分配，~40ns/op） --- diff --git a/internal/AGENTS.md b/internal/AGENTS.md new file mode 100644 index 0000000..a631380 --- /dev/null +++ b/internal/AGENTS.md @@ -0,0 +1,47 @@ + + + +# internal + +## Purpose +核心业务代码目录，包含服务器、配置、处理器、中间件、日志等模块。Go 的 internal 包机制确保这些代码不可被外部项目导入。 + +## Subdirectories + +| Directory | Purpose | +|-----------|---------| +| `app/` | 应用程序入口和运行逻辑（启动、信号处理、版本信息） | +| `config/` | 配置解析、验证和默认值生成 | +| `handler/` | HTTP 请求处理器（路由、静态文件） | +| `logging/` | 日志系统（zerolog 初始化、访问日志） | +| `middleware/` | 中间件框架（接口定义、链式组合） | +| `server/` | HTTP 服务器核心和虚拟主机管理 | + +## For AI Agents + +### Working In This Directory +- 所有包使用 `rua.plus/lolly/internal/{package}` 导入路径 +- 各子包有独立职责，遵循 Go 包设计原则 +- 添加新功能时应参考 `docs/plan.md` 确定所属模块 +- 测试文件与源文件同目录，使用 `_test.go` 后缀 + +### Testing Requirements +- 每个包应有对应的测试文件 +- 运行测试：`go test ./internal/...` +- 测试覆盖率目标 >80% + +### Common Patterns +- 使用 fasthttp 的 `RequestHandler` 函数签名处理请求 +- 配置结构体使用 `yaml` 标签 +- 中间件通过 `Chain.Apply()` 逆序包装 +- 服务器通过 `fasthttp.Server` 配置超时和连接限制 + +## Dependencies + +### External +- `github.com/valyala/fasthttp` - HTTP 服务器框架 +- `github.com/fasthttp/router` - 路由器 +- `github.com/rs/zerolog` - 日志库 +- `gopkg.in/yaml.v3` - YAML 解析 + + \ No newline at end of file diff --git a/internal/app/AGENTS.md b/internal/app/AGENTS.md new file mode 100644 index 0000000..4cc0471 --- /dev/null +++ b/internal/app/AGENTS.md @@ -0,0 +1,40 @@ + + + +# app + +## Purpose +应用程序入口包，提供启动逻辑、信号处理、版本信息显示和配置生成功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `app.go` | 核心逻辑：Run 入口、startServer、printVersion、generateConfig | +| `app_test.go` | 单元测试：版本显示、配置生成、服务器启动测试 | + +## For AI Agents + +### Working In This Directory +- 版本信息变量通过 `-ldflags` 在编译时注入，不要硬编码修改 +- `Run()` 是程序入口函数，返回退出码 +- 信号处理：SIGTERM/SIGINT 快速停止，SIGQUIT 优雅停止（等待 30s） +- `generateConfig()` 生成默认 YAML 配置，调用 `config.DefaultConfig()` + +### Testing Requirements +- 测试文件 `app_test.go` 包含启动逻辑测试 +- 运行测试：`go test ./internal/app/...` +- 测试覆盖率目标 >80% + +### Common Patterns +- 使用 `os.Signal` 和 `signal.Notify` 处理系统信号 +- 服务器启动在 goroutine 中执行，通过 channel 等待错误或信号 +- `shutdownTimeout` 定义优雅停止超时时间 + +## Dependencies + +### Internal +- `../config/` - 配置加载和验证 +- `../server/` - HTTP 服务器创建和启动 + + \ No newline at end of file diff --git a/internal/config/AGENTS.md b/internal/config/AGENTS.md new file mode 100644 index 0000000..c0edc36 --- /dev/null +++ b/internal/config/AGENTS.md @@ -0,0 +1,45 @@ + + + +# config + +## Purpose +配置模块，提供 YAML 配置文件的解析、验证、默认值生成和序列化功能。是整个项目的核心依赖模块（高频访问）。 + +## Key Files + +| File | Description | +|------|-------------| +| `config.go` | 配置结构体定义：Config、ServerConfig、ProxyConfig、SSLConfig 等 | +| `defaults.go` | 默认配置生成：DefaultConfig()、GenerateConfigYAML()（高频访问） | +| `validate.go` | 配置验证：validateServer、validateSSL、validateSecurity 等 | +| `config_test.go` | 配置解析测试 | +| `defaults_test.go` | 默认配置测试 | +| `validate_test.go` | 验证逻辑测试 | + +## For AI Agents + +### Working In This Directory +- 所有配置结构体使用 `yaml` 标签，支持 YAML 序列化/反序列化 +- `Load()` 加载配置文件，自动调用验证 +- `DefaultConfig()` 返回安全默认值（TLS 1.2+，安全头部等） +- `GenerateConfigYAML()` 生成带注释的配置模板 +- `defaults.go` 是高频访问文件，修改需谨慎 + +### Testing Requirements +- 测试覆盖完整：结构体解析、默认值、验证逻辑 +- 运行测试：`go test ./internal/config/...` +- 验证测试使用 table-driven 方式 + +### Common Patterns +- 使用 `gopkg.in/yaml.v3` 解析 YAML +- 验证函数按配置类型分组：validateServer、validateSSL、validateSecurity +- 时间配置使用 `time.Duration`，YAML 中用秒数或带单位字符串（如 "10s"） +- 安全配置强制要求：Basic Auth 启用时必须配置 SSL + +## Dependencies + +### External +- `gopkg.in/yaml.v3` - YAML 解析库 + + \ No newline at end of file diff --git a/internal/handler/AGENTS.md b/internal/handler/AGENTS.md new file mode 100644 index 0000000..9ec9f18 --- /dev/null +++ b/internal/handler/AGENTS.md @@ -0,0 +1,39 @@ + + + +# handler + +## Purpose +HTTP 请求处理器，包含路由管理和静态文件服务功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `router.go` | 路由器封装：基于 fasthttp/router，支持 GET/POST/PUT/DELETE/HEAD | +| `static.go` | 静态文件处理器：文件路径安全检查、索引文件支持 | + +## For AI Agents + +### Working In This Directory +- 使用 `fasthttp/router` 进行路由匹配，基于 radix tree 高效查找 +- 路径参数语法：`{name}` 命名参数，`{name?}` 可选参数，`{filepath:*}` 捕获所有 +- 静态文件处理器包含目录遍历安全检查（拒绝 ".."） +- 索引文件默认为 index.html、index.htm，可配置 + +### Testing Requirements +- 运行测试：`go test ./internal/handler/...` +- 测试路由匹配、路径安全检查、索引文件逻辑 + +### Common Patterns +- 使用 `github.com/valyala/fasthttp` 的 `RequestCtx` 处理请求 +- `fasthttp.ServeFile()` 用于静态文件响应 +- 路由参数通过 `ctx.UserValue("name")` 获取 + +## Dependencies + +### External +- `github.com/fasthttp/router` - 路由器 +- `github.com/valyala/fasthttp` - HTTP 框架 + + \ No newline at end of file diff --git a/internal/logging/AGENTS.md b/internal/logging/AGENTS.md new file mode 100644 index 0000000..7517e6b --- /dev/null +++ b/internal/logging/AGENTS.md @@ -0,0 +1,38 @@ + + + +# logging + +## Purpose +日志模块，使用 zerolog 提供零分配的 JSON 日志输出和访问日志记录。 + +## Key Files + +| File | Description | +|------|-------------| +| `logging.go` | 日志初始化和访问日志记录：Init()、LogAccess()、parseLevel() | + +## For AI Agents + +### Working In This Directory +- 使用 zerolog 的链式 API 记录日志 +- `Init(level, pretty)` 初始化：pretty=true 使用 ConsoleWriter（开发模式） +- `LogAccess()` 记录请求日志：method、path、status、size、duration、remote_addr +- 日志级别：debug、info、warn、error（默认 info） + +### Testing Requirements +- 运行测试：`go test ./internal/logging/...` +- 测试日志级别解析和格式化输出 + +### Common Patterns +- 全局日志实例 `log`，通过 `Init()` 初始化 +- zerolog 的零分配设计适合高并发场景 +- 生产模式输出 JSON 格式，便于日志采集系统解析 + +## Dependencies + +### External +- `github.com/rs/zerolog` - 零分配 JSON 日志库 +- `github.com/valyala/fasthttp` - 获取请求信息 + + \ No newline at end of file diff --git a/internal/middleware/AGENTS.md b/internal/middleware/AGENTS.md new file mode 100644 index 0000000..71d31ae --- /dev/null +++ b/internal/middleware/AGENTS.md @@ -0,0 +1,37 @@ + + + +# middleware + +## Purpose +中间件框架，定义统一的中间件接口和链式组合机制。 + +## Key Files + +| File | Description | +|------|-------------| +| `middleware.go` | 中间件接口和链：Middleware 接口、Chain 结构体、Apply 方法 | + +## For AI Agents + +### Working In This Directory +- `Middleware` 接口定义：`Name() string` 和 `Process(next) RequestHandler` +- `Chain` 用于组合多个中间件，按注册顺序逆序包装 +- `Apply()` 从最后一个中间件开始包装，确保执行顺序正确 +- 后续阶段将添加具体中间件实现（安全、压缩、重写等） + +### Testing Requirements +- 运行测试：`go test ./internal/middleware/...` +- 测试链式组合和执行顺序 + +### Common Patterns +- 中间件使用 `fasthttp.RequestHandler` 函数签名 +- 包装模式：`func(ctx) { preProcess(); next(ctx); postProcess() }` +- 空 Chain 的 `Apply()` 直接返回原始 handler + +## Dependencies + +### External +- `github.com/valyala/fasthttp` - HTTP 框架 + + \ No newline at end of file diff --git a/internal/server/AGENTS.md b/internal/server/AGENTS.md new file mode 100644 index 0000000..37de9f7 --- /dev/null +++ b/internal/server/AGENTS.md @@ -0,0 +1,46 @@ + + + +# server + +## Purpose +HTTP 服务器核心，提供服务器创建、启动、停止和虚拟主机管理功能。 + +## Key Files + +| File | Description | +|------|-------------| +| `server.go` | 服务器核心：Server 结构体、Start()、Stop()、GracefulStop() | +| `vhost.go` | 虚拟主机管理：VHostManager、VirtualHost、按 Host 头匹配 | + +## For AI Agents + +### Working In This Directory +- 使用 `fasthttp.Server` 配置超时和连接限制 +- `Start()` 初始化日志、创建路由、注册静态处理器、应用中间件 +- 默认超时：ReadTimeout 30s、WriteTimeout 30s、IdleTimeout 120s +- `Stop()` 快速停止，`GracefulStop()` 等待请求完成 +- `VHostManager` 支持多虚拟主机，按 Host 头匹配，有默认 fallback + +### Testing Requirements +- 运行测试：`go test ./internal/server/...` +- 测试服务器启动/停止、虚拟主机匹配 + +### Common Patterns +- 服务器配置从 `config.Config` 读取 +- 路由使用 `handler.NewRouter()` 创建 +- 中间件通过 `middleware.NewChain().Apply()` 应用 +- Host 头匹配时去除端口号 + +## Dependencies + +### Internal +- `../config/` - 服务器配置 +- `../handler/` - 路由和静态处理器 +- `../logging/` - 日志初始化 +- `../middleware/` - 中间件链 + +### External +- `github.com/valyala/fasthttp` - HTTP 服务器框架 + + \ No newline at end of file