# braum

**Repository Path**: shangqingL/braum

## Basic Information

- **Project Name**: braum
- **Description**: 限流工具,支持本地、分布式限流，采用令牌桶算法；
支持注解方式,方便使用；
动态规则配置；
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 8
- **Forks**: 7
- **Created**: 2022-08-01
- **Last Updated**: 2025-08-29

## Categories & Tags

**Categories**: distributed-service

**Tags**: 限流, 分布式

## README

## braum:布隆
### **布隆**：英雄联盟中坦克英雄，拥有巨大的盾牌，可以拦截住对方的各种技能。

>使用令牌桶机制限流的小工具,使用注解方式方便使用。
**braum**帮你实现注解方式，更加简单快捷。
### 支持功能
1. 单机限流
2. 分布式限流
3. 限流key 参数解析
4. 限流key 自定义(暂不支持线程池传递)
5. 限流立即返回异常
6. 等待获取token
7. **注解支持同一个方法多个限流规则**
8. 监控看板
9. 动态规则，目前支持nacos、apollo
![输入图片说明](braum-example/src/main/resources/image.png)
### 项目结构：
1. braum-admin 后台管理监控平台
2. braum-client 客户端，限流核心包
3. braum-example 示例包
4. braum-extension 扩展包

### 使用方式（示例为springboot项目）：
jdk 1.8+
maven 3.5+

拉取代码,打包

#### 单机限流
springboot：单机只需三步即可使用，
1. 第一步：
   拉取代码或引入jar包。
2. 第二步：
```
/**
* 使用 @EnableEasyRateLimiter 注解，才可以使用rateLimiter 注解类工具
*/
@SpringBootApplication()
@EnableEasyRateLimiter
public class Application extends SpringBootServletInitializer {
   ......
}
```
2. 第三步：
```
    //本地单机限流
    @EasyRateLimier(value = "test", permitsPerSecond = 0.1, limiterType = LimiterType.LOCAL, limiterHandleType = LimiterHandleType.WAIT, timeout = 2000L)
    public String global() {
        return "111";
    }
    //分布式限流
    @EasyRateLimier(value = "test", permitsPerSecond = 0.1, limiterType = LimiterType.DIST, limiterHandleType = LimiterHandleType.WAIT, timeout = 2000L)
    public String global() {
        return "111";
    }
    //注解支持多个限流规则
    @EasyRateLimier(value = "localException", permitsPerSecond = 0.1,blockMessage = "限流了",limiterType = LimiterType.LOCAL, limiterHandleType = LimiterHandleType.EXCEPTION)
    @EasyRateLimier(value = "localEx111ception", permitsPerSecond = 11,blockMessage = "又限流了",limiterType = LimiterType.LOCAL, limiterHandleType = LimiterHandleType.EXCEPTION)
    public String localException(User user) {
        return "111";
    }
    //更多示例参考 braum-example
```

#### 分布式限流
1. 配置 redis
```
application.properties 文件

easy.limiter.dist.redis.host=127.0.0.1
easy.limiter.dist.redis.port=6379
easy.limiter.dist.redis.password=xxx
```
2. 使用分布式限流
### 关键类解释

1. cn.mianshiyi.braumclient.ratelimit.EasyLocalRateLimiter
   本地单机限流
2. cn.mianshiyi.braumclient.ratelimit.EasyRedisCalcRateLimiter
   分布式限流，依赖redis
3. cn.mianshiyi.braumclient.annotation.EasyRateLimier
   注解
```
   
    /**
     * 资源命名，唯一标识
     */
    String value() default "";

    /**
     * 限流表达式 可为空
     * 如不为空，则完整限流名：资源命名+限流标识
     *
     * @return keys
     */
    String[] keys() default {};

    /**
     * 限流key定义类型
     *
     * @return 定义类型
     */
    LimiterKeyType keyType() default LimiterKeyType.PARAM;

    /**
     * 每秒内允许通过的数量
     */
    double permitsPerSecond() default 0.0d;

    /**
     * 限流类型 本地、分布式
     * 默认本地
     */
    LimiterType limiterType() default LimiterType.LOCAL;

    /**
     * 限流处理类型 默认 抛出异常
     * RateLimitBlockException
     */
    LimiterHandleType limiterHandleType() default LimiterHandleType.EXCEPTION;

    /**
     * 如果限流处理类型为 WAIT ,则默认有效
     * 超时 默认抛出异常:RateLimitTimeoutBlockException
     * 单位：毫秒
     */
    long timeout() default 10L;
```
### 动态规则
#### nacos使用
1. 引入datasource-nacos包
```aidl
        <dependency>
            <groupId>cn.mianshiyi</groupId>
            <artifactId>braum-datasource-nacos</artifactId>
            <version>1.0.0</version>
        </dependency>
```
2.初始化
```aidl
  //建议在项目启动时初始化
  new NacosDataSource("BRAUM", "cn.mianshiyi.braum.nacos.datasource", "localhost:8848");
```
3.配置
```json
[
    {
        "name":"test1",
        "permitsPerSecond":10
    },
    {
        "name":"test2",
        "permitsPerSecond":0.5
    }
]
```
#### apollo使用
1. 引入datasource-nacos包
```aidl
        <dependency>
            <groupId>cn.mianshiyi</groupId>
            <artifactId>braum-datasource-apollo</artifactId>
            <version>1.0.0</version>
        </dependency>
```
2.初始化
```aidl
  //建议在项目启动时初始化
  new ApolloDataSource("braum-test", "application", "braum.limit.rule", "http://localhost:8080");
```
3.配置
```json
[
    {
        "name":"test1",
        "permitsPerSecond":10
    },
    {
        "name":"test2",
        "permitsPerSecond":0.5
    }
]
```

### 控制台
#### 部署
1. 初始化数据库表，braum-admin模块下admin.sql
2. 配置braum-admin模块application.yml
3. 启动braum-admin模块
4. 限流客户端配置admin的ip及端口，ip为admin的机器ip，端口：6999 
例：spring.easy.limiter.monitor.url=127.0.0.1:6999
#### 示例图：
<img width="1509" alt="image" src="https://user-images.githubusercontent.com/30620322/182065129-2fcc7ae2-ebe3-41c6-911c-f08f2bbf603b.png">
   <img width="1221" alt="image" src="https://user-images.githubusercontent.com/30620322/182065157-053d9621-d557-4a20-86b4-fb118b92e091.png">

### 后续支持
1. 
   支持配置中心 zk等
   支持admin模块动态修改开关限流
2. 支持dubbo接口限流