kk
350 lines
10 KiB
Markdown
350 lines
10 KiB
Markdown
# Blade LiteRule 规则引擎
|
|
|
|
BladeX框架的轻量级规则引擎，提供简单易用的规则执行和编排能力。
|
|
|
|
## 特性
|
|
|
|
- 支持顺序规则、分支规则和并行规则三种执行模式
|
|
- 提供流式API用于构建规则链
|
|
- 支持同步和异步执行
|
|
- 完整的生命周期管理和监控
|
|
- 基于Spring管理规则实例
|
|
- 线程安全的上下文管理
|
|
- 规则链缓存和预加载
|
|
- 循环依赖检测
|
|
|
|
## 快速开始
|
|
|
|
### 1. 添加依赖
|
|
|
|
```xml
|
|
<dependency>
|
|
<groupId>org.springblade</groupId>
|
|
<artifactId>blade-starter-literule</artifactId>
|
|
<version>${blade.tool.version}</version>
|
|
</dependency>
|
|
```
|
|
|
|
### 2. 定义规则上下文
|
|
|
|
```java
|
|
import org.springblade.core.literule.core.RuleContextComponent;
|
|
|
|
@Data
|
|
@Builder
|
|
@NoArgsConstructor
|
|
@AllArgsConstructor
|
|
public class OrderContext extends RuleContextComponent {
|
|
private String orderId;
|
|
private BigDecimal amount;
|
|
private String paymentType;
|
|
private String status;
|
|
private Address shippingAddress;
|
|
// 其他业务字段...
|
|
}
|
|
```
|
|
|
|
### 3. 实现普通规则
|
|
|
|
```java
|
|
import org.springblade.core.literule.annotation.LiteRuleComponent;
|
|
|
|
@Slf4j
|
|
@LiteRuleComponent("orderValidateRule")
|
|
public class OrderValidateRule extends RuleComponent {
|
|
@Override
|
|
protected void process() throws Exception {
|
|
OrderContext context = getContextBean(OrderContext.class);
|
|
|
|
// 执行业务逻辑
|
|
if (StringUtils.isEmpty(context.getOrderId())) {
|
|
context.addError("订单ID不能为空");
|
|
return;
|
|
}
|
|
|
|
if (context.getAmount() == null || context.getAmount().compareTo(BigDecimal.ZERO) <= 0) {
|
|
context.addError("订单金额无效");
|
|
return;
|
|
}
|
|
|
|
log.info("[规则1] 订单校验通过：{}", context.getOrderId());
|
|
}
|
|
}
|
|
```
|
|
|
|
### 4. 实现分支规则
|
|
|
|
```java
|
|
import org.springblade.core.literule.annotation.LiteRuleComponent;
|
|
|
|
@Slf4j
|
|
@LiteRuleComponent("paymentRouteRule")
|
|
public class PaymentRouteRule extends SwitchRuleComponent {
|
|
@Override
|
|
protected List<String> process() throws Exception {
|
|
OrderContext context = getContextBean(OrderContext.class);
|
|
String paymentType = context.getPaymentType();
|
|
|
|
log.info("[规则3] 支付路由选择：{}", paymentType);
|
|
|
|
// 根据支付类型返回不同的规则ID
|
|
if ("ALIPAY".equals(paymentType)) {
|
|
return Collections.singletonList("alipayRule");
|
|
} else if ("WECHAT".equals(paymentType)) {
|
|
return Collections.singletonList("wechatPayRule");
|
|
} else if ("BANK".equals(paymentType)) {
|
|
return Collections.singletonList("bankPayRule");
|
|
} else {
|
|
context.addError("不支持的支付方式：" + paymentType);
|
|
return Collections.emptyList();
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### 5. 构建规则链
|
|
|
|
```java
|
|
@EngineComponent("orderChain")
|
|
public class OrderRuleBuilder implements RuleBuilder {
|
|
@Override
|
|
public RuleChain build() {
|
|
// 创建支付处理分支规则
|
|
RuleChain paymentRule = LiteRule.SWITCH("paymentRouteRule")
|
|
.TO("alipayRule", "wechatPayRule", "bankPayRule")
|
|
.build();
|
|
|
|
// 创建完整规则链
|
|
return LiteRule.THEN("orderValidateRule", "orderAmountRule")
|
|
.THEN(paymentRule)
|
|
.build();
|
|
}
|
|
}
|
|
```
|
|
|
|
### 6. 执行规则链
|
|
|
|
```java
|
|
import org.springblade.core.literule.provider.LiteRuleResponse;
|
|
|
|
@Autowired
|
|
private RuleEngineExecutor ruleEngine;
|
|
|
|
public void processOrder(OrderRequest request) {
|
|
// 构建上下文
|
|
OrderContext context = OrderContext.builder()
|
|
.orderId(request.getOrderId())
|
|
.amount(request.getAmount())
|
|
.paymentType(request.getPaymentType())
|
|
.shippingAddress(request.getAddress())
|
|
.build();
|
|
|
|
// 构建配置
|
|
RuleConfig config = RuleConfig.builder()
|
|
.enableTimeMonitor(true)
|
|
.printExecutionTime(true)
|
|
.enableLogging(true)
|
|
.build();
|
|
|
|
// 执行规则链
|
|
LiteRuleResponse<OrderContext> response = ruleEngine.execute(
|
|
"orderChain",
|
|
context,
|
|
config
|
|
);
|
|
|
|
// 处理响应
|
|
if (response.isSuccess()) {
|
|
log.info("规则执行成功，耗时: {}ms", response.getExecutionTime());
|
|
} else {
|
|
log.error("规则执行失败: {}", response.getMessage());
|
|
// 获取详细错误信息
|
|
context.getErrorMessages().forEach(error -> log.error("错误: {}", error));
|
|
}
|
|
}
|
|
```
|
|
|
|
### 7. 异步执行规则链
|
|
|
|
```java
|
|
@Autowired
|
|
private RuleEngineExecutor ruleEngine;
|
|
|
|
@Autowired
|
|
@Qualifier("ruleExecutorThreadPool")
|
|
private ThreadPoolExecutor threadPool;
|
|
|
|
public CompletableFuture<LiteRuleResponse<OrderContext>> processOrderAsync(OrderRequest request) {
|
|
// 构建上下文
|
|
OrderContext context = OrderContext.builder()
|
|
.orderId(request.getOrderId())
|
|
.amount(request.getAmount())
|
|
.paymentType(request.getPaymentType())
|
|
.build();
|
|
|
|
// 异步执行规则链
|
|
return ruleEngine.executeAsync(
|
|
"orderChain",
|
|
context,
|
|
threadPool
|
|
).thenApply(response -> {
|
|
if (response.isSuccess()) {
|
|
log.info("异步规则执行成功，耗时: {}ms", response.getExecutionTime());
|
|
} else {
|
|
log.error("异步规则执行失败: {}", response.getMessage());
|
|
}
|
|
return response;
|
|
});
|
|
}
|
|
```
|
|
|
|
## 核心概念
|
|
|
|
### 规则(Rule)
|
|
|
|
规则是业务逻辑的最小执行单元，分为两种类型：
|
|
|
|
- 普通规则(Rule): 执行固定的业务逻辑
|
|
- 分支规则(SwitchRule): 根据条件返回下一个要执行的规则列表
|
|
|
|
### 规则链(RuleChain)
|
|
|
|
规则链定义了规则的执行顺序，支持三种组合方式：
|
|
|
|
- THEN: 顺序执行一组规则
|
|
- SWITCH: 条件分支执行不同规则
|
|
- PARALLEL: 并行执行一组规则
|
|
|
|
### 规则上下文(RuleContext)
|
|
|
|
在规则执行过程中传递数据和状态的载体，包含：
|
|
|
|
- 上下文数据
|
|
- 错误信息
|
|
- 执行状态
|
|
- 执行时间统计
|
|
|
|
### 规则配置(RuleConfig)
|
|
|
|
控制规则执行的行为，包含：
|
|
|
|
- 是否启用执行时间监控
|
|
- 是否打印执行时间
|
|
- 是否启用日志
|
|
|
|
## 高级特性
|
|
|
|
### 1. 规则链缓存
|
|
|
|
规则引擎会自动缓存构建好的规则链，提高执行效率。缓存支持以下配置：
|
|
|
|
```yaml
|
|
literule:
|
|
cache:
|
|
enabled: true # 是否启用缓存
|
|
```
|
|
|
|
### 2. 规则预加载
|
|
|
|
在应用启动时预加载所有规则，提前发现配置错误，减少首次执行的延迟：
|
|
|
|
```yaml
|
|
literule:
|
|
preload:
|
|
enabled: true # 是否启用预加载
|
|
```
|
|
|
|
### 3. 并行执行配置
|
|
|
|
控制并行规则执行的行为：
|
|
|
|
```yaml
|
|
literule:
|
|
execution:
|
|
timeout: 30000 # 默认超时时间(毫秒)
|
|
enable-parallel: true # 是否启用并行执行
|
|
max-parallel-threads: 10 # 最大并行线程数
|
|
```
|
|
|
|
### 4. 循环依赖检测
|
|
|
|
规则引擎会自动检测规则链中的循环依赖，避免无限递归执行。
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
blade-starter-literule/
|
|
├── annotation/ # 注解
|
|
│ ├── EngineComponent.java # 引擎组件注解
|
|
│ └── RuleComponent.java # 规则组件注解
|
|
│
|
|
├── builder/ # 规则构建
|
|
│ ├── LiteRule.java # 规则构建器
|
|
│ ├── RuleBuilder.java # 规则构建器接口
|
|
│ ├── RuleBuilderExecutor.java # 规则构建器执行器
|
|
│ └── chain/ # 规则链构建器
|
|
│ ├── AbstractRuleChain.java # 规则链抽象基类
|
|
│ ├── ParallelRuleChain.java # 并行规则链构建器
|
|
│ ├── RuleChain.java # 并行规则链接口
|
|
│ ├── SwitchRuleChain.java # 分支规则链构建器
|
|
│ └── ThenRuleChain.java # 顺序规则链构建器
|
|
│
|
|
├── config/ # 配置类
|
|
│ ├── AbstractComponentRegistrar.java # 组件注册器抽象基类
|
|
│ ├── EngineComponentRegistrar.java # 引擎组件注册器
|
|
│ ├── RuleComponentRegistrar.java # 规则组件注册器
|
|
│ ├── RuleEngineAutoConfiguration.java # 规则引擎自动配置
|
|
│ └── RuleEngineProperties.java # 规则引擎配置属性
|
|
│
|
|
├── context/ # 上下文管理
|
|
│ ├── RuleContextHolder.java # 规则上下文持有者
|
|
│ └── RuleContextManager.java # 规则上下文管理器
|
|
│
|
|
├── core/ # 核心实现
|
|
│ ├── AbstractBaseRule.java # 规则基类
|
|
│ ├── AbstractRule.java # 普通规则抽象实现
|
|
│ ├── AbstractRuleContext.java # 规则上下文抽象实现
|
|
│ └── AbstractSwitchRule.java # 分支规则抽象实现
|
|
│
|
|
├── engine/ # 规则引擎执行
|
|
│ ├── DefaultRuleEngineExecutor.java # 默认规则引擎执行器
|
|
│ ├── RuleEngineExecutor.java # 规则引擎执行器接口
|
|
│ └── RulePreloadRunner.java # 规则预加载服务
|
|
│
|
|
├── exception/ # 异常
|
|
│ └── RuleException.java # 规则异常
|
|
│
|
|
└── provider/ # 接口和模型
|
|
├── Rule.java # 规则接口
|
|
├── RuleConfig.java # 规则配置类
|
|
├── RuleContext.java # 规则上下文接口
|
|
├── RuleResponse.java # 规则响应类
|
|
└── SwitchRule.java # 分支规则接口
|
|
```
|
|
|
|
## 最佳实践
|
|
|
|
### 1. 规则设计原则
|
|
|
|
- **单一职责**：一个规则只做一件事，便于维护和测试
|
|
- **无状态**：规则不应保存状态，所有状态应通过上下文传递
|
|
- **幂等性**：多次执行结果一致，避免副作用
|
|
- **异常处理**：规则内部应处理异常，避免中断规则链执行
|
|
|
|
### 2. 规则链设计原则
|
|
|
|
- **层次清晰**：明确的执行顺序，避免复杂的嵌套
|
|
- **解耦合**：规则之间通过上下文交互，避免直接依赖
|
|
- **可维护**：便于添加、删除、修改规则，不影响整体流程
|
|
- **合理分组**：相关规则放在一起，便于理解和维护
|
|
|
|
### 3. 性能优化
|
|
|
|
- **合理使用缓存**：对于频繁执行的规则链，启用缓存
|
|
- **并行执行**：对于独立的规则，使用并行执行提高效率
|
|
- **异步执行**：对于耗时长的规则链，使用异步执行
|
|
- **资源管理**：及时清理上下文资源，避免内存泄漏
|
|
|
|
## 完整示例
|
|
|
|
参考 `org.springblade.test.literule.LiteRuleTest` 类，提供了完整的使用示例。 |