# TokenBucket

**Repository Path**: huang_ru_yun_admin_admin/TokenBucket

## Basic Information

- **Project Name**: TokenBucket
- **Description**: 分布式令牌桶，主要用于接口限流操作，可针对单个用户设置不同的限流策略
- **Primary Language**: C#
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-07-28
- **Last Updated**: 2026-02-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TokenBucket

基于 .NET 9.0 的高性能轻量级令牌桶限流服务，专为 API 接口限流场景设计。

## ✨ 特性

- ⚡ **高性能** - 纯内存操作，响应速度快
- 🚀 **高并发** - 支持 10万+ 活跃用户并发
- 🎯 **灵活限流** - 支持用户级、用户+接口级限流
- 💾 **持久化** - 支持数据持久化，服务重启不丢失
- 📦 **SDK 支持** - 提供客户端 SDK，开箱即用
- 📚 **Swagger 文档** - 完整的 API 文档

## 📦 安装

### 服务端部署

1. 克隆项目
```bash
git clone https://gitee.com/huang_ru_yun_admin_admin/TokenBucket.git
cd TokenBucket
```

2. 运行服务
```bash
dotnet run --project TokenBucket
```

服务将在 `http://localhost:5000` 启动，Swagger 文档: `http://localhost:5000/swagger`

### 客户端 SDK

引用 `TokenBucket.Client` 项目

## 🚀 快速开始

### 基础用法

```csharp
// 初始化客户端（HTTP）
var client = new TokenBucketClient("localhost:8080;user;password");

// 初始化客户端（HTTPS，以 ;s 结尾）
var clientHttps = new TokenBucketClient("api.example.com;user;password;s");

// 添加限流规则
await client.Add("user_123", new BucketItem
{
    Max = 100,    // 最大令牌数
    Step = 10     // 每次恢复的令牌数
});

// 获取令牌
var allowed = await client.Get("user_123");
if (allowed)
{
    // 允许访问接口
}
```

### 推荐用法：用户+接口限流

```csharp
var client = new TokenBucketClient("api.example.com;user;password;s");
var userId = "user_001";

// 登录接口：严格限流，防止暴力破解
if (await client.TryGetTokenForApi(userId, "login", max: 10, step: 10))
{
    Console.WriteLine("登录成功");
}

// 查询接口：宽松限流，允许正常使用
if (await client.TryGetTokenForApi(userId, "query", max: 1000, step: 100))
{
    Console.WriteLine("查询成功");
}
```

### 批量配置

```csharp
var apiConfigs = new Dictionary<string, (int max, int step)>
{
    { "login", (10, 10) },
    { "query", (1000, 100) },
    { "export", (5, 5) }
};

await client.AddApiLimits("user_001", apiConfigs);
```

## 📖 配置说明

### appsettings.json

```json
{
  "FlushedTime": 1,        // 令牌刷新间隔（秒）
  "EnablePersist": true,   // 是否启用持久化
  "user": "1",             // API 用户名
  "password": "1"          // API 密码
}
```

### 连接字符串格式

| 协议 | 格式 | 示例 |
|------|------|------|
| HTTP | `地址;用户名;密码` | `localhost:8080;user;password` |
| HTTPS | `地址;用户名;密码;s` | `api.example.com;user;password;s` |

### 限流参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| Max | 最大令牌数 | 100 |
| Step | 每次恢复的令牌数 | 10 |
| FlushedTime | 刷新间隔（秒） | 1 |

## 🎯 使用场景

### 场景 1：限制单个用户（不推荐）

```csharp
var key = "user_123";
await client.Add(key, new BucketItem { Max = 100, Step = 10 });
// 问题：该用户所有接口共享限流
```

### 场景 2：限制用户+接口（推荐）✅

```csharp
var userId = "user_001";
// 用户+接口，每个接口独立限流
await client.TryGetTokenForApi(userId, "login", max: 10, step: 10);
await client.TryGetTokenForApi(userId, "query", max: 1000, step: 100);
```

### 场景 3：全局限流

```csharp
var key = "global_api";
await client.Add(key, new BucketItem { Max = 1000, Step = 100 });
// 所有用户共享限流
```

## 📊 性能指标

| 指标 | 值 |
|------|-----|
| QPS | 1000+ |
| 支持用户数 | 10万+ 活跃用户 |
| 内存占用 | ~15MB/10万用户 |
| 部署方式 | 单机即可，无需 Redis |

## 🏗️ 项目结构

```
TokenBucket/
├── TokenBucket/          # 服务端项目
│   ├── Controllers/      # API 控制器
│   ├── Service/          # 后台服务
│   └── Models/           # 数据模型
├── TokenBucket.Client/   # 客户端 SDK
├── TokenBucket.Comm/     # 通信层
└── ClientTest/           # 测试项目
```

## 🔧 核心功能

### 令牌桶管理 API

```csharp
// 添加/更新桶
POST /Add?key={key}&value={bucketItem}

// 获取令牌
POST /Get?key={key}

// 查询桶信息
POST /GetItem?key={key}

// 查询桶数量
POST /GetCount

// 分页查询
POST /GetList
```

### 持久化功能

- 自动定期保存到 `Bucket.bin`
- 服务启动时自动恢复
- 支持配置开关 `EnablePersist`

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 License

本项目采用 MIT 协议开源 - [LICENSE](LICENSE)

## 🔗 相关链接

- [Gitee 项目地址](https://gitee.com/huang_ru_yun_admin_admin/TokenBucket)
- [Swagger API 文档](http://localhost:5000/swagger)
- [.NET 9.0 文档](https://docs.microsoft.com/dotnet/core/)

## 💡 技术栈

- .NET 9.0
- ASP.NET Core
- ConcurrentDictionary
- Swashbuckle (Swagger)
- System.Text.Json

## 📝 更新日志

### v1.0.0 (2024-02)
- 初始版本发布
- 支持 SDK 调用
- 支持持久化
- 性能优化：懒加载刷新
- 支持 HTTPS 连接