# API Protect Starter

**Repository Path**: simplecoder-1/api-protect-starter

## Basic Information

- **Project Name**: API Protect Starter
- **Description**: 一个强大的 Spring Boot Starter，集成了多种 API 请求防护功能，让您轻松构建安全、可靠的 RESTful API。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-08
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# API Protect Starter

一个强大的 Spring Boot Starter，集成了多种 API 请求防护功能，让您轻松构建安全、可靠的 RESTful API。

## 功能特性

✅ **防重提交** - 防止用户快速重复提交请求  
✅ **接口限流** - 基于滑动窗口的速率限制  
✅ **接口幂等** - 确保重复请求只执行一次  
✅ **参数自动 Trim** - 自动去除请求参数前后空格  
✅ **慢接口检测** - 自动检测并记录慢查询  
✅ **请求链路追踪** - 自动生成和传递 Trace ID  
✅ **IP 黑白名单** - 支持 IP 访问控制  
✅ **防重放攻击** - 防止请求被恶意重放  
✅ **接口开关** - 动态控制接口启用/禁用  

## 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>com.api.protect</groupId>
    <artifactId>api-protect-starter</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 配置 application.properties

```properties
# 启用所有防护功能（默认全部启用）
api.protect.enabled=true
api.protect.auto-trim-enabled=true
api.protect.rate-limit-enabled=true
api.protect.idempotent-enabled=true
api.protect.anti-repeat-enabled=true
api.protect.anti-replay-enabled=true
api.protect.ip-access-enabled=true
api.protect.slow-query-enabled=true
api.protect.trace-id-enabled=true
api.protect.api-switch-enabled=true

# 慢查询阈值（毫秒）
api.protect.slow-query-threshold=1000

# 默认限流配置
api.protect.rate-limit-max-requests=100
api.protect.rate-limit-duration=1
```

## 注解使用说明

### 1. @AntiRepeat - 防重提交

防止短时间内重复提交请求。

```java
@GetMapping("/submit")
@AntiRepeat(interval = 5000, message = "操作太快了，请 5 秒后再试")
public Result submit() {
    return Result.success();
}
```

**参数说明：**
- `interval`: 时间间隔，默认 1000 毫秒
- `timeUnit`: 时间单位，默认 MILLISECONDS
- `message`: 提示信息

### 2. @RateLimit - 接口限流

限制单位时间内的请求次数。

```java
@GetMapping("/query")
@RateLimit(maxRequests = 10, duration = 10, message = "访问过于频繁")
public Result query() {
    return Result.success();
}
```

**参数说明：**
- `maxRequests`: 最大请求次数，默认 100
- `duration`: 时间窗口，默认 1
- `timeUnit`: 时间单位，默认 SECONDS
- `key`: 自定义限流 key（可选）
- `message`: 提示信息

### 3. @Idempotent - 接口幂等

确保相同请求在指定时间内只执行一次。

```java
@PostMapping("/order")
@Idempotent(key = "create_order", expireTime = 10, message = "请勿重复提交")
public Result createOrder(@RequestBody Order order) {
    return Result.success();
}
```

**参数说明：**
- `key`: 幂等 key（可选，默认根据方法和参数生成）
- `expireTime`: 过期时间，默认 5 秒
- `timeUnit`: 时间单位，默认 SECONDS
- `message`: 提示信息

### 4. @AutoTrim - 参数自动 Trim

自动去除请求参数的前后空格。

```java
@PostMapping("/update")
@AutoTrim
public Result update(@RequestBody User user) {
    // user 的字符串参数会自动 trim
    return Result.success();
}
```

**参数说明：**
- `enabled`: 是否启用，默认 true
- `excludeParams`: 排除的参数名（可选）

### 5. @SlowQuery - 慢接口检测

自动检测并记录执行时间超过阈值的接口。

```java
@GetMapping("/search")
@SlowQuery(threshold = 2000, logParams = true)
public Result search(@RequestParam String keyword) {
    return Result.success();
}
```

**参数说明：**
- `threshold`: 阈值（毫秒），默认 1000
- `timeUnit`: 时间单位，默认 MILLISECONDS
- `logParams`: 是否记录参数，默认 false

### 6. @TraceId - 请求链路追踪

自动生成和传递 Trace ID，便于日志追踪。

```java
@GetMapping("/data")
@TraceId
public Result getData() {
    // Trace ID 会自动放入 MDC 和响应头
    return Result.success();
}
```

**参数说明：**
- `enabled`: 是否启用，默认 true
- `headerName`: 请求头名称，默认 "X-Trace-Id"

### 7. @IpAccess - IP 黑白名单

限制允许访问的 IP 地址。

```java
@PostMapping("/admin")
@IpAccess(
    whitelist = {"127.0.0.1", "192.168.1.*"},
    blacklist = {"10.0.0.1"}
)
public Result admin() {
    return Result.success();
}
```

**参数说明：**
- `whitelist`: IP 白名单（支持通配符）
- `blacklist`: IP 黑名单（支持通配符）
- `message`: 提示信息

### 8. @AntiReplay - 防重放攻击

防止请求被恶意重放。

```java
@PostMapping("/payment")
@AntiReplay(
    timeWindow = 300,
    nonceHeader = "X-Nonce",
    timestampHeader = "X-Timestamp",
    signHeader = "X-Sign"
)
public Result payment(@RequestBody Payment payment) {
    return Result.success();
}
```

**参数说明：**
- `nonceHeader`: Nonce 请求头，默认 "X-Nonce"
- `timestampHeader`: 时间戳请求头，默认 "X-Timestamp"
- `signHeader`: 签名请求头，默认 "X-Sign"
- `timeWindow`: 时间窗口（秒），默认 300
- `message`: 提示信息

**客户端需要添加请求头：**
```
X-Nonce: unique-random-string
X-Timestamp: 1234567890
X-Sign: md5(nonce + timestamp + secret)
```

### 9. @ApiSwitch - 接口开关

动态控制接口的启用/禁用。

```java
@GetMapping("/feature")
@ApiSwitch(key = "new.feature", defaultValue = true)
public Result feature() {
    return Result.success();
}
```

**参数说明：**
- `key`: 开关 key（必填）
- `defaultValue`: 默认值，默认 true
- `message`: 接口关闭时的提示信息

**动态控制开关：**
```java
@Autowired
private ApiSwitchService apiSwitchService;

// 关闭接口
apiSwitchService.setSwitch("new.feature", false);

// 开启接口
apiSwitchService.setSwitch("new.feature", true);

// 获取开关状态
boolean enabled = apiSwitchService.getSwitch("new.feature", true);
```

## 组合使用示例

```java
@RestController
@RequestMapping("/api/order")
public class OrderController {

    @PostMapping("/create")
    @AntiRepeat(interval = 3000)
    @RateLimit(maxRequests = 5, duration = 10)
    @Idempotent(key = "create_order", expireTime = 10)
    @TraceId
    @ApiSwitch(key = "order.create", defaultValue = true)
    public Result createOrder(@RequestBody @AutoTrim Order order) {
        // 多种防护同时生效
        return orderService.create(order);
    }

    @GetMapping("/{id}")
    @SlowQuery(threshold = 2000, logParams = true)
    @RateLimit(maxRequests = 20, duration = 5)
    @TraceId
    public Result getOrder(@PathVariable Long id) {
        return orderService.getById(id);
    }
}
```

## 异常处理

所有防护功能抛出的异常会被统一处理：

```java
{
  "code": 429,
  "message": "访问过于频繁，请稍后再试",
  "data": null
}
```

**状态码说明：**
- 429: 限流、防重提交
- 403: IP 黑名单、防重放攻击
- 500: 其他错误

## 日志配置

推荐配置日志格式以包含 Trace ID：

```properties
logging.pattern.console=%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - traceId=%X{traceId} - %msg%n
```

## 高级用法

### 自定义限流 Key

```java
@RateLimit(key = "#userId", maxRequests = 100)
public Result getUserData(@RequestParam String userId) {
    return Result.success();
}
```

### 自定义幂等 Key

```java
@Idempotent(key = "#order.orderNo", expireTime = 30)
public Result createOrder(@RequestBody Order order) {
    return Result.success();
}
```

## 注意事项

1. **性能考虑**: 所有防护功能都使用本地缓存（Caffeine），性能优异
2. **分布式环境**: 如需分布式支持，可配置 Redis（后续版本支持）
3. **注解顺序**: 多个注解同时使用时，按 Order 值从小到大执行
4. **内存管理**: 缓存数据会自动过期，无需手动清理

## 技术栈

- Spring Boot 2.7.18
- Spring AOP
- Caffeine Cache
- Guava
- FastJSON2

## 执行顺序

各防护功能的执行顺序（数字越小越先执行）：

1. TraceId (Order=10)
2. AutoTrim Filter (Order=1)
3. ApiSwitch (Order=50)
4. AntiReplay (Order=60)
5. IpAccess (Order=70)
6. Idempotent (Order=80)
7. RateLimit (Order=90)
8. AntiRepeat (Order=100)
9. SlowQuery (Order=200)

## 示例项目

参考 `api-protect-demo` 模块获取完整使用示例。

## 许可证

MIT License

## 反馈与支持

如有问题或建议，欢迎提交 Issue。