# guardian

**Repository Path**: mybug/guardian

## Basic Information

- **Project Name**: guardian
- **Description**: 防重提交、接口限流、接口幂等、参数自动Trim、慢接口检测、请求链路追踪、IP黑白名单、防重放攻击、接口开关 —— 一个 Starter 搞定 API 请求防护。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/BigGG-Guardian/guardian
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 52
- **Created**: 2026-04-15
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <a href="https://central.sonatype.com/artifact/io.github.biggg-guardian/guardian-repeat-submit-spring-boot-starter"><img src="https://img.shields.io/maven-central/v/io.github.biggg-guardian/guardian-repeat-submit-spring-boot-starter?label=Maven%20Central&color=orange" alt="Maven Central"></a>
  <img src="https://img.shields.io/badge/Java-1.8+-blue?logo=openjdk&logoColor=white" alt="Java">
  <img src="https://img.shields.io/badge/Spring%20Boot-2.7.x-6DB33F?logo=springboot&logoColor=white" alt="Spring Boot">
  <a href="https://github.com/BigGG-Guardian/guardian/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License"></a>
  <a href="https://github.com/BigGG-Guardian/guardian/releases"><img src="https://img.shields.io/github/v/release/BigGG-Guardian/guardian?label=Release&color=green" alt="Release"></a>
  <a href="https://github.com/BigGG-Guardian/guardian/stargazers"><img src="https://img.shields.io/github/stars/BigGG-Guardian/guardian?style=flat&logo=github" alt="Stars"></a>
</p>

<h1 align="center">Guardian</h1>
<p align="center"><b>轻量级 Spring Boot API 请求层防护框架</b></p>
<p align="center">防重提交、接口限流、接口幂等、参数自动Trim、慢接口检测、请求链路追踪、IP黑白名单、防重放攻击、接口开关、参数签名、请求加解密 —— 一个 Starter 搞定 API 请求防护。</p>

<p align="center">
  <a href="https://github.com/BigGG-Guardian/guardian">GitHub</a> ·
  <a href="https://gitee.com/BigGG-Guardian/guardian">Gitee</a> ·
  <a href="https://central.sonatype.com/artifact/io.github.biggg-guardian/guardian-repeat-submit-spring-boot-starter">Maven Central</a>
</p>

---

<p align="center">
  <img src="assets/guardian-mindmap.png" alt="Guardian 功能全景图" width="700">
</p>

---

## 功能一览

| 功能       | Starter                                      | 注解 | YAML | 说明                                           |
|----------|----------------------------------------------|------|------|----------------------------------------------|
| 防重复提交    | `guardian-repeat-submit-spring-boot-starter` | `@RepeatSubmit` | ✅ | 防止用户重复提交表单/请求                                |
| 接口限流     | `guardian-rate-limit-spring-boot-starter`    | `@RateLimit` | ✅ | 滑动窗口 + 令牌桶，双算法可选                             |
| 接口幂等     | `guardian-idempotent-spring-boot-starter`    | `@Idempotent` | — | Token 机制保证接口幂等性，支持结果缓存                       |
| 参数自动Trim | `guardian-auto-trim-spring-boot-starter`     | — | ✅ | 自动去除请求参数首尾空格 + 不可见字符替换                       |
| 慢接口检测    | `guardian-slow-api-spring-boot-starter`      | `@SlowApiThreshold` | ✅ | 慢接口检测 + Top N 统计 + Actuator 端点               |
| 请求链路追踪   | `guardian-trace-spring-boot-starter`         | — | ✅ | 自动生成/透传 TraceId，MDC 日志串联，支持跨线程传递、MQ 链路追踪     |
| IP黑白名单   | `guardian-ip-filter-spring-boot-starter`     | — | ✅ | 全局黑名单 + URL 绑定白名单，支持精确/通配符/CIDR              |
| 防重放攻击    | `guardian-anti-replay-spring-boot-starter`   | — | ✅ | Timestamp + Nonce 双重校验，nonce TTL 与 timestamp 窗口解耦 |
| 接口开关     | `guardian-api-switch-spring-boot-starter`    | — | ✅ | 动态关闭/开启接口                                    |
| 参数签名     | `guardian-sign-spring-boot-starter`          | `@SignVerify` | ✅ | 支持多种签名算法，请求参数签名验证 + 响应结果签名               |
| 请求加解密   | `guardian-encrypt-spring-boot-starter`       | — | ✅ | 支持 RSA+AES / SM2+SM4 加密，请求解密 + 响应加密             |

每个功能独立模块、独立 Starter，**用哪个引哪个，互不依赖**。所有模块的 YAML 配置均支持**配置中心动态刷新**（Nacos / Apollo 等），无需重启即可生效。

---
# Spring Boot 3.5 + JDK 17 适配总结

> 适配日期：2026-06-24
> 涉及模块：全部 28 个 Maven 模块
> 构建结果：✅ BUILD SUCCESS

---

## 一、背景

项目从 Spring Boot 2.x（`javax.*` 命名空间）升级到 **Spring Boot 3.5.9 + JDK 17**，需要将所有 `javax.servlet`、`javax.annotation` 等 EE 命名空间迁移到 `jakarta.*`，同时修复 Spring 6.x 中被移除的 API。

Spring Boot 3.x 基于 Spring Framework 6，核心变化：
- **Servlet API**：`javax.servlet` → `jakarta.servlet`（Servlet 5.0+）
- **注解 API**：`javax.annotation.PostConstruct` → `jakarta.annotation.PostConstruct`
- **移除 API**：`org.springframework.util.Base64Utils` 在 Spring 6 中已删除

---

## 二、修改清单

### 2.1 pom.xml 修改（14 个文件）

#### 根 pom.xml（`pom.xml`）

| 修改项 | 修改前 | 修改后 |
|---|---|---|
| 版本属性 | `<servlet.version>4.0.1</servlet.version>` | 删除（由 Spring Boot BOM 管理） |
| dependencyManagement | `javax.servlet:javax.servlet-api` 显式声明版本 | 移除该条目，版本由 Spring Boot BOM 提供 |
| guardian-starter-all 依赖管理 | 未声明 `<type>pom</type>` | 添加 `<type>pom</type>` |

#### 12 个 core 模块 pom.xml

统一将 Servlet 依赖从 `javax` 迁移到 `jakarta`：

```xml
<!-- 修改前 -->
<dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <scope>provided</scope>
</dependency>

<!-- 修改后 -->
<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <scope>provided</scope>
</dependency>
```

涉及模块：

| # | 模块 | 文件路径 |
|---|---|---|
| 1 | guardian-core | `guardian-core/pom.xml` |
| 2 | guardian-encrypt-core | `guardian-encrypt/guardian-encrypt-core/pom.xml` |
| 3 | guardian-api-switch-core | `guardian-api-switch/guardian-api-switch-core/pom.xml` |
| 4 | guardian-sign-core | `guardian-sign/guardian-sign-core/pom.xml` |
| 5 | guardian-ip-filter-core | `guardian-ip-filter/guardian-ip-filter-core/pom.xml` |
| 6 | guardian-slow-api-core | `guardian-slow-api/guardian-slow-api-core/pom.xml` |
| 7 | guardian-rate-limit-core | `guardian-rate-limit/guardian-rate-limit-core/pom.xml` |
| 8 | guardian-trace-core | `guardian-trace/guardian-trace-core/pom.xml` |
| 9 | guardian-auto-trim-core | `guardian-auto-trim/guardian-auto-trim-core/pom.xml` |
| 10 | guardian-idempotent-core | `guardian-idempotent/guardian-idempotent-core/pom.xml` |
| 11 | guardian-repeat-submit-core | `guardian-repeat-submit/guardian-repeat-submit-core/pom.xml` |
| 12 | guardian-anti-replay-core | `guardian-anti-replay/guardian-anti-replay-core/pom.xml` |

#### guardian-example/pom.xml

```xml
<!-- 修改前 -->
<dependency>
    <groupId>io.github.biggg-guardian</groupId>
    <artifactId>guardian-starter-all</artifactId>
</dependency>

<!-- 修改后 -->
<dependency>
    <groupId>io.github.biggg-guardian</groupId>
    <artifactId>guardian-starter-all</artifactId>
    <type>pom</type>
</dependency>
```

---

### 2.2 Java 源码修改（6 个文件）

#### 2.2.1 DigestUtils.java（Spring 6 API 移除适配）

**文件**：`guardian-core/src/main/java/com/sun/guardian/core/utils/digest/DigestUtils.java`

**问题**：`org.springframework.util.Base64Utils` 在 Spring Framework 6.x 中已移除。

**修改**：

| 修改项 | 修改前 | 修改后 |
|---|---|---|
| import | `import org.springframework.util.Base64Utils;` | 删除（使用 JDK 内置 `java.util.Base64`） |
| 编码调用（6 处） | `Base64Utils.encodeToString(bytes)` | `Base64.getEncoder().encodeToString(bytes)` |
| 解码调用（10 处） | `Base64Utils.decodeFromString(str)` | `Base64.getDecoder().decode(str)` |
| 版本注释 | `@version java version 1.8` | `@version 17` |

#### 2.2.2 RepeatableRequestFilter.java

**文件**：`guardian-core/src/main/java/com/sun/guardian/core/filter/RepeatableRequestFilter.java`

| 修改项 | 修改前 | 修改后 |
|---|---|---|
| 版本注释 | `@version java version 1.8` | `@version 17` |

> Servlet 相关 import（`jakarta.servlet.FilterChain` 等）已由用户提前手动修改。

#### 2.2.3 RepeatableRequestWrapper.java

**文件**：`guardian-core/src/main/java/com/sun/guardian/core/wrapper/RepeatableRequestWrapper.java`

| 修改项 | 修改前 | 修改后 |
|---|---|---|
| 版本注释 | `@version java version 1.8` | `@version 17` |

#### 2.2.4 Trace 模块 PostConstruct 迁移（3 个文件）

**问题**：`javax.annotation.PostConstruct` 在 JDK 17 中已移除，需迁移到 `jakarta.annotation.PostConstruct`。

| 文件 | 修改 |
|---|---|
| `guardian-trace-rabbitmq/.../GuardianTraceRabbitAutoConfiguration.java` | `import javax.annotation.PostConstruct` → `import jakarta.annotation.PostConstruct` |
| `guardian-trace-kafka/.../GuardianTraceKafkaAutoConfiguration.java` | 同上 |
| `guardian-trace-rocketmq/.../GuardianTraceRocketMQAutoConfiguration.java` | 同上 |

---

## 三、版本对照

| 组件 | 修改前 | 修改后 |
|---|---|---|
| Java | 1.8 | 17 |
| Spring Boot | 2.x | 3.5.9 |
| Servlet API | `javax.servlet:javax.servlet-api:4.0.1` | `jakarta.servlet:jakarta.servlet-api`（BOM 管理，6.0.0） |
| 注解 API | `javax.annotation.PostConstruct` | `jakarta.annotation.PostConstruct` |
| Base64 工具 | `org.springframework.util.Base64Utils`（已移除） | `java.util.Base64`（JDK 内置） |

---

## 四、修改文件汇总

共修改 **20 个文件**：

| 类型 | 数量 | 文件 |
|---|---|---|
| 根 pom.xml | 1 | `pom.xml` |
| 子模块 pom.xml | 13 | 12 个 core 模块 + `guardian-example/pom.xml` |
| Java 源码 | 6 | `DigestUtils.java`、`RepeatableRequestFilter.java`、`RepeatableRequestWrapper.java`、3 个 Trace AutoConfiguration |

---

## 五、验证

```bash
mvn clean install -DskipTests -pl '!guardian-example'
mvn clean compile -pl guardian-example -U
```

结果：**BUILD SUCCESS**，全部 28 个模块编译通过。

---

## 六、注意事项

1. **`javax.crypto.*` 无需迁移**：`javax.crypto.Cipher`、`javax.crypto.Mac` 等属于 JDK 标准 API，不属于 Jakarta EE，保持不变。
2. **Servlet 版本由 BOM 管理**：不要在 dependencyManagement 或子模块中显式指定 `jakarta.servlet-api` 的版本，由 Spring Boot BOM 统一管理（3.5.9 对应 6.0.0）。
3. **pom 类型依赖**：`guardian-starter-all` 打包类型为 `pom`，被依赖时必须声明 `<type>pom</type>`，否则 Maven 找不到 jar 会报错。


## 开源协议

[Apache License 2.0](LICENSE)