跳到主要内容

黑名单管理功能

引用文件

本文引用的文件

目录​

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

简介​

本技术文档围绕黑名单管理功能展开，聚焦于APP卸载黑名单的配置与执行闭环，覆盖应用卸载配置、黑名单类型管理、黑白名单切换机制、增删改查操作、与设备/渠道/区域的关联关系、状态与版本管理、以及与规则引擎的协同。文档同时给出API接口设计要点、参数校验、业务逻辑处理流程、数据模型关系、以及最佳实践与排障建议。

项目结构​

黑名单模块由API层与业务层组成，API层负责对外暴露REST接口与枚举常量，业务层负责审批流、规则引擎集成、子表关联（渠道、MAC、地区）、导出任务、Kafka回调处理等。

Mermaid Diagram Code:

graph TB
subgraph "API 层"
E1["BlacklistedTypeEnum<br/>黑名单类型枚举"]
E2["ErrorCodeConstants<br/>错误码常量"]
end
subgraph "业务层"
C1["AppBlacklistedController<br/>管理后台控制器"]
S1["AppBlacklistedServiceImpl<br/>黑名单主业务实现"]
M1["AppBlacklistedMapper.xml<br/>MyBatis 映射"]
DO1["AppBlacklistedDO<br/>主表实体"]
end
C1 --> S1
S1 --> DO1
S1 --> M1
E1 --- C1
E2 --- C1

图表来源

章节来源

核心组件​

  • 控制器层：提供黑名单主表与子表（渠道、MAC、地区、卸载明细）的增删改查、审批流、导出、布隆过滤器刷新等接口。
  • 服务层：封装业务逻辑，包括审批流状态管理、草稿数据处理、规则引擎集成、子表批量导入与变更、导出任务调度、Redis缓存穿透保护等。
  • 数据模型：主表AppBlacklistedDO承载黑名单基本信息；子表包括渠道、MAC、地区、卸载明细等。
  • 枚举与错误码：BlacklistedTypeEnum定义处理类型（卸载/杀死），ErrorCodeConstants定义模块内错误码。
  • 规则引擎：通过RuleBusinessApi与RuleRunUtil实现基于设备画像的高精度匹配。

章节来源

架构总览​

黑名单模块采用“控制器-服务-数据访问-规则引擎”的分层架构，支持规则引擎与传统模式双模匹配，兼容审批流与无审批模式，配合导出任务与Kafka异步回调完善数据闭环。

Mermaid Diagram Code:

graph TB
U["管理员/运营用户"]
API["AppBlacklistedController<br/>REST 接口"]
SVC["AppBlacklistedServiceImpl<br/>业务逻辑"]
RBA["RuleBusinessApi<br/>规则引擎接口"]
DB[("MySQL/Redis/TDengine")]
KFK["Kafka<br/>回调/通知"]
EX["导出任务/文件系统"]
U --> API
API --> SVC
SVC --> DB
SVC --> RBA
SVC --> KFK
SVC --> EX

图表来源

详细组件分析​

1) 黑名单类型与状态管理​

  • 黑名单类型：卸载（DELETE）与杀死（KILL），通过枚举统一管理。
  • 状态与版本：主表包含开启状态、处理类型、版本号、审批状态、生效标记等字段，支持草稿与审批流状态管理。

章节来源

2) API 接口设计与参数校验​

  • 主表增删改查：创建、更新、删除、分页查询、详情查询。
  • 子表管理：渠道、MAC、地区三类关联的分页查询、创建、更新、删除、导出、导入（MAC）。
  • 审批流：创建审批、取消审批、取消未审批更新（含/不含子表）。
  • 导出：支持同步与异步导出，MAC与卸载明细分别提供不同导出策略。
  • 参数校验：版本号格式校验、系统保留包名校验、导出时间范围限制等。

章节来源

3) 业务逻辑处理流程​

  • 创建/更新/删除：校验可编辑性、生成草稿、更新审批状态、触发规则解绑/更新。
  • 子表变更：渠道/MAC/地区均支持草稿态与生效态切换，未生效数据可直接删除，已生效数据走删除草稿。
  • 导入：MAC批量导入采用分批写入，避免大事务。
  • 缓存：主表支持本地缓存与分布式锁保护，防止缓存穿透。

Mermaid Diagram Code:

flowchart TD
Start(["进入业务方法"]) --> CheckEditable["校验是否可编辑"]
CheckEditable --> |不可编辑| ThrowErr["抛出异常"]
CheckEditable --> |可编辑| Draft["生成草稿/更新审批状态"]
Draft --> OperType{"操作类型？"}
OperType --> |创建| Insert["插入主表/子表"]
OperType --> |更新| Update["更新主表/子表"]
OperType --> |删除| MarkDel["标记删除/或直接删除"]
Insert --> ImportMac["导入MAC如有"]
ImportMac --> Done(["完成"])
Update --> Done
MarkDel --> Done
ThrowErr --> End(["结束"])
Done --> End

图表来源

章节来源

4) 与设备/渠道/区域的关联关系​

  • 多对多关系：黑名单主表与渠道、MAC、地区通过子表维护，支持批量导入与导出。
  • 传统模式：按渠道、MAC、地区组合进行匹配，逻辑为“(渠道 ∪ MAC) ∩ 地区”。
  • 规则引擎：支持更复杂的设备画像条件组合，实现高精度策略控制。

章节来源

5) 卸载/杀死明细与数据同步​

  • 数据来源：设备上报事件经Kafka异步落库，支持同步/异步导出。
  • 回调处理：黑名单卸载回调与杀死回调分别写入不同表，并在入库后触发后续通知。
  • 查询与统计：支持按MAC/CPU/时间范围查询，导出明细。

Mermaid Diagram Code:

sequenceDiagram
participant Dev as "设备"
participant Ctrl as "AppEventReportController"
participant Svc as "DeviceEventService"
participant KC as "Kafka : black-call-back"
participant KC2 as "Kafka : black-kill-call-back"
participant Cons as "BlackCallbackConsumer/BlackKillCallbackConsumer"
participant DB as "flow_blacklisted_device / app_kill_record"
Dev->>Ctrl : "POST /task/recoedDeviceEvent"
Ctrl->>Svc : "分发事件"
Svc->>KC : "BLACK_OP_CALL_BACK"
Svc->>KC2 : "BLACK_KILL_CALL_BACK"
KC-->>Cons : "消息"
KC2-->>Cons : "消息"
Cons->>DB : "写入明细表"

图表来源

章节来源

6) 黑名单状态管理与版本控制​

  • 启用/禁用：通过主表status字段控制是否生效。
  • 生效时间控制：通过审批流与生效标记（valid）控制变更生效时机。
  • 版本管理：version字段支持按版本号精准控制目标APP版本。

章节来源

7) 规则引擎与传统模式并行​

  • 双模匹配：同时计算规则引擎命中的黑名单ID与传统渠道/MAC/地区命中的黑名单ID，取并集后二次过滤未开启/已删除配置。
  • 建议：新创建记录优先使用规则配置，保持逻辑一致性与可维护性。

章节来源

依赖分析​

  • 控制器依赖服务：AppBlacklistedController聚合多个服务（黑名单、审批、导出、规则引擎）。
  • 服务依赖数据访问：AppBlacklistedServiceImpl依赖Mapper与RedisDAO、导出任务API、规则引擎API。
  • 枚举与错误码：API层提供类型与错误码，业务层统一使用。

Mermaid Diagram Code:

classDiagram
class AppBlacklistedController
class AppBlacklistedServiceImpl
class AppBlacklistedDO
class BlacklistedTypeEnum
class ErrorCodeConstants
AppBlacklistedController --> AppBlacklistedServiceImpl : "调用"
AppBlacklistedServiceImpl --> AppBlacklistedDO : "持久化/查询"
AppBlacklistedController --> BlacklistedTypeEnum : "使用"
AppBlacklistedController --> ErrorCodeConstants : "使用"

图表来源

章节来源

性能考虑​

  • 批量导入：MAC导入采用分批写入，降低单次事务压力。
  • 缓存保护：主表Redis缓存使用分布式锁与穿透值，避免热点击穿。
  • 导出优化：支持同步/异步导出，异步导出通过任务中心管理，减轻接口阻塞。
  • 并行匹配：规则引擎与传统模式并行计算，结果合并后统一过滤，兼顾准确性与性能。

故障排查指南​

  • 常见错误码
    • 黑名单配置不存在
    • 渠道关联不存在
    • MAC关联不存在
    • 卸载明细不存在
    • 正在审批中
    • MAC导入失败
    • 不允许修改
    • 关联配置已存在
    • 地区关联不存在
  • 排查建议
    • 检查审批状态与生效标记，确认是否处于草稿态或审批中。
    • 核对版本号格式与系统保留包名限制。
    • 导出失败时检查任务中心状态与文件路径权限。
    • Kafka回调异常时核对Topic配置与消费者状态。

章节来源

结论​

黑名单管理模块通过清晰的分层设计、完善的审批流与规则引擎集成、以及对设备/渠道/区域的灵活关联，实现了高可用、可扩展的黑名单配置与执行体系。建议在新场景中优先采用规则引擎配置，保持逻辑一致性；对存量传统配置逐步迁移；严格遵循参数校验与导出规范，确保数据质量与性能稳定。

附录​

A. 黑名单配置示例（操作指引）​

  • 新增黑名单：填写应用名称、包名、开启状态、处理类型、版本号，选择渠道/地区/MAC，提交审批。
  • 编辑黑名单：修改主表与子表配置，系统生成草稿并进入审批流程。
  • 删除黑名单：未审批可直接删除，已审批需走删除草稿流程。
  • 导出与导入：支持同步/异步导出，MAC支持批量导入。

章节来源

B. 最佳实践​

  • 新建黑名单优先绑定规则，减少传统条件碎片化。
  • 对高频变更的渠道/MAC/地区配置，使用批量导入与导出，避免逐条操作。
  • 严格控制版本号与生效时间，避免跨版本误伤。
  • 定期清理无效/过期规则与关联，保持系统整洁。
用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答