diff --git a/script/sentinel/README.md b/script/sentinel/README.md new file mode 100644 index 0000000..b9cc191 --- /dev/null +++ b/script/sentinel/README.md @@ -0,0 +1,39 @@ +# 限流熔断（可选接入） + +基于 [Sentinel](https://sentinelguard.io/zh-cn/docs/introduction.html) 1.8.10 的可选接入材料，演示接口（资源）级别的限流、熔断。项目默认**不启用**：本目录不是 Maven 模块，不参与默认构建，主工程的依赖、配置、业务代码都不受影响。 + +项目的 `yudao-spring-boot-starter-protection` 组件本身**不包含** Sentinel，它提供的是基于 Redis（Redisson）的 `@RateLimiter` 请求限流、`@Idempotent` 幂等、Lock4j 分布式锁，接入本材料后保持不变，可以和 Sentinel 同时使用。 + +接入后，只有添加了 `@SentinelResource` 注解、并且配置了规则的资源，才会被限流、熔断，其它接口不受影响。示例的规则从 classpath 中的 JSON 文件加载，只保存在 JVM 内存中；单机阈值，多个实例不共享计数。 + +接入步骤、验证方式及使用限制，请阅读项目文档《限流熔断》，本文只列出材料及分支适用范围： + +- 单体项目 ruoyi-vue-pro： +- 微服务项目 yudao-cloud： + +## 1. 材料清单 + +| 文件 | 说明 | 目标位置 | +| --- | --- | --- | +| `dependencies.xml` | Maven 依赖片段：第 1 段 Sentinel 核心及注解切面（必须），第 2 段与 Dashboard 通信的模块（可选） | `yudao-module-infra/pom.xml` | +| `src/main/resources/sentinel/demo-flow-rules.json` | 限流规则：资源 `demo-sentinel-flow`，QPS 2 | `yudao-module-infra/src/main/resources/sentinel/` | +| `src/main/resources/sentinel/demo-degrade-rules.json` | 熔断规则：资源 `demo-sentinel-degrade`，慢调用比例 | `yudao-module-infra/src/main/resources/sentinel/` | +| `src/main/java/.../infra/sentineldemo/DemoSentinelConfiguration.java` | 注册 `SentinelResourceAspect` 切面，启动时加载上面两个规则文件 | `yudao-module-infra/src/main/java` 的同名包 | +| `src/main/java/.../infra/sentineldemo/controller/admin/DemoSentinelController.java` | 示例接口 `/admin-api/infra/sentinel-demo/flow`、`/admin-api/infra/sentinel-demo/degrade`，及被阻断时的 `blockHandler` | `yudao-module-infra/src/main/java` 的同名包 | + +示例的包名在 `yudao.info.base-package`（`cn.iocoder.yudao`）下，才能被 Spring 扫描到；Controller 放在 `controller.admin` 子包下，才会添加 `/admin-api` 前缀。规则 JSON 是严格的 JSON，不能包含注释，字段说明见项目文档。 + +## 2. 分支适用范围 + +目前只有 `master-jdk17` 分支提供本目录的材料；`master`、`master-jdk25` 分支请先从 `master-jdk17` 分支的 `script/sentinel/` 获取，同步到对应分支后，也可以直接从当前分支获取。 + +本目录的材料按 `master`（JDK 8 + Spring Boot 2.7.18）、`master-jdk17`（Spring Boot 3.5.15）、`master-jdk25`（Spring Boot 4.1.2）三个分支的 API 编写，接入步骤相同，兼容要点如下： + +| 要点 | 说明 | +| --- | --- | +| Sentinel 坐标 | 显式指定 `com.alibaba.csp:*:1.8.10`，三个依赖的版本保持一致。单体项目没有 Spring Cloud Alibaba 的 BOM，不要为了 Sentinel 引入 Spring Cloud 相关的 BOM 或 starter | +| JDK 8 | Sentinel 1.8.10 的常规类按 Java 8 字节码发布（仅 `module-info.class` 面向 Java 9+），`master` 分支可以使用 | +| AOP | `@SentinelResource` 依赖 Spring AOP，项目的 Security 组件已经引入（`master`、`master-jdk17` 是 `spring-boot-starter-aop`，`master-jdk25` 是 `spring-boot-starter-aspectj`），不需要额外添加 | +| 示例代码 | 只使用 Java 8 语法，不引用 `javax`、`jakarta` 包；规则通过项目的 `JsonUtils` 解析，不区分 Jackson 2、Jackson 3，三个分支无需修改 | +| Web 适配模块 | 示例没有使用自动统计所有 URL 的 Web 适配模块：它在 `master` 分支是 `sentinel-spring-webmvc-adapter`（`javax`），`master-jdk17` 分支是 `sentinel-spring-webmvc-v6x-adapter`（`jakarta`），两者的包名、`BlockExceptionHandler` 方法签名都不同，需要按分支自行接入 | +| `master-jdk25` | Sentinel 官方没有声明对 Spring Boot 4、Spring Framework 7 的适配，接入后以实际的启动、请求验证为准 | diff --git a/script/sentinel/dependencies.xml b/script/sentinel/dependencies.xml new file mode 100644 index 0000000..d80da7b --- /dev/null +++ b/script/sentinel/dependencies.xml @@ -0,0 +1,43 @@ + + + + + + + + com.alibaba.csp + sentinel-core + 1.8.10 + + + com.alibaba.csp + sentinel-annotation-aspectj + 1.8.10 + + + + + + com.alibaba.csp + sentinel-transport-simple-http + 1.8.10 + + + diff --git a/script/sentinel/src/main/java/cn/iocoder/yudao/module/infra/sentineldemo/DemoSentinelConfiguration.java b/script/sentinel/src/main/java/cn/iocoder/yudao/module/infra/sentineldemo/DemoSentinelConfiguration.java new file mode 100644 index 0000000..0a97169 --- /dev/null +++ b/script/sentinel/src/main/java/cn/iocoder/yudao/module/infra/sentineldemo/DemoSentinelConfiguration.java @@ -0,0 +1,65 @@ +package cn.iocoder.yudao.module.infra.sentineldemo; + +import cn.hutool.core.io.resource.ResourceUtil; +import cn.iocoder.yudao.framework.common.util.json.JsonUtils; +import com.alibaba.csp.sentinel.annotation.aspectj.SentinelResourceAspect; +import com.alibaba.csp.sentinel.slots.block.degrade.DegradeRule; +import com.alibaba.csp.sentinel.slots.block.degrade.DegradeRuleManager; +import com.alibaba.csp.sentinel.slots.block.flow.FlowRule; +import com.alibaba.csp.sentinel.slots.block.flow.FlowRuleManager; +import lombok.extern.slf4j.Slf4j; +import org.springframework.beans.factory.SmartInitializingSingleton; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; + +import java.util.List; + +/** + * Sentinel 限流熔断示例的配置类 + * + * 1. 注册 {@link SentinelResourceAspect} 切面，让 @SentinelResource 注解生效。单体项目没有引入 Spring Cloud Alibaba，需要自己注册 + * 2. 启动时，从 classpath 的 sentinel 目录加载示例的限流、熔断规则 + * + * @author 芋道源码 + */ +@Configuration(value = "demoSentinelConfiguration", proxyBeanMethods = false) +@Slf4j +public class DemoSentinelConfiguration { + + /** + * 限流规则的 JSON 文件，资源名与 DemoSentinelController 中 @SentinelResource 的 value 一致 + */ + private static final String FLOW_RULES_PATH = "sentinel/demo-flow-rules.json"; + /** + * 熔断规则的 JSON 文件 + */ + private static final String DEGRADE_RULES_PATH = "sentinel/demo-degrade-rules.json"; + + @Bean + public SentinelResourceAspect sentinelResourceAspect() { + return new SentinelResourceAspect(); + } + + /** + * 加载示例的规则：在所有单例 Bean 初始化之后、Web 服务器开始接收请求之前执行 + * + * 注意，规则只保存在当前 JVM 的内存中： + * 1. loadRules 会替换同一类型的全部规则，自己的业务有其它规则来源时，需要合并后再加载 + * 2. 通过 Sentinel Dashboard 修改的规则，重启后会恢复成 JSON 文件中的规则 + */ + @Bean + public SmartInitializingSingleton demoSentinelRuleLoader() { + return () -> { + FlowRuleManager.loadRules(parseRules(FLOW_RULES_PATH, FlowRule.class)); + DegradeRuleManager.loadRules(parseRules(DEGRADE_RULES_PATH, DegradeRule.class)); + // 打印实际生效的规则数：不合法的规则（例如说 count 小于 0）会被 Sentinel 忽略，此时数量会少于 JSON 文件中的 + log.info("[demoSentinelRuleLoader][加载 Sentinel 规则完成，限流规则({}) 条，熔断规则({}) 条]", + FlowRuleManager.getRules().size(), DegradeRuleManager.getRules().size()); + }; + } + + private static List parseRules(String path, Class clazz) { + return JsonUtils.parseArray(ResourceUtil.readUtf8Str(path), clazz); + } + +} diff --git a/script/sentinel/src/main/java/cn/iocoder/yudao/module/infra/sentineldemo/controller/admin/DemoSentinelController.java b/script/sentinel/src/main/java/cn/iocoder/yudao/module/infra/sentineldemo/controller/admin/DemoSentinelController.java new file mode 100644 index 0000000..c1da125 --- /dev/null +++ b/script/sentinel/src/main/java/cn/iocoder/yudao/module/infra/sentineldemo/controller/admin/DemoSentinelController.java @@ -0,0 +1,76 @@ +package cn.iocoder.yudao.module.infra.sentineldemo.controller.admin; + +import cn.hutool.core.thread.ThreadUtil; +import cn.iocoder.yudao.framework.common.exception.ServiceException; +import cn.iocoder.yudao.framework.common.pojo.CommonResult; +import com.alibaba.csp.sentinel.annotation.SentinelResource; +import com.alibaba.csp.sentinel.slots.block.BlockException; +import com.alibaba.csp.sentinel.slots.block.degrade.DegradeException; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.Parameter; +import io.swagger.v3.oas.annotations.tags.Tag; +import org.springframework.http.HttpStatus; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RequestParam; +import org.springframework.web.bind.annotation.RestController; + +import static cn.iocoder.yudao.framework.common.exception.enums.GlobalErrorCodeConstants.TOO_MANY_REQUESTS; +import static cn.iocoder.yudao.framework.common.pojo.CommonResult.success; + +/** + * 管理后台 - Sentinel 限流熔断示例 + * + * 1. 每个接口通过 @SentinelResource 定义一个资源，资源名与 sentinel 目录下 JSON 规则中的 resource 一一对应 + * 2. 被限流、熔断时，调用同一个类中的 blockHandler 方法，返回 CommonResult 错误码，与 @RateLimiter 被限流时的返回格式一致 + * + * 放在 controller.admin 包下，才会和项目其它管理后台接口一样，添加 /admin-api 前缀 + * + * @author 芋道源码 + */ +@Tag(name = "管理后台 - Sentinel 示例") +@RestController +@RequestMapping("/infra/sentinel-demo") +public class DemoSentinelController { + + @GetMapping("/flow") + @Operation(summary = "限流示例", description = "资源 demo-sentinel-flow，每秒最多通过 2 个请求") + @SentinelResource(value = "demo-sentinel-flow", blockHandler = "flowBlockHandler") + public CommonResult flow() { + return success("flow"); + } + + @GetMapping("/degrade") + @Operation(summary = "熔断示例", description = "资源 demo-sentinel-degrade，慢调用比例超过阈值时熔断 10 秒") + @Parameter(name = "slow", description = "是否模拟慢调用", example = "false") + @SentinelResource(value = "demo-sentinel-degrade", blockHandler = "degradeBlockHandler", + exceptionsToIgnore = ServiceException.class) // 业务异常不计入异常比例、异常数的熔断统计，由全局异常处理器照常返回错误码 + public CommonResult degrade(@RequestParam(value = "slow", defaultValue = "false") Boolean slow) { + if (Boolean.TRUE.equals(slow)) { + ThreadUtil.sleep(500); // 模拟慢调用：超过熔断规则中 200 毫秒的最大响应时间 + return success("slow"); + } + return success("ok"); + } + + // ========== blockHandler：被 Sentinel 阻断时调用。参数为原方法的参数 + BlockException，返回值类型与原方法相同 ========== + + public CommonResult flowBlockHandler(BlockException ex) { + return buildBlockResult(ex); + } + + public CommonResult degradeBlockHandler(Boolean slow, BlockException ex) { + return buildBlockResult(ex); + } + + /** + * 将 BlockException 转换成 CommonResult：熔断返回 503，限流等其它阻断返回 429 + */ + private static CommonResult buildBlockResult(BlockException ex) { + if (ex instanceof DegradeException) { + return CommonResult.error(HttpStatus.SERVICE_UNAVAILABLE.value(), "服务暂时不可用，请稍后重试"); + } + return CommonResult.error(TOO_MANY_REQUESTS); + } + +} diff --git a/script/sentinel/src/main/resources/sentinel/demo-degrade-rules.json b/script/sentinel/src/main/resources/sentinel/demo-degrade-rules.json new file mode 100644 index 0000000..c8814a7 --- /dev/null +++ b/script/sentinel/src/main/resources/sentinel/demo-degrade-rules.json @@ -0,0 +1,11 @@ +[ + { + "resource": "demo-sentinel-degrade", + "grade": 0, + "count": 200, + "slowRatioThreshold": 0.5, + "minRequestAmount": 3, + "statIntervalMs": 10000, + "timeWindow": 10 + } +] diff --git a/script/sentinel/src/main/resources/sentinel/demo-flow-rules.json b/script/sentinel/src/main/resources/sentinel/demo-flow-rules.json new file mode 100644 index 0000000..cb4c475 --- /dev/null +++ b/script/sentinel/src/main/resources/sentinel/demo-flow-rules.json @@ -0,0 +1,11 @@ +[ + { + "resource": "demo-sentinel-flow", + "limitApp": "default", + "grade": 1, + "count": 2, + "strategy": 0, + "controlBehavior": 0, + "clusterMode": false + } +]