跳到主要内容

规则引擎API

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向业务系统与规则引擎的集成，提供规则引擎API的完整接口文档，覆盖业务规则接口、规则执行接口、规则缓存接口、业务限制接口等核心能力。文档重点说明：

  • 规则链配置与缓存策略
  • 规则执行上下文与LiteFlow集成
  • 业务限制检查与缓存一致性
  • 规则配置示例与执行流程
  • 性能优化建议与最佳实践

项目结构​

规则引擎API位于 yudao-module-rule 模块，分为API接口层与工具/上下文层：

  • API接口层：对外暴露Feign接口，供业务系统调用
  • DTO与枚举：定义规则详情、业务限制、缓存键等数据结构
  • 上下文与工具：封装设备上下文、规则执行与缓存访问逻辑
  • 文档：规则中心操作与配置说明

Mermaid Diagram Code:

graph TB
subgraph "规则引擎API模块"
A["RuleBusinessApi 接口<br/>业务规则交互"]
B["DTO与枚举<br/>RuleLiteflowChainCacheDTO<br/>BusinessLimitCacheDTO<br/>RuleBusinessLimitDTO<br/>CacheConstants<br/>ApiConstants"]
C["上下文与工具<br/>DeviceContext<br/>RuleRunUtil<br/>RuleApiUtil"]
end
subgraph "外部依赖"
D["LiteFlow 规则引擎"]
E["Redis 缓存"]
F["Kafka 事件总线"]
end
A --> B
C --> A
C --> D
C --> E
C --> F

图表来源

章节来源

核心组件​

  • 业务规则交互接口：RuleBusinessApi，提供规则绑定/解绑、规则列表查询、MAC/渠道/地区查询、规则详情、业务ID集合查询、审批变更、业务数量限制、设备数量统计等RPC接口
  • 规则缓存DTO：RuleLiteflowChainCacheDTO，承载规则链名称、EL表达式、命名空间、启用状态、流程状态、地区集合等
  • 业务限制DTO：RuleBusinessLimitDTO、BusinessLimitCacheDTO，承载业务类型/ID、数量限制、当前已操作数、剩余可用数等
  • 缓存常量：CacheConstants，定义规则详情、规则-设备/MAC/渠道/业务、业务限制等Redis键前缀与本地缓存键
  • 执行工具：RuleRunUtil，封装三级缓存（本地缓存->Redis->数据库）、候选规则初筛、LiteFlow规则执行、业务限制检查、业务ID聚合
  • 上下文：DeviceContext，扩展设备响应DTO，注入设备属性与心跳时间标记

章节来源

架构总览​

规则引擎API采用“三级缓存 + 分布式锁 + RPC回源”的架构，结合LiteFlow执行规则链，最终返回业务ID集合。

Mermaid Diagram Code:

sequenceDiagram
participant Biz as "业务系统"
participant API as "RuleBusinessApi"
participant Util as "RuleRunUtil"
participant Redis as "Redis"
participant DB as "RuleBusinessApi(后端)"
participant LF as "LiteFlow"
Biz->>API : 调用规则匹配接口
API->>Util : 传入业务类型与设备上下文
Util->>Redis : 读取候选规则(MAC/渠道/业务类型/无设备限制)
Redis-->>Util : 返回候选规则ID集合
Util->>Redis : 读取规则详情(按ID)
Redis-->>Util : 返回规则详情(含EL/启用/地区)
Util->>LF : 执行规则链(chainName, 设备上下文)
LF-->>Util : 返回执行结果
Util->>Redis : 读取业务限制(按业务类型+业务ID)
Redis-->>Util : 返回业务限制信息
Util-->>API : 返回匹配的业务ID集合
API-->>Biz : 返回结果

图表来源

详细组件分析​

业务规则接口（RuleBusinessApi）​

  • 作用：业务系统与规则引擎交互的RPC接口，提供规则绑定/解绑、规则列表、MAC/渠道/地区查询、规则详情、业务ID集合、审批变更、业务限制、设备数量统计等能力
  • 关键接口
    • 绑定/解绑规则：bindOrUnbindRule
    • 规则列表：listRules
    • MAC列表：listMacs
    • 渠道/地区列表：listChannels、listRegions
    • 规则ID集合查询：按MAC、业务类型、渠道、无设备限制
    • 规则详情：getRuleDetail
    • 业务ID集合：按规则+业务类型
    • 解绑全部规则：unbindAllRules、unbindAllRulesNoBpm
    • 审批变更：getApprovalChangeInfo、updateBpmNoStartMessage、cancelPendingChanges
    • 业务限制：getBusinessLimit
    • 设备数量：getDeviceCount、getDeviceCountMore

章节来源

规则执行接口（RuleRunUtil）​

  • 作用：封装规则执行全流程，包含候选规则初筛、规则详情缓存、LiteFlow执行、业务限制检查、业务ID聚合
  • 执行流程
    • 输入：业务类型、设备上下文
    • 候选规则初筛：基于MAC专属规则、业务类型规则、渠道规则、无设备限制规则取并集后与业务类型规则取交集
    • 规则详情获取：三级缓存（本地->Redis->数据库），命中后校验启用/生效/地区限制
    • 规则计算：LiteFlow执行规则链，返回成功即纳入候选
    • 业务限制检查：仅对有数量限制的业务类型，从Redis实时获取限制信息并判断
    • 输出：匹配的业务ID集合

Mermaid Diagram Code:

flowchart TD
Start(["开始"]) --> CheckInput["校验业务类型与设备上下文"]
CheckInput --> |为空| EmptyRet["返回空集合"]
CheckInput --> Candidate["候选规则初筛<br/>MAC/渠道/业务类型/无设备限制"]
Candidate --> Exec["遍历候选规则并执行LiteFlow"]
Exec --> Detail["获取规则详情(含启用/生效/地区)"]
Detail --> Limit["业务限制检查(仅限有配额业务)"]
Limit --> Out["输出匹配的业务ID集合"]
EmptyRet --> End(["结束"])
Out --> End

图表来源

章节来源

规则缓存接口（RuleRunUtil + CacheConstants）​

  • 缓存策略
    • 本地缓存：热点数据（业务类型规则、渠道规则、无设备限制规则、规则详情、业务限制）使用本地缓存提升命中率
    • Redis缓存：规则-设备/MAC/渠道/业务、规则详情、业务限制使用Redis，支持穿透占位符与分布式锁
    • 数据库回源：缓存未命中时加分布式锁查询数据库，并回填缓存
  • 缓存键前缀
    • 规则详情：r:data:base:rule
    • MAC->规则ID集合：r:m:r
    • 无设备限制->规则ID集合：r:no:limit:r
    • 业务类型->规则ID集合：r:btype:r
    • 规则ID+业务类型->业务ID集合：r:r:btype:b
    • 业务类型->业务ID->数量限制：r:btype:b:limit
    • 渠道ID->规则ID集合：r:c:r
    • 业务数量限制缓存：r:b:limit

Mermaid Diagram Code:

classDiagram
class CacheConstants {
+RULE_INFO
+RULE_MAC_SET
+RULE_NO_LIMIT_SET
+RULE_BUSINESS_TYPE_SET
+RULE_BUSINESS_HASH
+RULE_BUSINESS_LIMIT_HASH
+RULE_CHANNEL_SET
+RULE_BUSINESS_LIMIT
+LOCAL_RULE_INFO
+LOCAL_RULE_NO_LIMIT_SET
+LOCAL_RULE_BUSINESS_TYPE_SET
+LOCAL_RULE_BUSINESS_HASH
+LOCAL_RULE_CHANNEL_SET
+LOCAL_RULE_BUSINESS_LIMIT
+LOCAL_NO_LIMIT_CACHE_KEY
}
class RuleRunUtil {
+matchBusinessIds(...)
+getRuleIdsByMac(...)
+getRuleIdsByBusinessType(...)
+getRuleIdsByChannel(...)
+getNoLimitRuleIds(...)
+getRuleDetail(...)
+getBusinessLimit(...)
}
RuleRunUtil --> CacheConstants : "使用缓存键"

图表来源

章节来源

业务限制接口（RuleBusinessLimitDTO / BusinessLimitCacheDTO / RuleApiUtil）​

  • 业务限制DTO：RuleBusinessLimitDTO，支持设置业务类型/ID、数量限制、当前已操作数、增量更新
  • 业务限制缓存DTO：BusinessLimitCacheDTO，用于Redis哈希结构存储业务限制信息，提供剩余可用数与余量判断
  • 事件与广播：RuleApiUtil提供业务限制更新消息发送与本地缓存清理事件广播，配合Spring Cloud Bus实现集群一致性

Mermaid Diagram Code:

sequenceDiagram
participant Biz as "业务系统"
participant API as "RuleBusinessApi"
participant Util as "RuleApiUtil"
participant Kafka as "Kafka"
participant Bus as "Spring Cloud Bus"
participant Nodes as "集群节点"
Biz->>API : 更新业务限制
API->>Util : 调用更新方法
Util->>Kafka : 发送业务限制更新消息
Util->>Bus : 发布本地缓存清理事件
Bus-->>Nodes : 广播事件
Nodes-->>Nodes : 随机延迟后清理本地缓存

图表来源

章节来源

规则链配置与执行上下文​

  • 规则链配置：RuleLiteflowChainCacheDTO包含chainName、elData、enable、valid、regionIds等字段，用于LiteFlow执行与地区过滤
  • 执行上下文：DeviceContext扩展设备响应DTO，注入设备属性与心跳时间标记，便于规则节点按需读取

Mermaid Diagram Code:

classDiagram
class DeviceContext {
+Map~String,Object~ properties
+Long heartbeatTime
+boolean hasHeartbeatUpdated
+setHeartbeatTime(...)
+isHasHeartbeatUpdated()
}
class RuleLiteflowChainCacheDTO {
+Long id
+String chainName
+String elData
+Integer enable
+Integer valid
+Long[] regionIds
}
DeviceContext --> RuleLiteflowChainCacheDTO : "执行时传入LiteFlow"

图表来源

章节来源

规则配置示例与执行流程说明​

  • 规则清单管理：支持规则新增、编辑、EL表达式可视化配置、设备数量统计与重新计算
  • MAC资源管理：支持MAC资源包创建、批量导入、在规则中复用
  • EL规则编辑器：支持AND/OR逻辑组、字段与操作类型、EL表达式实时预览

章节来源

依赖关系分析​

  • RuleRunUtil依赖
    • Spring上下文：获取FlowExecutor、RuleBusinessApi、Redis客户端、本地缓存工具
    • LiteFlow：执行规则链
    • Redis：规则详情、规则-设备/MAC/渠道/业务、业务限制缓存
    • Kafka：业务限制更新消息
  • RuleBusinessApi依赖
    • Feign客户端：远程调用规则中心后端
    • ApiConstants：服务名与前缀

Mermaid Diagram Code:

graph LR
Util["RuleRunUtil"] --> LF["LiteFlow FlowExecutor"]
Util --> Redis["Redis 缓存"]
Util --> API["RuleBusinessApi(Fegin)"]
API --> Backend["规则中心后端"]
Util --> Kafka["Kafka"]

图表来源

章节来源

性能考量​

  • 三级缓存策略
    • 本地缓存：热点数据（业务类型规则、渠道规则、无设备限制规则、规则详情、业务限制）优先命中，降低Redis与数据库压力
    • Redis缓存：使用穿透占位符避免缓存穿透；对热点数据设置合理TTL
    • 分布式锁：缓存未命中时加锁查询数据库，避免缓存击穿
  • LiteFlow执行
    • 仅对候选规则执行，减少不必要的规则链执行
    • 对启用/生效/地区限制进行前置过滤
  • 业务限制检查
    • 仅对有数量限制的业务类型从Redis实时获取限制信息，避免本地缓存污染
  • 事件与广播
    • 业务限制更新通过Kafka异步传播，本地缓存清理事件通过Spring Cloud Bus广播，节点随机延迟清理，避免雪崩

章节来源

故障排查指南​

  • 规则匹配为空
    • 检查候选规则初筛：确认MAC/渠道/业务类型/无设备限制规则是否正确配置
    • 检查规则启用/生效/地区限制：确保规则enable=1、valid非无效、设备regionId在规则regionIds中
  • 规则执行失败
    • 检查规则链名称与EL表达式：确保chainName正确、EL表达式不为空且合法
    • 查看LiteFlow执行响应与日志
  • 业务限制异常
    • 确认业务类型是否配置数量限制；检查Redis中业务限制缓存是否正确
    • 触发本地缓存清理事件，等待广播后重试
  • 缓存穿透与击穿
    • 检查穿透占位符是否正确设置；确认分布式锁是否正确释放

章节来源

结论​

规则引擎API通过三级缓存、分布式锁与LiteFlow规则链执行，实现了高性能、可扩展的规则匹配与业务限制检查能力。配合业务限制事件与本地缓存清理广播，保障了集群一致性与低延迟。建议在业务系统中遵循本文档的接口规范与最佳实践，确保规则配置与执行的稳定性与性能。

附录​

  • 规则中心操作与配置参考
    • 规则清单管理：规则新增、编辑、EL表达式可视化配置、设备数量统计
    • MAC资源管理：资源包创建、批量导入、在规则中复用
    • EL规则编辑器：AND/OR逻辑组、字段与操作类型、EL表达式预览

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答