docs: 添加模块上下文文档 (AGENTS.md)

为各模块添加上下文文档，帮助 AI 助手理解代码结构： - AGENTS.md: 项目根目录上下文 - docs/AGENTS.md: 文档目录说明 - internal/AGENTS.md: 内部包结构概览 - 各子模块 AGENTS.md: 模块特定上下文和约定 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-02 16:25:51 +08:00 · 2026-04-02 16:25:51 +08:00 · 179aacac04
commit 179aacac04
parent 413e418b37
10 changed files with 428 additions and 14 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,56 @@
+<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+
+# 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 解析库
+
+<!-- MANUAL: -->
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@ -0,0 +1,57 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+
+# 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/` - 实现代码目录，文档描述的功能在此实现
+
+<!-- MANUAL: -->
--- 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）

 ---

--- a/internal/AGENTS.md
+++ b/internal/AGENTS.md
@ -0,0 +1,47 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+
+# 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 解析
+
+<!-- MANUAL: -->
--- a/internal/app/AGENTS.md
+++ b/internal/app/AGENTS.md
@ -0,0 +1,40 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+
+# 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 服务器创建和启动
+
+<!-- MANUAL: -->
--- a/internal/config/AGENTS.md
+++ b/internal/config/AGENTS.md
@ -0,0 +1,45 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+
+# 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 解析库
+
+<!-- MANUAL: -->
--- a/internal/handler/AGENTS.md
+++ b/internal/handler/AGENTS.md
@ -0,0 +1,39 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+
+# 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 框架
+
+<!-- MANUAL: -->
--- a/internal/logging/AGENTS.md
+++ b/internal/logging/AGENTS.md
@ -0,0 +1,38 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+
+# 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` - 获取请求信息
+
+<!-- MANUAL: -->
--- a/internal/middleware/AGENTS.md
+++ b/internal/middleware/AGENTS.md
@ -0,0 +1,37 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+
+# 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 框架
+
+<!-- MANUAL: -->
--- a/internal/server/AGENTS.md
+++ b/internal/server/AGENTS.md
@ -0,0 +1,46 @@
+<!-- Parent: ../AGENTS.md -->
+<!-- Generated: 2026-04-02 | Updated: 2026-04-02 -->
+
+# 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 服务器框架
+
+<!-- MANUAL: -->