# CLAUDE.md
此文件为 Claude Code (claude.ai/code) 在此仓库中工作时提供指导。
## 项目概述
Revoke 是一个基于 Rust 和 Cloudflare Pingora 构建的高性能云原生 API 网关。它被设计为现代服务架构的综合微服务框架。
## 开发命令
### 构建
```bash
# 构建整个工作空间
cargo build --release
# 构建特定的 crate
cargo build -p revoke-core
cargo build -p gateway
cargo build -p web
# 构建所有功能
cargo build --features full
```
### 测试
```bash
# 运行所有测试
cargo test
# 运行集成测试
cargo test --test integration
# 运行特定 crate 的测试
cargo test -p revoke-core
cargo test -p gateway
```
### 代码质量
```bash
# 格式化代码
cargo fmt
# 代码检查
cargo clippy
# 检查安全漏洞
cargo audit
```
### 运行示例
```bash
# 使用 Docker 启动完整的示例环境
cd examples && ./start.sh
# 仅启动网关和依赖项
cd examples && ./start.sh --mode gateway
# 清理容器
cd examples && ./start.sh --cleanup
```
## 架构
### 工作空间结构
- **revoke-core**: 微服务框架的核心抽象、特征和工具
- **gateway**: 使用 Pingora 的主要 API 网关实现
- **web**: Web 框架组件和 HTTP 工具
- **config**: 配置管理和解析
- **metrics**: Prometheus 指标收集和报告
- **tracing**: OpenTelemetry 分布式追踪
- **log**: 结构化日志工具
- **registry**: 服务发现和注册集成
### 核心组件
#### 核心框架 (revoke-core)
- 服务特征和生命周期管理
- 请求上下文和元数据处理
- 熔断器和限流抽象
- 具有分类的全面错误类型
- 常用操作的工具函数
#### 网关 (gateway)
- 基于 Cloudflare Pingora 的高性能实现
- 多种负载均衡策略（轮询、加权、最少连接）
- 与 Consul 的服务发现集成
- 健康检查（主动和被动）
- 熔断器模式实现
- 可配置策略的限流
- 请求/响应处理的中间件系统
- 指标收集和报告
#### 配置系统
- 基于 YAML 的配置和验证
- 支持环境变量和 TOML
- 热重载功能
- 具有有用错误消息的全面验证
### 关键设计模式
#### 服务发现
服务通过 Consul 集成自动发现。网关监视服务变化并动态更新路由表。
#### 中间件链
请求处理遵循中间件模式，每个中间件可以：
- 修改请求/响应
- 短路处理
- 添加上下文元数据
- 收集指标
#### 熔断器模式
具有可配置故障阈值、超时和恢复策略的自动容错。
#### 负载均衡
可用的多种策略：
- 轮询
- 加权轮询
- 最少连接
- IP 哈希
## 配置
### 网关配置
配置以 YAML 格式定义。查看 `examples/gateway_config.yaml` 获取完整示例。
关键部分：
- `server`: 基本服务器设置（主机、端口、工作进程）
- `routes`: 基于路径的路由规则
- `upstreams`: 后端服务定义
- `middleware`: 请求/响应处理链
- `health_check`: 健康监控配置
- `load_balancer`: 负载均衡策略和设置
### 环境变量
框架支持使用 `REVOKE_` 前缀的环境变量覆盖。
## 测试策略
### 单元测试
每个 crate 都有涵盖核心功能的全面单元测试。
### 集成测试
使用 Docker Compose 和真实服务的完整端到端测试。
### 负载测试
性能测试脚本在 `tests/load/` 中可用。
## 服务集成
### 添加新服务
1. 在 Consul 中注册服务或配置静态上游
2. 在网关配置中添加路由配置
3. 配置适当的中间件链
4. 设置健康检查和监控
### 中间件开发
实现 `GatewayMiddleware` 特征：
```rust
#[async_trait]
pub trait GatewayMiddleware: Send + Sync {
async fn process_request(&self, ctx: &mut GatewayContext) -> Result<()>;
async fn process_response(&self, ctx: &mut GatewayContext) -> Result<()>;
}
```
## 监控和可观测性
### 指标
- 在 `/metrics` 端点暴露的 Prometheus 指标
- 请求/响应指标、错误率、延迟百分位数
- 熔断器状态和限流统计
- 自定义业务指标支持
### 日志
- 带关联 ID 的结构化 JSON 日志
- 可配置的日志级别和输出
- 跨服务边界的请求追踪
### 健康检查
- 网关健康端点在 `/health`
- 上游服务健康监控
- 可配置的故障阈值和恢复
## 性能特征
### 基准测试
- 在现代硬件上支持 >100 万请求/秒
- 简单路由的亚毫秒级 P99 延迟
- 通过连接池的高效内存使用
### 扩展性
- 通过多个网关实例的水平扩展
- 健康上游的自动负载均衡
- 连接池和 keep-alive 优化
## 开发工作流程
1. 对相关 crate 进行更改
2. 运行 `cargo fmt` 和 `cargo clippy`
3. 使用 `cargo test` 运行测试
4. 使用示例环境测试：`cd examples && ./start.sh`
5. 验证网关的配置更改
6. 如果是性能关键更改，运行负载测试
## 常见问题
### 端口冲突
示例环境使用端口 8080-8084。确保这些端口可用或修改 docker-compose 配置。
### 服务发现
如果服务未被发现，请检查：
- Consul 正在运行且可访问
- 服务已正确注册
- 健康检查正在通过
### 内存使用
对于高流量场景，调整：
- 连接池大小
- 请求/响应缓冲区大小
- 垃圾收集设置