limiteron 0.2.2

---

📋 目录

• ✨ 特性
• 🎯 使用场景
• 🚀 快速开始
  • 安装
  • 基本用法
• 📚 文档
• 🎨 示例
• 🏗️ 架构
• ⚙️ 配置
• 🧪 测试
• 📊 性能
• 🔒 安全
• 🗺️ 路线图
• 🤝 贡献
• 📄 许可证
• 🙏 致谢

---

✨ 特性

🎯 核心特性

• ✅ 多种限流算法 - 令牌桶、固定窗口、滑动窗口、并发控制
• ✅ 封禁管理 - IP/User/MAC/Geo 封禁、自动封禁、封禁优先级、文件批量加载
• ✅ 配额控制 - 配额分配、配额预警、配额透支
• ✅ 熔断器 - 自动故障转移、状态恢复、降级策略

⚡ 高级特性

• 🚀 高性能 - P99 延迟 < 200μs
• 🔐 安全可靠 - 内存安全、SQL 注入防护、YAML 炸弹防护
• 🌐 多存储支持 - 通过 DBNexus 支持 PostgreSQL、内存存储；缓存通过 oxcache 统一管理
• 📦 易于使用 - 宏支持、简洁 API、Admin REST API

🎨 特性亮点

graph LR
    A[请求] --> B[标识符提取]
    B --> C[限流检查]
    B --> D[封禁检查]
    B --> E[配额检查]
    C --> F[决策链]
    D --> F
    E --> F
    F --> G[允许/拒绝]

    style A fill:#e1f5ff
    style B fill:#b3e5fc
    style C fill:#81d4fa
    style D fill:#81d4fa
    style E fill:#81d4fa
    style F fill:#4fc3f7
    style G fill:#29b6f6

---

🎯 使用场景

use limiteron::limiters::{Limiter, TokenBucketLimiter};

async fn enterprise_api() -> Result<(), Box<dyn std::error::Error>> {
    let limiter = TokenBucketLimiter::new(100, 10); // 100 个令牌，每秒补充 10 个

    // 限流检查
    match limiter.allow(1).await {
        Ok(true) => {
            // 处理请求
            process_request().await;
        }
        Ok(false) => {
            eprintln!("超出限流限制");
        }
        Err(e) => {
            eprintln!("错误: {:?}", e);
        }
    }

    Ok(())
}

async fn process_request() {
    println!("处理请求...");
}

适用于需要高并发和高可靠性的企业应用。

use limiteron::flow_control;

#[flow_control(rate = "100/s", quota = "10000/m", concurrency = 50)]
async fn api_handler(user_id: &str) -> Result<String, limiteron::error::FlowGuardError> {
    // API 业务逻辑
    Ok(format!("处理用户 {} 的请求", user_id))
}

适用于保护 API 服务免受滥用和 DDoS 攻击。

use limiteron::ban_manager::{BanManager, BanManagerConfig, BanTarget};
use limiteron::adapters::StorageFactory;
use std::sync::Arc;

async fn web_app() -> Result<(), Box<dyn std::error::Error>> {
    // 使用 DBNexus 工厂创建存储
    let mut factory = StorageFactory::from_dsn("postgresql://localhost/limiteron");
    factory.initialize(None).await?;
    let ban_storage = factory.create_ban_storage().await?;
    let ban_manager = BanManager::with_dependencies(ban_storage, BanManagerConfig::default()).await?;

    // 检查用户是否被封禁
    let user_target = BanTarget::UserId("user123".to_string());
    if let Some(ban_detail) = ban_manager.is_banned(&user_target).await? {
        println!("用户已被封禁: {}", ban_detail.reason);
        return Err("用户已被封禁".into());
    }

    // 处理请求
    println!("处理 user123 的请求");
    Ok(())
}

适用于需要防止恶意用户和爬虫的 Web 应用。

或者使用 Mock 存储进行测试：

use limiteron::ban_manager::{BanManager, BanTarget};
use limiteron::storage::MemoryBanStorage;
use std::sync::Arc;

async fn web_app_test() -> Result<(), Box<dyn std::error::Error>> {
    // 创建存储和封禁管理器
    let storage = Arc::new(MemoryBanStorage::default());
    let ban_manager = BanManager::new().await?;

    // 检查用户是否被封禁
    let user_target = BanTarget::UserId("user123".to_string());
    if let Some(ban_record) = ban_manager.is_banned(&user_target).await? {
        println!("用户被封禁: {:?}", ban_record);
        return Err("用户被封禁".into());
    }

    // 处理请求
    println!("处理 user123 的请求");
    Ok(())
}

---

🚀 快速开始

安装

🦀 Cargo

[dependencies]
limiteron = { version = "0.2.2", features = ["macros"] }

🔧 特性配置

[dependencies]
limiteron = { version = "0.2.2", features = ["postgres", "ban-manager", "macros"] }

特性标志

🎛️ 可选特性配置

Limiteron 使用 feature flags 来控制功能启用，默认只启用内存存储：

预定义组合

# 最小化：仅核心限流
limiteron = { version = "0.2.2", features = ["minimal"] }

# 标准：核心 + 基础高级功能
limiteron = { version = "0.2.2", features = ["standard"] }

# 完整：所有功能
limiteron = { version = "0.2.2", features = ["full"] }

单独特性

# 存储后端
limiteron = { version = "0.2.2", features = ["postgres"] }

# 高级功能
limiteron = { version = "0.2.2", features = ["ban-manager", "quota-control", "circuit-breaker"] }

# 宏支持
limiteron = { version = "0.2.2", features = ["macros"] }

特性	描述	默认
postgres	PostgreSQL 存储（DBNexus）	❌
ban-manager	封禁管理	❌
quota-control	配额控制	❌
circuit-breaker	熔断器	❌
cache-service	统一缓存服务（支持 DI）	❌
cache-storage	缓存存储（oxcache Redis 集成）	❌
lua-script	Lua 脚本支持（oxcache）	❌
tower-middleware	Tower 中间件集成	❌
event-system	事件系统	❌
macros	宏支持	❌
telemetry	遥测和追踪	❌
monitoring	Prometheus 指标	❌
metrics	DBNexus 指标导出	❌
config-watcher	配置热更新	❌
config-security	配置安全验证	❌
validation	请求验证	❌
fallback	降级策略	❌
audit-log	审计日志	❌
log-redaction	日志脱敏	❌
parallel-checker	并行封禁检查	❌
geo-matching	地理位置匹配	❌
device-matching	设备信息匹配	❌
gcra	GCRA 限流算法	❌
custom-limiter	自定义限流器支持	❌
multi-tenant	多租户支持	❌
admin-api	管理 REST API	❌
webhook	Webhook 通知	❌

基本用法

🎬 5 分钟快速开始

步骤 1: 添加依赖

[dependencies]
limiteron = { version = "0.2.2", features = ["macros"] }

步骤 2: 使用宏

use limiteron::flow_control;

#[flow_control(rate = "10/s")]
async fn api_call() -> Result<String, limiteron::error::FlowGuardError> {
    Ok("成功".to_string())
}

use limiteron::limiters::{Limiter, TokenBucketLimiter};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 步骤 1: 创建限流器
    let limiter = TokenBucketLimiter::new(10, 1); // 10 个令牌，每秒补充 1 个

    // 步骤 2: 检查限流
    match limiter.allow(1).await {
        Ok(true) => println!("✅ 请求允许"),
        Ok(false) => println!("❌ 请求被限流"),
        Err(e) => println!("❌ 错误: {:?}", e),
    }

    // 步骤 3: 使用成本
    match limiter.allow(2).await {
        Ok(true) => println!("✅ 成本为 2 的请求允许"),
        Ok(false) => println!("❌ 成本为 2 的请求被限流"),
        Err(e) => println!("❌ 错误: {:?}", e),
    }

    Ok(())
}

---

📚 文档

📖 更多资源

• 🎓 用户指南 - 详细教程
• 🔧 API 参考 - API 文档
• ❓ 常见问题 - 常见问题解答
• 🐛 故障排除 - 常见问题和解决方案

---

🎨 示例

💡 实用示例

📝 示例 1: 基础限流

use limiteron::limiters::{Limiter, TokenBucketLimiter};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let limiter = TokenBucketLimiter::new(10, 1);

    for i in 0..15 {
        match limiter.allow(1).await {
            Ok(true) => println!("请求 {} ✅", i),
            Ok(false) => println!("请求 {} ❌", i),
            Err(e) => println!("请求 {} 错误: {:?}", i, e),
        }
    }

    Ok(())
}

请求 0 ✅
请求 1 ✅
...
请求 9 ✅
请求 10 ❌
...
请求 14 ❌
✅ 前 10 个请求允许，其余被限流

🔥 示例 2: 使用宏

use limiteron::flow_control;

#[flow_control(rate = "100/s", quota = "10000/m", concurrency = 50)]
async fn api_handler(user_id: &str) -> Result<String, Box<dyn std::error::Error>> {
    // API 业务逻辑
    Ok(format!("处理用户 {} 的请求", user_id))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let result = api_handler("user123").await?;
    println!("{}", result);
    Ok(())
}

处理用户 user123 的请求
✅ 宏自动处理限流

📂 查看所有示例 →

注意：limiteron-examples 已设为 publish = false 并纳入 workspace 管理。

---

🏗️ 架构

系统概览

graph TB
    A[用户应用] --> B[API 层]
    B --> C[Governor]
    C --> D[标识符提取]
    C --> E[决策链]
    D --> F[匹配器]
    E --> G[限流器]
    E --> H[封禁管理]
    E --> I[配额控制]
    E --> J[熔断器]
    G --> K[L2/L3 缓存]
    H --> K
    I --> K
    K --> L[存储层]
    L --> M[PostgreSQL via DBNexus]
    L --> N[内存存储]

    style A fill:#e1f5ff
    style B fill:#b3e5fc
    style C fill:#81d4fa
    style D fill:#4fc3f7
    style E fill:#4fc3f7
    style F fill:#29b6f6
    style G fill:#29b6f6
    style H fill:#29b6f6
    style I fill:#29b6f6
    style J fill:#29b6f6
    style K fill:#0288d1
    style L fill:#0277bd
    style M fill:#01579b
    style N fill:#01579b

组件	描述	状态
Governor	主控制器，端到端流量控制	✅ 稳定
Matchers	标识符提取（IP、用户 ID、设备 ID 等）	✅ 稳定
Limiters	多种限流算法	✅ 稳定
封禁管理	IP/User/MAC/Geo 封禁、文件批量加载、热重载	✅ 稳定
配额控制	配额分配、配额预警	✅ 稳定
熔断器	自动故障转移、状态恢复	✅ 稳定
缓存	L2/L3 缓存支持（oxcache 统一管理）	✅ 稳定
存储层	PostgreSQL via DBNexus、内存	✅ 稳定
Admin API	REST 管理端点（封禁/配额/状态）	✅ 稳定

Limiteron 支持多种存储后端，通过 trait 抽象实现可插拔：

存储后端	模块	特性	说明
MemoryStorage	src/storage/mod.rs	（始终可用）	内存存储，适用于单实例开发和测试
DBNexusStorageAdapter	src/adapters/dbnexus_storage.rs	postgres	通过 DBNexus 支持 PostgreSQL，生产级持久化

注意: v0.2.1 移除了 RedisStorage 与 redis-storage feature。如需 Redis 缓存，通过 cache-storage feature 启用 oxcache 的 Redis 后端统一管理。

MemoryStorage 使用示例：

use limiteron::storage::MemoryStorage;
use limiteron::Governor;

// 内存存储开箱即用
let governor = Governor::new().await;
// 或通过 builder 显式注入
let storage = MemoryStorage::create_storage();
let governor = Governor::builder()
    .with_storage(storage)
    .build()
    .await?;

BanFileLoader 从 YAML 文件批量加载封禁规则：

use limiteron::ban::{BanFileLoader, BanManager};

let ban_manager = BanManager::new().await?;
let loader = BanFileLoader::new("bans.yaml");

// 一次性加载
let result = loader.load_once(&ban_manager).await?;
println!("加载成功 {} 条，失败 {} 条", result.success_count, result.failure_count);

// 启用热重载（需要 `config-watcher` feature，500ms debounce）
loader.start_watching(ban_manager.clone()).await?;

---

⚙️ 配置

🎛️ 配置选项

Limiteron 使用 TOML 格式的配置文件（config.toml），支持环境变量覆盖。

TOML 配置 (config.toml)

version = "1.0"

[global]
storage = "memory"
cache = "memory"
metrics = "prometheus"

[[rules]]
id = "api_rate_limit"
name = "API Rate Limit"
priority = 100

[rules.matchers]
type = "User"
user_ids = ["*"]

[[rules.limiters]]
type = "TokenBucket"
capacity = 1000
refill_rate = 100

[rules.action]
on_exceed = "reject"

环境变量覆盖

# 覆盖全局存储
export LIMITERON_GLOBAL_STORAGE=postgres

加载配置

use limiteron::ConfigLoader;

let config = ConfigLoader::load_from_file("config.toml")?;

选项	类型	默认值	描述
version	String	"0.1.0"	配置版本
global.storage	String	"memory"	存储类型: postgres (通过 DBNexus) / memory
global.cache	String	"memory"	缓存类型: memory/redis（通过 oxcache）
global.metrics	String	"prometheus"	指标类型
rules[].id	String	-	规则标识符
rules[].name	String	-	规则名称
rules[].priority	u16	100	规则优先级
rules[].limiters[].capacity	u64	-	限流器容量
rules[].limiters[].refill_rate	u64	-	限流器补充速率
rate_limit	String	"100/s"	速率限制
quota_limit	String	"10000/m"	配额限制
concurrency_limit	Integer	50	并发限制
l2_capacity	Integer	10000	L2 缓存容量
l3_capacity	Integer	100000	L3 缓存容量
enable_metrics	Boolean	false	启用指标
enable_tracing	Boolean	false	启用追踪

ConfigBuilder（编程方式）

use limiteron::config::ConfigBuilder;

let config = ConfigBuilder::new()
    .with_storage("memory")
    .with_rule(|rule| {
        rule.id("default")
            .token_bucket(1000, 100)
    })
    .build()?;

---

🧪 测试

测试状态: 2000+ 个测试全部通过 ✅

测试类型	测试数量	状态
单元测试	1700+	✅ 通过
集成测试	328	✅ 通过
文档测试	145+	✅ 通过

# 运行所有测试
cargo test --all-features

# 运行单元测试
cargo test --lib

# 运行集成测试（需要 Docker 服务）
cargo test --test integration_tests -- --ignored

# 运行特定测试
cargo test test_name

# 运行基准测试
cargo bench

# 生成覆盖率报告
cargo tarpaulin --out Html

详细测试文档: TESTING.md 覆盖率报告: COVERAGE_REPORT.md

---

📊 性能

⚡ 基准测试结果

注意: 以下数据来自综合测试的实际基准测试结果 (2026-01-19)。

吞吐量

限流器类型	实际	目标	达标率
TokenBucket	12M+ ops/s	500K ops/s	✅ 24x
FixedWindow	20M+ ops/s	300K ops/s	✅ 66x
ConcurrencyLimiter	12M+ ops/s	200K ops/s	✅ 60x

延迟

百分位	TokenBucket	FixedWindow
P50	< 100ns	< 100ns
P95	< 200ns	< 150ns
P99	< 1µs	< 500ns

并发测试结果

测试项	结果	状态
数据一致性	100%	✅ 通过
高并发稳定性	50/100 并发	✅ 通过
限流正确性	1000/1000	✅ 通过

# 运行性能测试
cd temp/comprehensive_test
./target/release/functional_test    # 功能测试
./target/release/performance_test   # 性能测试
./target/release/concurrency_test   # 并发测试

示例输出:

功能测试: 7/7 通过 (100%)
TokenBucket: 12,088,759 ops/s
FixedWindow: 19,920,188 ops/s
ConcurrencyLimiter: 11,891,237 ops/s
并发测试: 100% 数据一致性

---

🔒 安全

🛡️ 安全特性

安全措施

• ✅ 内存保护 - Rust 内存安全保证
• ✅ 输入验证 - IP 地址、用户 ID、MAC 地址验证
• ✅ SQL 注入防护 - 使用参数化查询
• ✅ 密码保护 - 使用 secrecy 库处理敏感数据
• ✅ 审计日志 - 完整的操作跟踪

报告安全问题

请通过 GitHub Issues 报告安全漏洞。

---

🗺️ 路线图

🎯 开发计划

gantt
    title Limiteron 路线图
    dateFormat  YYYY-MM
    section 第一阶段
    核心功能           :done, 2026-01, 2026-03
    section 第二阶段
    功能扩展      :active, 2026-03, 2026-06
    section 第三阶段
    性能优化 :2026-06, 2026-09
    section 第四阶段
    生产就绪        :2026-09, 2026-12

✅ 已完成

• 核心限流
• 封禁管理
• 配额控制
• 熔断器
• 单元和集成测试
• 宏支持
• 通过 DBNexus 支持 PostgreSQL 存储
• Governor 优雅关闭与健康检测（v0.2.0）
• ConfigLoader 环境变量覆盖（v0.2.0）
• CircuitBreaker new() 默认构造（v0.2.0）
• 95%+ 测试覆盖率（v0.2.0）
• pangu 工业级 harness 完整（v0.2.0）
• diting 全维度代码审查（v0.2.0）
• 文档完善与 20 个示例（v0.2.0）
• 移除 RedisStorage，缓存统一由 oxcache 管理（v0.2.1）
• BanTarget::Geo 地理位置封禁（v0.2.1）
• BanFileLoader YAML 文件批量加载 + 热重载（v0.2.1）
• POST /api/v1/ban HTTP 端点（v0.2.1）
• DELETE /api/v1/ban/{target}?type= 支持 MAC/Geo 解封（v0.2.1）
• YAML 炸弹防护、Drop impl、告警背压等安全加固（v0.2.1）
• 96.16% 行覆盖率（v0.2.1）

🚧 进行中

• 性能优化
• 监控和追踪改进

🔜 v0.3.1 计划

• Tower 中间件集成完善
• 事件系统增强
• 更多存储后端测试覆盖
• 性能基准测试更新

🎯 v0.4.0 计划

• 分布式限流（跨实例 Lua 协调）
• Governor shutdown 完整实现（后台任务等待/状态刷新/连接释放/Drop trait）
• MySQL/SQLite 存储支持（待 DBNexus 支持）
• HTB 分层令牌桶
• Bulkhead 隔离

📋 计划中

• Lua 脚本增强
• 自定义匹配器扩展
• 更多存储后端
• Web UI 管理界面

💡 未来想法

• 机器学习驱动的限流
• 更多限流算法
• 社区插件系统

---

🤝 贡献

💖 欢迎贡献！

🐛 报告问题

发现 Bug？ 创建 Issue

💡 功能建议

有建议？ 开始讨论

🔧 提交代码

想贡献？ Fork & PR

如何贡献

1. Fork 仓库
2. Clone 你的 fork: git clone https://github.com/yourusername/limiteron.git
3. Create 分支: git checkout -b feature/amazing-feature
4. Make 你的更改
5. Test 你的更改: cargo test --all-features
6. Commit 你的更改: git commit -m 'Add amazing feature'
7. Push 到分支: git push origin feature/amazing-feature
8. Create Pull Request

代码风格

• 遵循 Rust 标准编码约定
• 编写全面的测试
• 更新文档
• 为新功能添加示例

---

📄 许可证

本项目采用 Apache 2.0 许可证:

---

🙏 致谢

使用优秀工具构建

特别感谢

• 🌟 依赖 - 基于这些优秀项目构建:

  • tokio - 异步运行时
  • sqlx - 异步 SQL 工具包
  • dbnexus - 数据库抽象层
  • oxcache - 缓存抽象层（统一管理 memory/redis 等后端）
  • dashmap - 并发 HashMap
  • lru - LRU 缓存

• 👥 贡献者 - 感谢所有贡献者！

• 💬 社区 - 特别感谢社区成员

---

📞 联系与支持

保持联系

---

⭐ Star 历史

---

💝 支持本项目

如果你觉得这个项目有用，请考虑给它一个 ⭐️！

由 Kirky.X 用 ❤️ 构建

⬆ 返回顶部

---

© 2026 Kirky.X. 保留所有权利。