# RateLimiter

**Repository Path**: chen-zhangyi666/RateLimiter

## Basic Information

- **Project Name**: RateLimiter
- **Description**: JAVA自定义注解实现接口/ip限流
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2025-08-14
- **Last Updated**: 2025-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



---

# RateLimiter 项目简介

这是一个基于 Spring Boot 和 Redis 实现的分布式限流组件。通过自定义注解与 AOP 切面，可以轻松地对方法进行限流控制，适用于高并发场景下的访问频率限制。

## 特性

- 使用 Redis + Lua 脚本实现原子性限流操作，保障分布式环境下的准确性。
- 自定义注解 `@RateLimiter` 可灵活配置限流时间窗口与访问次数。
- 支持统一异常处理，通过 `@RestControllerAdvice` 捕获限流异常并返回友好响应。
- 可扩展性强，方便集成到其他 Spring Boot 项目中。

## 技术栈

- Java 1.8
- Spring Boot
- Redis
- Lua
- Maven

## 快速启动

1. **克隆项目：**

   ```bash
   git clone https://gitee.com/chen-zhangyi666/RateLimiter.git
   ```

2. **进入项目目录：**

   ```bash
   cd RateLimiter
   ```

3. **构建项目：**

   ```bash
   mvn clean install
   ```

4. **启动项目：**

   ```bash
   mvn spring-boot:run
   ```

5. **访问测试接口：**

   ```bash
   curl http://localhost:8080/hello
   ```

   如果在 10 秒内超过 3 次访问，会抛出限流异常并返回提示信息。

## 使用说明

### 注解使用方式

在需要限流的接口方法上添加 `@RateLimiter` 注解，例如：

```java
@GetMapping("/hello")
@RateLimiter(time = 10, count = 3, limitType = LimitType.DEFAULT)
public String hello() {
    return "Hello, you accessed successfully!";
}
```

- `time`: 限流时间窗口（秒）
- `count`: 在时间窗口内允许的最大访问次数
- `limitType`: 限流类型（默认为 IP 限流）

### 异常处理

当触发限流时，会抛出 `RateLimitException`，由 `GlobalException` 统一捕获并返回 JSON 格式的异常信息。

### Redis 配置

项目通过 `RedisConfig` 配置类初始化 `RedisTemplate` 并加载 Lua 脚本，确保 Redis 操作的高效性与一致性。

### Lua 脚本

`rateLimit.lua` 用于实现限流逻辑，通过 Redis 的原子性执行保证并发安全。

## 目录结构

```
src/
├── main/
│   ├── java/
│   │   ├── com.xxx/
│   │   │   ├── RateLimiterApplication.java        # 启动类
│   │   │   ├── annotation/RateLimiter.java       # 自定义限流注解
│   │   │   ├── aspect/RateLimitAspect.java       # 限流切面逻辑
│   │   │   ├── config/RedisConfig.java           # Redis 配置
│   │   │   ├── controller/HelloController.java   # 测试控制器
│   │   │   ├── enums/LimitType.java              # 限流类型枚举
│   │   │   ├── exception/RateLimitException.java # 限流异常类
│   │   │   └── exception/GlobalException.java    # 全局异常处理
│   ├── resources/
│   │   ├── application.yml                       # 配置文件
│   │   └── lua/rateLimit.lua                     # Lua 限流脚本
```

## 贡献指南

欢迎贡献代码和改进功能！请遵循以下步骤：

1. Fork 仓库
2. 创建新分支
3. 提交 Pull Request

请确保代码风格与项目一致，并提供清晰的提交信息。

## 许可证

该项目遵循 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

--- 

如需进一步帮助，请查看项目源码或联系项目维护者。