状态同步机制

引用文件

本文引用的文件

简介

本文件系统化阐述黑名单状态同步机制，覆盖事件驱动架构、监听器设计、状态传播路径、触发条件（审批完成、规则匹配、手动修改）、状态数据结构（状态枚举、变更历史、冲突解决）、跨系统一致性保障（分布式锁、幂等性、重试机制），以及监控与性能优化建议。目标是帮助读者快速理解并安全地扩展黑名单状态同步能力。

项目结构

黑名单状态同步涉及多个模块协作：

规则模块：产生“规则变更导致流程不启动”的事件
BPM模块：产生“流程实例状态变化”的事件
黑名单模块：作为事件消费者，接收并处理状态变更
报告模块：消费“APK卸载更新”事件，完善历史记录
通用框架：提供事件模型、幂等与分布式锁工具、布隆过滤器等基础设施

Mermaid Diagram Code:

graph TB
subgraph "规则模块"
RBL["RuleBlacklistStatusListener<br/>规则变更监听器"]
end
subgraph "BPM模块"
BPE["BpmProcessInstanceStatusEvent<br/>流程状态事件"]
end
subgraph "黑名单模块"
BCL["BlackCallbackConsumer<br/>黑名单回调消费者"]
BLU["BlacklistUtil<br/>状态工具"]
end
subgraph "报告模块"
AUC["ApkUninstallUpdateConsumer<br/>卸载更新消费者"]
end
subgraph "通用框架"
DTO["DeviceBlackCallbackEventDTO<br/>回调事件DTO"]
EVT["ApkUninstallUpdateEvent<br/>卸载更新事件"]
IDE["幂等注解/RedisDAO"]
LOCK["Redis分布锁工具"]
BF["布隆过滤器工具"]
end
RBL --> |"规则变更事件"| BCL
BPE --> |"流程状态事件"| BCL
BCL --> |"下发卸载更新事件"| AUC
DTO --> BCL
EVT --> AUC
IDE --> BCL
LOCK --> BCL
BF --> BCL

图表来源

章节来源

README.md

核心组件

事件监听器
- 规则变更监听器：监听规则模块发出的“流程不启动”事件，将黑名单配置的BPM状态置为未启动
- BPM状态监听器：监听BPM模块发出的流程实例状态事件，交由黑名单业务服务处理审批结果
- 黑名单回调消费者：监听设备回调事件，落库并下发“APK卸载更新”事件
- 报告模块消费者：消费“APK卸载更新”事件，完善历史记录字段
事件模型
- 规则变更事件：携带规则ID与业务ID
- BPM流程状态事件：携带流程实例ID、状态、业务信息
- 设备回调事件DTO：包含事件ID、设备信息、黑名单ID列表
- 卸载更新事件：包含设备MAC/CPU、包名、卸载时间等
状态工具
- 提供黑名单状态更新、草稿封装等能力
基础设施
- 幂等注解与RedisDAO：保证同一业务请求在时间窗内仅执行一次
- 分布式锁工具：基于Redis实现加锁/解锁
- 布隆过滤器工具：用于高效判断黑名单命中与批量刷新

章节来源

架构总览

黑名单状态同步采用事件驱动架构，围绕“规则变更”和“BPM流程状态变化”两条主线进行状态传播，并通过消息队列实现跨模块解耦。

Mermaid Diagram Code:

sequenceDiagram
participant 规则 as "规则模块"
participant 黑名单 as "黑名单模块"
participant 报告 as "报告模块"
规则->>黑名单 : "规则变更事件(业务ID)"
黑名单->>黑名单 : "校验可编辑状态并更新BPM状态=未启动"
黑名单-->>报告 : "下发APK卸载更新事件"
报告->>报告 : "消费事件并完善历史记录"
Note over 规则,报告 : "规则变更触发状态回退至未启动，等待审批或手动确认"

图表来源

详细组件分析

规则变更监听器（RuleBlacklistStatusListener）

职责：监听规则模块发出的“流程不启动”事件，针对黑名单业务类型，将对应配置的BPM状态置为未启动，确保后续审批流程正确推进。

Mermaid Diagram Code:

classDiagram
class RuleBlacklistStatusListener {
+getBusinessType() Integer
+onEvent(event) void
}
class RuleBpmNoStartEventListener {
<<抽象>>
+onEvent(event) void
}
class BlacklistUtil {
+getCanEditAppBlackListedDO(businessId) AppBlacklistedDO
+updateBpmStatusToNoStart(data) void
}
class BusinessTypeEnum {
+BLACK_LIST
+getType() Integer
}
RuleBlacklistStatusListener --|> RuleBpmNoStartEventListener
RuleBlacklistStatusListener --> BlacklistUtil : "更新BPM状态"
RuleBlacklistStatusListener --> BusinessTypeEnum : "过滤业务类型"

图表来源

章节来源

BPM状态监听器（BpmBlacklistStatusListener）

职责：监听BPM模块发布的流程实例状态事件，限定仅处理黑名单相关流程前缀，交由业务服务处理审批结果。

Mermaid Diagram Code:

sequenceDiagram
participant BPM as "BPM模块"
participant 监听器 as "BpmBlacklistStatusListener"
participant 服务 as "IAppBlackListedBpmService"
BPM->>监听器 : "BpmProcessInstanceStatusEvent"
监听器->>监听器 : "校验流程定义Key前缀=黑名单"
监听器->>服务 : "handleBpmResult(event)"
服务-->>监听器 : "处理完成"

图表来源

章节来源

黑名单回调消费者（BlackCallbackConsumer）

职责：消费设备回调事件，批量落库设备命中记录，并下发“APK卸载更新”事件给报告模块。

Mermaid Diagram Code:

flowchart TD
Start(["接收回调事件"]) --> Check["校验黑名单ID列表"]
Check --> |为空| Warn["记录警告并返回"]
Check --> |非空| Loop["遍历黑名单ID"]
Loop --> Build["构造设备命中记录"]
Build --> Save["持久化设备命中记录"]
Save --> Send["下发APK卸载更新事件"]
Send --> End(["结束"])
Warn --> End

图表来源

章节来源

报告模块消费者（ApkUninstallUpdateConsumer）

职责：消费“APK卸载更新”事件，完善历史记录中的CPU与卸载时间字段，必要时新增记录并同步到搜索引擎。

Mermaid Diagram Code:

sequenceDiagram
participant MQ as "Kafka"
participant 消费者 as "ApkUninstallUpdateConsumer"
participant 服务 as "ApkPushHistoryService"
MQ->>消费者 : "ApkUninstallUpdateEvent"
消费者->>消费者 : "参数校验(mac, packageName)"
消费者->>服务 : "updateCpuidAndUninstallTime(record)"
服务-->>消费者 : "返回更新结果"
消费者-->>MQ : "处理完成"

图表来源

章节来源

状态数据结构与变更历史

业务类型枚举（BusinessTypeEnum）
- 黑名单业务类型标识，用于事件过滤与路由
BPM流程状态事件（BpmProcessInstanceStatusEvent）
- 包含流程实例ID、状态、业务信息（业务类型、业务ID、更新原因）
黑名单状态工具（BlacklistUtil）
- 提供状态更新、草稿封装等能力，确保状态变更原子性与一致性

章节来源

冲突解决与一致性保障

幂等性
- 使用幂等注解与RedisDAO，确保相同业务请求在时间窗内仅执行一次，避免重复落库或重复下发事件
分布式锁
- 基于Redis实现加锁/解锁，用于关键资源访问控制，防止并发冲突
布隆过滤器
- 用于黑名单命中快速判断与批量刷新，降低查询压力并提升命中准确性

章节来源

依赖关系分析

黑名单状态同步的关键依赖链如下：

Mermaid Diagram Code:

graph LR
RBL["RuleBlacklistStatusListener"] --> BT["BusinessTypeEnum"]
RBL --> BU["BlacklistUtil"]
BU --> APP["AppBlacklistedDO"]
BPL["BpmBlacklistStatusListener"] --> BPE["BpmProcessInstanceStatusEvent"]
BPL --> SVC["IAppBlackListedBpmService"]
BCC["BlackCallbackConsumer"] --> DTO["DeviceBlackCallbackEventDTO"]
BCC --> SVC2["AppBlacklistedService"]
BCC --> EVT["ApkUninstallUpdateEvent"]
AUC["ApkUninstallUpdateConsumer"] --> EVT

图表来源

性能考虑

消息批处理
- 回调消费者对黑名单ID列表进行批量处理，减少数据库往返与事件发送次数
缓存与布隆过滤器
- 利用Redis缓存与布隆过滤器加速命中判断与批量刷新，降低数据库压力
幂等与重试
- 幂等注解避免重复执行；Kafka消费者异常时触发自动重试，提高可靠性
监控与告警
- 建议对事件延迟、处理耗时、重试次数、失败率等指标进行监控

故障排查指南

规则变更后状态未更新
- 检查监听器业务类型过滤是否正确
- 校验黑名单配置是否处于可编辑状态
BPM状态未同步
- 确认流程定义Key前缀匹配
- 检查业务服务处理逻辑与异常日志
回调事件丢失或重复
- 核对Kafka主题与消费者组配置
- 检查幂等Key与Redis缓存状态
卸载更新未完善
- 校验事件字段完整性（mac、packageName）
- 查看消费者异常堆栈与重试日志

章节来源

结论

黑名单状态同步通过事件驱动与消息队列实现跨模块解耦，结合幂等、分布式锁与布隆过滤器等手段，保障状态一致性与高可用。建议在生产环境中持续完善监控指标、优化批处理策略与重试机制，以进一步提升稳定性与性能。

目录​

简介​

项目结构​

核心组件​

架构总览​

详细组件分析​

规则变更监听器（RuleBlacklistStatusListener）​

BPM状态监听器（BpmBlacklistStatusListener）​

黑名单回调消费者（BlackCallbackConsumer）​

报告模块消费者（ApkUninstallUpdateConsumer）​

状态数据结构与变更历史​

冲突解决与一致性保障​

依赖关系分析​

性能考虑​

故障排查指南​

结论​

目录

简介

项目结构

核心组件

架构总览

详细组件分析

规则变更监听器（RuleBlacklistStatusListener）

BPM状态监听器（BpmBlacklistStatusListener）

黑名单回调消费者（BlackCallbackConsumer）

报告模块消费者（ApkUninstallUpdateConsumer）

状态数据结构与变更历史

冲突解决与一致性保障

依赖关系分析

性能考虑

故障排查指南

结论