# http-governance

**Repository Path**: net_yc60/http-governance

## Basic Information

- **Project Name**: http-governance
- **Description**: 动态HTTP治理平台 - 运维可视推送版
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-07
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智盾 - HTTP智能治理平台

> 🛡️ 一站式 HTTP 请求智能治理平台，让你的接口更稳定、更安全、更可控。

---

## 系统简介

**智盾** 是一个企业级的 HTTP 请求智能治理平台，为您的微服务架构提供全方位的请求治理能力。

### 一句话概括

**一个管理后台，一套 Starter 依赖，让您的业务项目自动获得 12 种强大的 HTTP 治理能力。

### 核心价值

| 能力 | 说明 | 解决的问题 |
|------|------|-----------|
| 🚦 **流量管控** | 限流、熔断、重试 | 防止服务雪崩，保护下游系统 |
| 🛡️ **安全加固** | 签名验证、报文加解密 | 防止数据泄露和篡改 |
| 📊 **可观测性** | 接口日志、慢接口检测、数据脱敏 | 快速定位问题，保护敏感信息 |
| 🔄 **灵活路由** | 动态路由、灰度发布 | 平滑升级、流量切分 |
| 🧪 **混沌工程** | 故障注入、Mock 响应 | 提前发现系统脆弱点 |
| 🎯 **运维监控** | 实时监控、事件追溯 | 生产问题快速排查 |

### 快速预览

启动服务后，您将获得：

```
浏览器访问：http://localhost
├── 仪表盘：系统总览（项目数、规则数、拦截器统计）
├── 规则管理：创建和配置治理规则
├── 项目管理：注册业务项目
├── 拦截器管理：查看 12 种内置拦截器
├── 配置推送：将规则推送到业务项目
└── 运维监控：接口日志、慢接口、限流/熔断/重试事件
```

---

## 一、快速开始（5 分钟上手）

### 1. 环境准备

确保您的系统已安装：
- **JDK 21** 或更高版本
- **Maven 3.6+**
- **Docker** 和 **Docker Compose**

### 2. 一键启动

```bash
# 1. 进入项目根目录
cd http-governance

# 2. 打包项目
mvn clean package -DskipTests

# 3. 启动所有服务
docker compose up -d
```

### 3. 访问系统

服务启动成功后，打开浏览器访问：

| 地址 | 说明 |
|------|------|
| **http://localhost** | **管理后台首页**（推荐） |
| http://localhost:8080/doc.html | API 文档页面 |

### 4. 服务端口说明

| 服务 | 端口 | 说明 |
|------|------|------|
| 前端管理页面 | 80 | Web 控制台 |
| Admin 后台 API | 8080 | 后端服务 |
| MySQL 数据库 | 3306 | 数据存储 |

---

## 二、完整使用指南（图文教程）

### 使用流程总览

使用 **智盾** 治理您的业务项目 HTTP 请求，只需 **5 步**：

```
┌─────────────────────────────────────────────────────────────┐
│                    完整使用流程                               │
├─────────────────────────────────────────────────────────────┤
│                                                       │
│  第一步：创建治理规则                                 │
│       ↓                                                │
│  第二步：配置拦截器（限流/熔断/重试/日志等）            │
│       ↓                                                │
│  第三步：注册业务项目                                 │
│       ↓                                                │
│  第四步：推送配置到业务项目                            │
│       ↓                                                │
│  第五步：查看运维监控（接口日志、事件追溯）              │
│                                                       │
└─────────────────────────────────────────────────────────────┘
```

---

### 第一步：创建治理规则

**规则** 是治理的核心，定义了"哪些请求需要被治理"。

#### 操作步骤：

1. 打开浏览器访问 **http://localhost**
2. 点击左侧菜单「**规则管理**」
3. 点击右上角「**新建规则**」按钮
4. 填写规则信息：

| 字段 | 说明 | 示例 |
|------|------|------|
| 规则名称 | 给规则起个名字 | 用户接口限流 |
| 匹配模式 | 如何匹配请求 URL | 前缀匹配 / 域名匹配 / 正则匹配 |
| 匹配值 | 具体的匹配条件 | `https://api.example.com/user` |
| 优先级 | 多规则时的匹配顺序 | 100（越大越优先） |
| 状态 | 启用/禁用 | 启用 |

5. 点击「**保存**」

#### 匹配模式说明：

| 模式 | 说明 | 示例 |
|------|------|------|
| 前缀匹配 | URL 以该值开头即匹配 | `https://api.example.com/user` 会匹配 `/user/list`、`/user/1` |
| 域名匹配 | URL 的域名等于该值即匹配 | `example.com` |
| 正则匹配 | URL 满足正则表达式即匹配 | `https://api\.example\.com/\d+` |

---

### 第二步：配置拦截器

创建规则后，需要配置该规则触发时执行哪些拦截器。

#### 操作步骤：

1. 在规则列表中，找到刚创建的规则
2. 点击「**配置拦截器**」按钮
3. 在弹窗中点击「**添加拦截器**」
4. 从下拉框选择要添加的拦截器类型
5. 在「**配置参数**（不同拦截器参数不同）
6. 点击「**确定**」添加
7. 可以通过**拖拽**调整拦截器的执行顺序（从上到下执行）
8. 点击「**保存**」

#### 12 种内置拦截器一览：

| 分类 | 拦截器名称 | 功能说明 |
|------|-----------|----------|
| 🚦 流量管控 | 请求限流 | 基于 QPS 的接口限流控制 |
| 🚦 流量管控 | 熔断降级 | 错误率超过阈值时熔断，保护下游 |
| 🚦 流量管控 | 自动重试 | 请求失败时自动重试 |
| 🛡️ 安全加密 | 加签验签 | 请求签名生成与验证 |
| 🛡️ 安全加密 | 报文加解密 | 请求体加密、响应体解密 |
| 📊 可观测性 | 接口日志 | 记录请求/响应详细信息 |
| 📊 可观测性 | 数据脱敏 | 敏感字段自动脱敏 |
| 📊 可观测性 | 慢接口检测 | 检测超过阈值的慢请求 |
| 🔄 灵活路由 | 动态路由 | 动态切换请求目标域名 |
| 🔄 灵活路由 | 灰度发布 | 按比例/指定用户路由到灰度环境 |
| 🧪 混沌工程 | 故障注入 | 模拟延迟、错误、超时等故障 |
| 🧪 混沌工程 | Mock 响应 | 直接返回预设响应 |

#### 常用拦截器配置示例：

**示例 1：请求限流**

限制用户接口 QPS 为 100，超过时返回 429：

```json
{
  "qps": 100,
  "periodSeconds": 1,
  "blockEnabled": true,
  "blockStatusCode": 429,
  "blockBody": "{\"code\":429,\"message\":\"请求过于频繁，请稍后重试\"}"
}
```

**示例 2：熔断降级**

错误率超过 50% 时熔断，等待 30 秒后恢复：

```json
{
  "failureThreshold": 50,
  "waitDuration": 30,
  "permittedCalls": 3,
  "fallbackEnabled": true,
  "fallbackStatusCode": 503,
  "fallbackBody": "{\"code\":503,\"message\":\"服务暂时不可用\"}"
}
```

**示例 3：自动重试**

失败后自动重试 3 次，每次间隔 1 秒：

```json
{
  "maxAttempts": 3,
  "backoff": 1000,
  "fallbackEnabled": true
}
```

**示例 4：接口日志**

记录所有请求和响应：

```json
{
  "logRequest": true,
  "logResponse": true,
  "logHeaders": true,
  "maxBodyLength": 2048
}
```

**示例 5：慢接口检测**

超过 3 秒的请求记录为慢接口：

```json
{
  "thresholdMs": 3000,
  "warnOnSlow": true
}
```

---

### 第三步：注册业务项目

需要将您的业务项目注册到管理平台，以便推送配置。

#### 操作步骤：

1. 点击左侧菜单「**项目管理**」
2. 点击「**新建项目**」按钮
3. 填写项目信息：

| 字段 | 说明 | 示例 |
|------|------|------|
| 项目编码 | 项目唯一标识（英文） | order-service |
| 项目名称 | 项目中文名称 | 订单服务 |
| 客户端类型 | 业务项目使用的 HTTP 客户端 | RestTemplate / RestClient / WebClient |
| 服务 IP | 业务项目部署的 IP | 192.168.1.100 |
| 服务端口 | 业务项目的端口 | 8080 |

4. 点击「**保存**」

---

### 第四步：推送配置

将规则和拦截器配置推送到业务项目。

#### 操作步骤：

1. 点击左侧菜单「**配置推送**」
2. 在下拉框中选择要推送的项目
3. 点击「**推送配置**」按钮
4. 推送成功后，业务项目会自动应用最新配置

> 💡 也可以点击「**推送到所有项目**」一次性推送给所有已注册的项目

---

### 第五步：业务项目集成（引入依赖）

业务项目需要引入对应的 Starter 依赖，才能接收并应用治理规则。

#### 1. 添加依赖

在业务项目的 `pom.xml` 中添加：

**使用 RestTemplate：

```xml
<dependency>
    <groupId>com.governance</groupId>
    <artifactId>governance-starter-template</artifactId>
    <version>1.0.0</version>
</dependency>
```

**使用 RestClient：

```xml
<dependency>
    <groupId>com.governance</groupId>
    <artifactId>governance-starter-restclient</artifactId>
    <version>1.0.0</version>
</dependency>
```

**使用 WebClient：

```xml
<dependency>
    <groupId>com.governance</groupId>
    <artifactId>governance-starter-webclient</artifactId>
    <version>1.0.0</version>
</dependency>
```

#### 2. 启用治理

在启动类添加注解：

```java
@SpringBootApplication
@EnableHttpGovernanceTemplate  // RestTemplate
// 或 @EnableHttpGovernanceRestClient
// 或 @EnableHttpGovernanceWebClient
public class OrderApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderApplication.class, args);
    }
}
```

#### 3. 配置项目信息

在 `application.yml` 中配置：

```yaml
governance:
  project-code: order-service      # 必须与管理平台注册的项目编码一致
  admin-url: http://localhost:8080    # 管理平台地址
  metrics:
    enabled: true                   # 启用运维监控数据上报
    interval: 5000                  # 上报间隔（毫秒）
```

#### 4. 使用（无需修改代码）

**RestTemplate 示例：

```java
@RestController
public class DemoController {
    
    @Autowired
    private RestTemplate restTemplate;  // 自动注入治理版
    
    @GetMapping("/test")
    public String callUserService() {
        // 自动应用规则匹配和拦截器链
        String result = restTemplate.getForObject(
            "https://api.example.com/user/1", 
            String.class
        );
        return result;
    }
}
```

**RestClient 示例：

```java
@RestController
public class DemoController {
    
    @Autowired
    private RestClient restClient;  // 自动注入治理版
    
    @GetMapping("/test")
    public String callUserService() {
        return restClient.get()
            .uri("https://api.example.com/user/1")
            .retrieve()
            .body(String.class);
    }
}
```

**WebClient 示例：

```java
@RestController
public class DemoController {
    
    @Autowired
    private WebClient webClient;  // 自动注入治理版
    
    @GetMapping("/test")
    public Mono<String> callUserService() {
        return webClient.get()
            .uri("https://api.example.com/user/1")
            .retrieve()
            .bodyToMono(String.class);
    }
}
```

完成！您的业务项目的 HTTP 请求现在会自动应用您配置的所有治理规则！

---

### 第六步：查看运维监控

业务项目运行后，可以在管理平台查看运维监控数据。

#### 查看接口日志

接口日志记录了所有经过治理的 HTTP 请求，可用于：
- 排查程序问题
- 分析请求耗时
- 查看请求/响应内容

#### 查看慢接口

慢接口检测会记录响应时间超过阈值的接口，可用于：
- 识别性能瓶颈
- 优化慢接口
- 预防业务影响

#### 查看限流/熔断/重试事件

这些事件记录了治理动作的触发情况：

| 事件类型 | 说明 |
|-----------|------|
| 限流事件 | 哪些接口被限流了，触发了多少次 |
| 熔断事件 | 哪些接口被熔断了，熔断器状态 |
| 重试事件 | 哪些接口触发了重试，最终是否成功 |

---

## 三、外放 API 接口文档

### 1. 项目管理接口

**基础路径：`/api/project`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/page` | 分页查询项目列表 |
| GET | `/list` | 查询所有项目 |
| GET | `/{id}` | 根据 ID 查询项目详情 |
| POST | `/` | 新增项目 |
| PUT | `/` | 更新项目 |
| DELETE | `/{id}` | 删除项目 |

**新增项目请求示例：

```http
POST /api/project
Content-Type: application/json

{
  "projectCode": "order-service",
  "projectName": "订单服务",
  "clientType": "TEMPLATE",
  "serviceIp": "192.168.1.100",
  "servicePort": 8080
}
```

**clientType 可选值：
- `TEMPLATE` - RestTemplate
- `RESTCLIENT` - RestClient
- `WEBCLIENT` - WebClient

---

### 2. 治理规则管理接口

**基础路径：`/api/rule`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/page` | 分页查询规则列表 |
| GET | `/list` | 查询所有规则 |
| GET | `/{id}` | 查询规则详情（含拦截器配置）
| POST | `/` | 新增规则 |
| PUT | `/` | 更新规则 |
| DELETE | `/{id}` | 删除规则（级联删除拦截器配置）
| POST | `/{id}/status` | 启用/禁用规则 |
| GET | `/{id}/interceptors` | 查询规则的拦截器配置 |
| POST | `/{id}/interceptors` | 保存规则的拦截器配置 |
| POST | `/{id}/interceptors/batch` | 批量保存拦截器配置 |

**新增规则请求示例：

```http
POST /api/rule
Content-Type: application/json

{
  "ruleName": "用户接口限流",
  "matchType": "PREFIX",
  "matchValue": "https://api.example.com/user",
  "priority": 100,
  "status": 1
}
```

**配置规则拦截器（批量保存）：

```http
POST /api/rule/1/interceptors/batch
Content-Type: application/json

[
  {
    "interceptorCode": "rate_limit",
    "paramJson": {
      "qps": 100,
      "periodSeconds": 1
    }
  },
  {
    "interceptorCode": "api_log",
    "paramJson": {
      "logRequest": true,
      "logResponse": true
    }
  }
]
```

---

### 3. 拦截器元数据接口

**基础路径：`/api/interceptor`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/list` | 查询所有拦截器元数据 |
| GET | `/group` | 按分类分组查询 |
| GET | `/{id}` | 根据 ID 查询 |
| GET | `/code/{code}` | 根据编码查询 |

**按分类分组查询响应示例：

```json
{
  "流量管控": [
    {
      "interceptorCode": "rate_limit",
      "interceptorName": "请求限流",
      "category": "流量管控",
      "description": "基于 QPS 的接口限流控制"
    }
  ]
}
```

---

### 4. 配置推送接口

**基础路径：`/api/push`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/project/{projectId}` | 向指定项目推送 |
| POST | `/all` | 向所有项目推送 |
| POST | `/batch` | 批量推送 |
| GET | `/history` | 获取推送历史记录 |

---

### 5. 运维监控查询接口

**基础路径：`/api/monitor`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/overview` | 获取运营统计总览 |
| GET | `/api-log/page` | 分页查询接口日志 |
| GET | `/api-log/{id}` | 查询接口日志详情 |
| GET | `/slow-api/page` | 分页查询慢接口列表 |
| GET | `/rate-limit/page` | 分页查询限流事件 |
| GET | `/circuit-breaker/page` | 分页查询熔断事件 |
| GET | `/retry/page` | 分页查询重试事件 |

**统计总览响应示例：

```json
{
  "apiLogCount": 156,
  "slowApiCount": 12,
  "rateLimitCount": 3,
  "circuitBreakerCount": 0,
  "retryCount": 8
}
```

---

### 6. 运维监控数据上报接口（业务项目调用）

**基础路径：`/api/metrics`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api-log` | 上报接口日志 |
| POST | `/slow-api` | 上报慢接口 |
| POST | `/rate-limit` | 上报限流事件 |
| POST | `/circuit-breaker` | 上报熔断事件 |
| POST | `/retry` | 上报重试事件 |

---

## 四、技术架构说明

### 整体架构：

```
┌─────────────────────────────────────────────────────────────┐
│           Admin 管控后台（Spring Boot 3 + JDK 21）    │
│                                                          │
│  REST API（Knife4j OpenAPI 3）                         │
│  ├── /api/project/*        项目管理                  │
│  ├── /api/rule/*           规则管理                    │
│  ├── /api/interceptor/*    拦截器元数据                │
│  ├── /api/push/*           配置推送                    │
│  ├── /api/monitor/*        运维监控查询                 │
│  └── /api/metrics/*      运维监控数据上报         │
│                                                          │
│  定时任务（TimingPushTask）每小时全量推送                │
│                                                          │
│  数据层（MyBatis-Plus + MySQL 8.0）                     │
└──────────────────────────┬───────────────────────────────┘
                           │ HTTP POST（配置推送）
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    业务项目（引入 Starter）                      │
│                                                          │
│  配置接收接口（自动注册）                                │
│  POST /api/governance/config/push                    │
│           ↓                                              │
│  RuleCacheManager（内存缓存）                               │
│           ↓                                              │
│  HTTP 客户端拦截                                          │
│  ├── RestTemplate: ClientHttpRequestInterceptor        │
│  ├── RestClient:   ClientHttpRequestInterceptor        │
│  └── WebClient:    ExchangeFilterFunction            │
│           ↓                                              │
│  内置拦截器链（12个）                                     │
│  ├── 流量管控: 限流、熔断、重试（Resilience4j）         │
│  ├── 安全加密: 签名、加密（JDK Crypto）              │
│  ├── 观测监控: 日志、脱敏、慢接口                         │
│  ├── 路由灰度: 动态路由、灰度发布                         │
│  └── 混沌工程: 故障注入、Mock 降级                       │
└─────────────────────────────────────────────────────────────┘
```

### 技术栈

#### 后端技术栈：

| 组件名称 | 版本 | 用途 |
|---------|------|------|
| **Spring Boot** | 3.2.5 | 核心框架 |
| **MyBatis-Plus** | 3.5.5 | ORM 框架 |
| **Resilience4j** | 2.2.0 | 容错组件（限流、熔断、重试） |
| **Knife4j** | 4.5.0 | API 文档 |
| **FastJSON2** | 2.0.43 | JSON 序列化 |
| **Lombok** | 1.18.30 | 代码简化 |
| **MySQL** | 8.0 | 数据库 |

#### 前端技术栈：

| 组件名称 | 版本 | 用途 |
|---------|------|------|
| **Vue 3** | 3.4+ | 前端框架 |
| **Element Plus** | 2.7+ | UI 组件库 |
| **Axios** | 1.6+ | HTTP 客户端 |
| **Nginx** | 最新 | Web 服务器 |

---

## 五、常用命令

```bash
# 启动服务
docker compose up -d

# 查看运行状态
docker compose ps

# 查看 Admin 日志
docker compose logs -f governance-admin

# 查看 MySQL 日志
docker compose logs -f mysql

# 停止服务（保留数据）
docker compose down

# 重新构建镜像（代码修改后）
docker compose build --no-cache
docker compose up -d
```

---

## 六、完整示例

假设您有一个订单服务，想要：
1. 对用户接口限流（QPS=100）
2. 对支付接口熔断降级
3. 记录所有接口日志

### 配置步骤：

**步骤 1**：创建规则
- 规则名称：用户接口限流
- 匹配模式：前缀匹配
- 匹配值：`https://api.example.com/user`

**步骤 2**：配置拦截器
- 添加「请求限流」拦截器
- 参数：`qps=100, periodSeconds=1, blockEnabled=true, blockStatusCode=429`

**步骤 3**：再创建一条规则
- 规则名称：支付接口熔断
- 匹配模式：前缀匹配
- 匹配值：`https://api.example.com/payment`

**步骤 4**：配置拦截器
- 添加「熔断降级」拦截器
- 参数：`failureThreshold=50, waitDuration=30, fallbackEnabled=true`

**步骤 5**：再创建一条规则
- 规则名称：全链路日志
- 匹配模式：前缀匹配
- 匹配值：`https://api.example.com/`

**步骤 6**：配置拦截器
- 添加「接口日志」拦截器
- 参数：`logRequest=true, logResponse=true`

**步骤 7**：注册项目
- 项目编码：`order-service`
- 客户端类型：`RestTemplate`
- IP：`192.168.1.100`
- 端口：`8080`

**步骤 8**：推送配置
- 选择 `order-service` 项目
- 点击「推送配置」

完成！业务项目的 HTTP 请求现在会自动：
- 用户接口 QPS 超过 100 时返回 429
- 支付接口错误率超过 50% 时熔断并返回降级内容
- 所有请求/响应都会被记录到管理平台

---

## 七、FAQ

**Q: 12 个拦截器是否开箱即用？

A: 是的，12 个拦截器全部已实现并在 `governance-interceptor` 模块中。业务项目只需引入 Starter，拦截器会通过 Spring Boot 自动配置注入。

**Q: 配置推送失败怎么办？

A: 推送失败会记录到推送历史表，可通过「配置推送」页面查看，可重试推送。业务项目健康状态也会更新为异常。

**Q: 业务项目需要自己存储数据吗？

A: 不需要。业务项目只需：
1. 接收管理平台推送的配置（内存缓存）
2. 上报运维监控数据到管理平台

所有数据（配置、日志、事件）都由管理平台统一存储。

**Q: 接口日志数据量太大怎么办？

A: 接口日志支持以下优化：
1. 可以在「接口日志」拦截器中设置 `maxBodyLength` 限制请求/响应体大小
2. 可以设置 `logRequest=false` 或 `logResponse=false` 关闭部分日志
3. 管理平台数据库建议定期清理历史数据

**Q: 自定义拦截器如何开发？

A: 实现 `HttpGovernanceInterceptor` 接口，注册为 Spring Bean，然后在 Admin 数据库 `governance_interceptor_meta` 表添加元数据即可。

---

## 八、版本信息

- **Spring Boot**: 3.2.5
- **Java**: 21
- **MyBatis-Plus**: 3.5.5
- **Resilience4j**: 2.2.0
- **Knife4j**: 4.5.0
- **FastJSON2**: 2.0.43
- **Lombok**: 1.18.30

---

🛡️ **智盾** - 让您的 HTTP 请求更稳定、更安全、更可控！