# Resilience4j-Sentinel

**Repository Path**: KlysNcheJs/resilience4j-sentinel

## Basic Information

- **Project Name**: Resilience4j-Sentinel
- **Description**: 熔断限流技术
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-06-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Resilience4j & Sentinel 熔断限流学习项目

> Spring Boot 3 多模块项目，通过三个独立模块对比学习 **Resilience4j** 和 **Alibaba Sentinel** 的熔断、限流、隔离舱能力。

---

## 项目概览

| 模块 | 端口 | 框架 | 规则存储 | 说明 |
|------|------|------|----------|------|
| `resilience4j` | 8081 | Resilience4j 2.4.0 | JVM 内存 (YAML 配置) | 演示 5 种保护模式：熔断器、重试、限流、隔离舱、超时 |
| `sentinel-standalone` | 8082 | Sentinel 1.8.8 | JVM 内存 (编程式初始化) | 单机模式，`@PostConstruct` 加载规则 |
| `sentinel-distributed` | 8083 | Sentinel 1.8.8 + Nacos | Nacos 配置中心 | 分布式模式，规则从 Nacos 动态拉取 |

**同一个 Sentinel Dashboard 可同时管理 standalone 和 distributed 两个应用。**

---

## 技术栈

| 组件 | 版本 |
|------|------|
| JDK | 17+ |
| Spring Boot | 3.3.5 |
| Spring Cloud | 2023.0.3 |
| Spring Cloud Alibaba | 2023.0.1.2 |
| Resilience4j | 2.4.0 (`resilience4j-spring-boot3`) |
| Sentinel | 1.8.8 (通过 SCA BOM 引入) |
| Nacos Server | 2.4.x (仅分布式模块需要) |
| Sentinel Dashboard | 1.8.8 (独立 JAR) |

---

## 模块结构

```
resilience4j-sentinel/
├── pom.xml                                       # 父 POM
├── resilience4j/                                 # 模块 1: Resilience4j
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/example/resilience4j/
│       │   ├── Resilience4jApplication.java      # 启动类
│       │   ├── config/Resilience4jConfig.java     # 熔断器事件监听
│       │   ├── service/DownstreamService.java     # 模拟下游服务 (可控失败率/延迟)
│       │   └── controller/DemoController.java     # 5 种模式 + admin 控制端点
│       └── resources/application.yml              # 所有 resilience4j 实例配置
├── sentinel-standalone/                          # 模块 2: Sentinel 单机
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/example/sentinel/standalone/
│       │   ├── SentinelStandaloneApplication.java # 启动类
│       │   ├── config/SentinelConfig.java         # 编程式规则初始化 (Flow/Degrade/System)
│       │   ├── service/ProtectedService.java      # @SentinelResource (blockHandler + fallback)
│       │   └── controller/DemoController.java     # 业务端点
│       └── resources/application.yml              # Dashboard 连接 + eager 模式
└── sentinel-distributed/                         # 模块 3: Sentinel 分布式
    ├── pom.xml
    └── src/main/
        ├── java/com/example/sentinel/distributed/
        │   ├── SentinelDistributedApplication.java # 启动类
        │   ├── config/SentinelNacosConfig.java     # 全局 BlockException JSON 处理
        │   ├── service/ProtectedService.java       # @SentinelResource (Nacos 规则)
        │   └── controller/DemoController.java      # 业务端点
        └── resources/application.yml               # Nacos 数据源 + Sentinel transport
```

---

## 各模块详解

### 1. resilience4j 模块 (端口 8081)

**五种保护模式**：

| 端点 | 注解 | 配置实例 | 行为 |
|------|------|----------|------|
| `GET /api/circuit-breaker` | `@CircuitBreaker` + `@Retry` | backendA | 滑动窗口 10 次，失败率 50% 熔断，重试 3 次 |
| `GET /api/rate-limiter` | `@RateLimiter` | backendB | 每秒最多 5 次请求 |
| `GET /api/bulkhead` | `@Bulkhead` (SEMAPHORE) | backendC | 最大并发 3 个请求 |
| `GET /api/time-limiter` | `@TimeLimiter` + `@CircuitBreaker` | backendD | 500ms 超时 |

**动态控制端点**：

| 端点 | 说明 |
|------|------|
| `POST /api/admin/simulate` | 设置失败率和延迟，触发熔断/超时场景 |
| `POST /api/admin/reset` | 重置为正常状态 |

**Actuator 端点**：`/actuator/circuitbreakers`、`/actuator/circuitbreakerevents`、`/actuator/prometheus`

### 2. sentinel-standalone 模块 (端口 8082)

**编程式初始化规则**（`SentinelConfig.java` 中 `@PostConstruct`）：

| Resource | 规则类型 | 阈值 |
|----------|----------|------|
| `queryOrder` | FlowRule (QPS) | 10 QPS |
| `getUserInfo` | FlowRule (QPS) | 5 QPS |
| `queryOrder` | DegradeRule (异常比例) | 50%，10s 窗口 |
| 全局 | SystemRule (系统负载) | load 5.0 / CPU 80% |

**端点**：

| 端点 | 说明 |
|------|------|
| `GET /api/order/{orderId}` | 查询订单 (受 FlowRule + DegradeRule 保护) |
| `GET /api/user/{userId}` | 查询用户 (受 FlowRule 保护，userId=ERROR 触发 fallback) |
| `GET /api/system/health` | 系统健康检查 (受 SystemRule 保护) |

### 3. sentinel-distributed 模块 (端口 8083)

**规则来自 Nacos**（无需编程式初始化），应用启动后自动从 Nacos 拉取并监听变更：

| Nacos Data ID | Group | 规则类型 |
|---------------|-------|----------|
| `sentinel-distributed-demo-flow-rules` | SENTINEL_GROUP | FlowRule |
| `sentinel-distributed-demo-degrade-rules` | SENTINEL_GROUP | DegradeRule |
| `sentinel-distributed-demo-system-rules` | SENTINEL_GROUP | SystemRule |

端点与 standalone 模块一致。

---

## 环境准备

### 1. 安装 JDK 17+

### 2. 下载 Sentinel Dashboard

从 [GitHub Releases](https://github.com/alibaba/Sentinel/releases) 下载 `sentinel-dashboard-1.8.8.jar`。

### 3. 安装 Nacos (仅分布式模块需要)

从 [Nacos Releases](https://github.com/alibaba/nacos/releases) 下载，单机模式启动：

```bash
cd nacos/bin
# Linux/Mac
sh startup.sh -m standalone
# Windows
startup.cmd -m standalone
```

---

## 启动步骤

```bash
# 1. 启动 Sentinel Dashboard
java -Dserver.port=8080 -Dcsp.sentinel.dashboard.server=localhost:8080 -jar sentinel-dashboard-1.8.8.jar

# 2. 启动 Nacos (仅分布式模块需要，默认端口 8848)

# 3. 编译项目
mvn clean install -DskipTests

# 4. 分别启动三个模块 (各开一个终端)
cd resilience4j       && mvn spring-boot:run    # 8081
cd sentinel-standalone && mvn spring-boot:run   # 8082
cd sentinel-distributed && mvn spring-boot:run  # 8083
```

**端口分配**：

| 服务 | 端口 |
|------|------|
| Sentinel Dashboard | 8080 |
| resilience4j | 8081 |
| sentinel-standalone | 8082 |
| sentinel-distributed | 8083 |
| Nacos | 8848 |
| Sentinel transport (单机) | 8719 |
| Sentinel transport (分布式) | 8720 |

---

## 验证测试

### Resilience4j 熔断器测试

```bash
# 正常调用
curl http://localhost:8081/api/circuit-breaker
# 输出: success from downstream

# 设置 80% 失败率 + 600ms 延迟 (触发熔断和超时)
curl -X POST http://localhost:8081/api/admin/simulate \
  -H "Content-Type: application/json" \
  -d '{"failureRate": 0.8, "delay": 600}'

# 连续请求，观察熔断
for i in {1..20}; do curl -s http://localhost:8081/api/circuit-breaker; echo; done
# 输出: Blocked: circuitBreaker - CallNotPermittedException: ...

# 查看熔断器状态
curl -s http://localhost:8081/actuator/circuitbreakers | python -m json.tool

# Prometheus 指标
curl -s http://localhost:8081/actuator/prometheus | grep resilience4j

# 重置
curl -X POST http://localhost:8081/api/admin/reset
```

### Sentinel 单机限流测试

```bash
# 正常调用
curl http://localhost:8082/api/order/ORD001
# 输出: Order{ORD001, status=PAID, amount=299.00, items=3}

# 超过 10 QPS 触发限流
for i in {1..20}; do curl -s http://localhost:8082/api/order/ORD001; echo; done
# 超额请求输出: Blocked: queryOrder - FlowException (rule: ...)

# 用户查询 (5 QPS 限流)
for i in {1..10}; do curl -s http://localhost:8082/api/user/USR001; echo; done

# 触发 fallback (userId=ERROR 抛出业务异常)
curl http://localhost:8082/api/user/ERROR
# 输出: Fallback: getUserInfo - Simulated business exception
```

### Sentinel 分布式测试

```bash
# 先在 Nacos 控制台 (http://localhost:8848/nacos) 创建规则配置:
#   Data ID: sentinel-distributed-demo-flow-rules
#   Group:   SENTINEL_GROUP
#   内容 (JSON):
#   [{"resource":"queryOrder","grade":1,"count":10,"strategy":0,"controlBehavior":0,"clusterMode":false}]

# 然后测试
curl http://localhost:8083/api/order/ORD001
for i in {1..20}; do curl -s http://localhost:8083/api/order/ORD001; echo; done

# 修改 Nacos 中的规则后，限流行为实时生效
```

### Sentinel Dashboard

打开 http://localhost:8080 （默认账号 `sentinel` / `sentinel`），左侧菜单可见 `sentinel-standalone-demo` 和 `sentinel-distributed-demo` 两个应用，可查看实时监控、规则管理和簇点链路。

---

## 关键设计对比

| 特性 | Resilience4j | Sentinel |
|------|-------------|----------|
| 配置方式 | YAML 声明式 | 编程式 / Nacos 动态推送 |
| 熔断策略 | 滑动窗口 + 失败率/慢调用 | 异常比例 / 异常数 / 慢调用比例 |
| 限流算法 | 令牌桶 (固定速率) | QPS / 线程数 / 集群限流 |
| 隔离舱 | 信号量 / 线程池 | 仅信号量 |
| 超时控制 | TimeLimiter | 无独立超时 (通过 RT 降级间接控制) |
| 规则持久化 | 不支持 (需自行实现) | 原生支持 Nacos/Apollo/Zookeeper |
| 监控面板 | Prometheus + Grafana | Sentinel Dashboard |
| 适用场景 | Spring 生态 / 微服务 | 阿里生态 / 高并发场景 |

---

## 已知注意事项

1. **Sentinel Dashboard 不在 Maven Central**：需要从 GitHub Releases 手动下载 JAR
2. **Nacos 2.2+ 默认开启认证**：分布式模块的 `application.yml` 中需配置 `username` / `password`
3. **sentinel-datasource-nacos 版本兼容**：SCA 2023.0.1.2 + Nacos 2.4.x 较稳定，避免使用 2.5.x
4. **Sentinel transport 端口冲突**：单机和分布式模块使用不同的 transport 端口 (8719 / 8720)