跳到主要内容

黑名单管理API

引用文件

本文引用的文件

目录​

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

简介​

本文件面向黑名单管理API，系统性梳理应用黑名单查询接口、黑名单状态管理接口、黑名单审批流程接口、黑名单统计分析接口等核心功能，明确黑名单类型枚举、审批状态流转、缓存策略、异步处理机制，提供黑名单配置示例、审批流程图和异常处理方案，并解释黑名单与工作流系统的集成方式。

项目结构​

黑名单模块由API接口层、业务服务层、数据访问层与工作流监听器组成，采用分层清晰的职责划分，配合规则引擎与传统匹配逻辑并行，实现灵活高效的黑名单策略下发。

Mermaid Diagram Code:

graph TB
subgraph "接口层"
Ctl["AppBlacklistedController<br/>REST 控制器"]
end
subgraph "业务服务层"
SvcI["AppBlacklistedService<br/>接口"]
SvcImpl["AppBlacklistedServiceImpl<br/>实现"]
BpmSvc["AppBlackListedBpmServiceImpl<br/>审批流服务"]
Listener["BpmBlacklistStatusListener<br/>流程状态监听"]
end
subgraph "数据访问层"
DO["AppBlacklistedDO<br/>实体"]
MapperXML["AppBlacklistedMapper.xml<br/>MyBatis 映射"]
end
subgraph "枚举与常量"
EnumType["BlacklistedTypeEnum<br/>黑名单类型"]
EnumErr["ErrorCodeConstants<br/>错误码"]
ConstApi["ApiConstants<br/>API常量"]
end
subgraph "文档与说明"
DocIndex["docs/blacklist/index.md"]
DocDetail["docs/blacklist/app-blacklisted.md"]
DocMac["docs/blacklist/mac-relation.md"]
end
Ctl --> SvcI
SvcI --> SvcImpl
SvcImpl --> BpmSvc
BpmSvc --> Listener
SvcImpl --> DO
DO --> MapperXML
Ctl --> EnumType
Ctl --> EnumErr
Ctl --> ConstApi
DocIndex -.-> Ctl
DocDetail -.-> Ctl
DocMac -.-> Ctl

图表来源

章节来源

核心组件​

  • 控制器层：提供黑名单配置、关联关系、明细查询、导出、审批流、缓存刷新等HTTP接口。
  • 服务层：封装业务逻辑，包括黑名单主表与子表（渠道、MAC、地区）的CRUD、审批流编排、异步导出、布隆过滤器刷新、规则引擎与传统匹配合并。
  • 数据访问层：MyBatis实体与映射文件，DAO层负责持久化。
  • 枚举与常量：黑名单类型、错误码、API前缀与版本等。
  • 工作流集成：审批流创建、取消、状态监听与规则引擎联动。

章节来源

架构总览​

黑名单模块采用“控制器-服务-数据访问-工作流”的分层架构，支持规则引擎与传统匹配双路径，审批流贯穿修改与删除操作，异步导出与缓存提升性能与一致性。

Mermaid Diagram Code:

graph TB
Client["客户端/设备"] --> API["AppBlacklistedController"]
API --> Svc["AppBlacklistedService"]
Svc --> Impl["AppBlacklistedServiceImpl"]
Impl --> Bpm["AppBlackListedBpmServiceImpl"]
Bpm --> WF["BpmProcessInstanceApi"]
Impl --> DAO["MyBatis/DAO"]
Impl --> Rule["RuleBusinessApi"]
Impl --> Export["ExportTaskApi"]
Impl --> Redis["Redis/本地缓存"]
WF --> Listener["BpmBlacklistStatusListener"]
Listener --> Impl

图表来源

详细组件分析​

1) 黑名单类型枚举​

  • 类型定义：卸载（DELETE）、杀死（KILL）。
  • 使用位置：接口返回、统计计算、导出校验等。

Mermaid Diagram Code:

classDiagram
class BlacklistedTypeEnum {
+Integer code
+String desc
+DELETE
+KILL
}

图表来源

章节来源

2) 审批状态与流程集成​

  • 审批状态：未开始、审批中、审批通过、审批不通过、已取消。
  • 流程变量：业务类型、更新类型、黑名单主子表关联ID集合。
  • 监听器：接收流程状态变更事件，驱动业务生效或回滚。

Mermaid Diagram Code:

sequenceDiagram
participant Admin as "管理员"
participant Ctrl as "AppBlacklistedController"
participant BpmSvc as "AppBlackListedBpmServiceImpl"
participant WF as "BpmProcessInstanceApi"
participant Lsn as "BpmBlacklistStatusListener"
Admin->>Ctrl : "提交审批/取消审批"
Ctrl->>BpmSvc : "createBpm()/cancelBpm()"
alt 创建审批
BpmSvc->>WF : "创建流程实例"
WF-->>BpmSvc : "返回流程实例ID"
BpmSvc-->>Ctrl : "更新业务状态"
else 取消审批
BpmSvc->>WF : "取消流程实例"
BpmSvc-->>Ctrl : "重置业务状态"
end
WF-->>Lsn : "推送流程状态事件"
Lsn->>BpmSvc : "handleBpmResult()"
BpmSvc-->>Ctrl : "业务生效/回滚"

图表来源

章节来源

3) 黑名单查询与统计接口​

  • 查询接口：分页查询、详情查询、导出Excel（同步/异步）。
  • 统计接口：按黑名单ID统计执行次数（卸载/Kill）。
  • 关联统计：结合规则引擎设备数量统计。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "AppBlacklistedController"
participant Svc as "AppBlacklistedService"
participant Impl as "AppBlacklistedServiceImpl"
participant Rule as "RuleBusinessApi"
participant Export as "ExportTaskApi"
Client->>Ctrl : "GET /page"
Ctrl->>Svc : "getAppBlacklistedPage()"
Svc->>Impl : "分页查询+设备数统计"
Impl->>Rule : "批量获取设备数量"
Rule-->>Impl : "返回设备数量"
Impl-->>Ctrl : "返回分页结果"
Ctrl-->>Client : "分页数据"
Client->>Ctrl : "GET /export-excel"
Ctrl->>Svc : "异步导出"
Svc->>Export : "创建导出任务"
Export-->>Client : "返回任务ID"

图表来源

章节来源

4) 黑名单状态管理接口​

  • 管理员直通：管理员修改/删除直接生效，无需审批。
  • 非管理员：修改/删除走审批流，支持取消未审批更新（含/不含子表）。

Mermaid Diagram Code:

flowchart TD
Start(["提交修改/删除"]) --> IsAdmin{"是否管理员角色"}
IsAdmin --> |是| Direct["直接更新/删除<br/>无需审批"]
IsAdmin --> |否| Draft["生成草稿并提交审批"]
Draft --> Approve{"审批通过?"}
Approve --> |是| Apply["应用变更并生效"]
Approve --> |否| Rollback["回滚草稿"]
Direct --> End(["完成"])
Apply --> End
Rollback --> End

图表来源

章节来源

5) 黑名单审批流程接口​

  • 创建审批：校验流程实例状态，构建流程变量，创建流程实例并更新业务状态。
  • 取消审批：取消运行中的流程实例并重置业务状态。
  • 规则联动：根据业务类型与更新类型向规则引擎推送业务信息。

Mermaid Diagram Code:

sequenceDiagram
participant Ctrl as "AppBlacklistedController"
participant BpmSvc as "AppBlackListedBpmServiceImpl"
participant WF as "BpmProcessInstanceApi"
participant Rule as "RuleBusinessApi"
Ctrl->>BpmSvc : "createBpm(userId, id)"
BpmSvc->>BpmSvc : "校验流程状态"
BpmSvc->>WF : "创建流程实例"
WF-->>BpmSvc : "返回实例ID"
BpmSvc->>Rule : "推送业务信息(可选)"
BpmSvc-->>Ctrl : "更新业务状态=审批中"
Ctrl->>BpmSvc : "cancelBpm(userId, id)"
BpmSvc->>WF : "取消流程实例"
BpmSvc-->>Ctrl : "更新业务状态=未开始"

图表来源

章节来源

6) 黑名单统计分析接口​

  • 统计维度：按黑名单ID统计执行次数（卸载/Kill）。
  • 时间范围：杀死/闪退明细导出需指定时间范围，同步导出限制最大天数。
  • 设备数：结合规则引擎获取设备数量，用于评估影响范围。

Mermaid Diagram Code:

flowchart TD
Req["请求统计/导出"] --> Type{"类型=卸载/Kill?"}
Type --> |卸载| CountDel["统计卸载执行次数"]
Type --> |杀死| Range{"是否指定时间范围?"}
Range --> |否| Err["抛出参数错误"]
Range --> |是| Limit{"是否超过最大天数?"}
Limit --> |是| Err
Limit --> |否| CountKill["统计杀死执行次数"]
CountDel --> Resp["返回统计结果"]
CountKill --> Resp
Err --> End["结束"]
Resp --> End

图表来源

章节来源

7) 缓存策略​

  • 本地缓存：按ID缓存黑名单主信息；按渠道ID/地区ID缓存黑名单ID集合，支持并发同步。
  • Redis缓存：黑名单主表缓存清理，避免脏读。
  • 布隆过滤器：预留初始化与刷新接口（示例代码存在，便于后续启用）。

Mermaid Diagram Code:

graph LR
Svc["AppBlacklistedService"] --> Local["LocalCache<br/>按ID/渠道/地区"]
Svc --> Redis["Redis缓存<br/>黑名单主表"]
Svc --> Bloom["布隆过滤器<br/>预留接口"]

图表来源

章节来源

8) 异步处理机制​

  • 异步导出：MAC配置导出、执行结果明细导出，创建导出任务并返回任务ID。
  • 同步导出：小数据量直接生成CSV并打包返回。
  • Kafka测试：提供发送设备回调与杀死回调事件的测试接口。

Mermaid Diagram Code:

sequenceDiagram
participant Client as "客户端"
participant Ctrl as "AppBlacklistedController"
participant Svc as "AppBlacklistedService"
participant Export as "ExportTaskApi"
Client->>Ctrl : "GET /export-excel"
Ctrl->>Svc : "asyncExportConfigMac()"
Svc->>Export : "创建导出任务"
Export-->>Client : "返回任务ID"
Client->>Ctrl : "GET /export-excel/sync"
Ctrl->>Svc : "startConfigMacExportTask()"
Svc-->>Client : "返回压缩包"

图表来源

章节来源

9) 黑名单配置示例​

  • 基础配置：应用名称、包名、开启状态、处理方式（卸载/杀死）、版本号、备注。
  • 关联配置：渠道、地区、MAC（支持文件导入）。
  • 规则引擎：绑定规则或新建规则，支持复杂条件组合与逻辑运算。

章节来源

10) 黑名单与工作流系统集成​

  • 流程定义键：以“blacklist”为前缀，绑定业务类型与更新类型。
  • 业务变量：包含黑名单主子表关联ID集合，规则引擎联动推送业务信息。
  • 状态监听：监听流程状态事件，驱动业务生效或回滚。

章节来源

依赖分析​

  • 控制器依赖服务接口，服务实现依赖DAO、规则引擎、导出任务、Redisson、Kafka等。
  • 审批流服务依赖流程实例API与规则引擎API。
  • 实体与映射文件支撑主子表持久化。

Mermaid Diagram Code:

graph TB
Ctrl["AppBlacklistedController"] --> SvcI["AppBlacklistedService"]
SvcI --> SvcImpl["AppBlacklistedServiceImpl"]
SvcImpl --> BpmSvc["AppBlackListedBpmServiceImpl"]
SvcImpl --> DAO["MyBatis/DAO"]
SvcImpl --> Rule["RuleBusinessApi"]
SvcImpl --> Export["ExportTaskApi"]
SvcImpl --> Redis["RedissonClient"]
BpmSvc --> WF["BpmProcessInstanceApi"]
BpmSvc --> Dict["DictDataApi"]
BpmSvc --> Rule
Listener["BpmBlacklistStatusListener"] --> BpmSvc

图表来源

章节来源

性能考虑​

  • 缓存策略：本地缓存与Redis缓存降低查询压力，布隆过滤器可用于快速排除非命中设备。
  • 异步导出：大数据量采用异步导出，避免阻塞请求线程。
  • 并发控制：流程实例并发冲突时统一取消并提示，避免数据不一致。
  • 统计优化：批量获取设备数量，减少多次远程调用。

故障排查指南​

  • 常见错误码
    • 黑名单配置不存在
    • 黑名单配置和渠道关系不存在
    • 黑名单配置和设备mac绑定关系不存在
    • 卸载明细不存在
    • 该黑名单配置正在审批中
    • 黑名单配置和设备mac绑定导入失败
    • 该数据不允许修改
    • 该黑名单对应的关联配置已存在
    • 黑名单配置和国家关系不存在
  • 排查要点
    • 审批状态异常：检查流程实例是否存在、是否被取消或重复提交。
    • 导出失败：确认任务ID、文件路径、权限与磁盘空间。
    • 导入失败：核对文件格式、字段校验与业务ID有效性。
    • 统计异常：确认黑名单状态（开启/删除）、类型（卸载/Kill）与时间范围。

章节来源

结论​

黑名单管理API通过清晰的分层设计、完善的审批流集成、灵活的规则引擎与传统匹配双路径、以及缓存与异步导出等性能优化，实现了对APP黑名单的高效治理与精准下发。接口覆盖查询、状态管理、审批、统计与导出等关键场景，满足复杂业务需求与高并发场景下的稳定性要求。

附录​

  • API前缀与版本：服务名、前缀、版本号定义于API常量。
  • 文档入口：黑名单管理模块概览、APP卸载配置、MAC关联配置等文档。

章节来源

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