跳到主要内容

黑名单关联关系

引用文件

本文引用的文件

目录​

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

简介​

本章节聚焦“黑名单关联关系”的设计与实现，覆盖黑名单与设备MAC地址、渠道、区域三类实体之间的多对多关联管理。内容包括：

  • 关联表设计与外键约束策略
  • 级联与变更状态同步机制
  • 批量导入/导出（Excel）、异步导出任务与错误恢复
  • 实时更新与缓存一致性保障
  • 最佳实践与性能优化建议

项目结构​

黑名单模块由“API层 + 业务层 + 数据访问层 + 配置映射”构成，核心控制器负责对外暴露黑名单及其关联关系的CRUD与导出接口；业务实现层负责审批流、草稿、缓存与批量处理；数据对象与Mapper映射MySQL表结构。

Mermaid Diagram Code:

graph TB
subgraph "黑名单模块"
C["AppBlacklistedController<br/>REST 控制器"]
S["AppBlacklistedServiceImpl<br/>业务实现"]
M1["AppBlacklistedMapper.xml"]
M2["FlowBlacklistedMacMapper.xml"]
M3["FlowBlacklistedChannelMapper.xml"]
M4["FlowBlacklistedRegionMapper.xml"]
DO1["FlowBlacklistedMacDO"]
DO2["FlowBlacklistedChannelDO"]
DO3["FlowBlacklistedRegionDO"]
end
subgraph "设备模块"
CH["ChannelMapper<br/>渠道"]
RG["SysRegionMapper<br/>区域"]
DM["DeviceMacTypeMapper<br/>设备MAC"]
end
subgraph "任务模块"
ET["ExportTaskApi<br/>导出任务"]
EU["ExportTaskUtil<br/>导出工具"]
ETD["ExportTaskEvent<br/>导出事件"]
end
C --> S
S --> M1
S --> M2
S --> M3
S --> M4
S --> ET
S --> EU
S --> ETD
DO1 -.-> M2
DO2 -.-> M3
DO3 -.-> M4
M3 --> CH
M4 --> RG
M2 --> DM

图表来源

章节来源

核心组件​

  • 控制器层：提供黑名单及三类关联关系的分页查询、创建、更新、删除、导出、取消变更等接口。
  • 业务实现层：封装审批流、草稿、缓存、批量导入/导出、异步任务等逻辑。
  • 数据对象层：三类关联DO分别映射 flow_blacklisted_mac、flow_blacklisted_channel、flow_blacklisted_region。
  • 映射层：MyBatis XML 定义分页查询、批量插入/更新、按条件删除等SQL。

章节来源

架构总览​

黑名单关联关系采用“主表 + 三张子表”的多对多设计，通过审批流与草稿机制实现变更的非即时生效与回滚能力。业务层统一协调三类关联的创建、更新、删除与批量导入，并通过导出任务实现异步导出。

Mermaid Diagram Code:

sequenceDiagram
participant U as "用户"
participant C as "AppBlacklistedController"
participant S as "AppBlacklistedServiceImpl"
participant M as "各Mapper"
participant T as "ExportTaskApi/Util"
U->>C : "POST /flow-blacklisted-mac/import"
C->>S : "importFlowBlacklistedMac(userId, files, blacklistedId)"
S->>S : "解析Excel并格式化MAC"
S->>M : "批量插入/更新 flow_blacklisted_mac"
S->>M : "更新主表审批状态"
S-->>C : "返回导入成功数量"
U->>C : "GET /flow-blacklisted-mac/export-excel"
C->>S : "asyncExportConfigMac(pageReqVO)"
S->>T : "创建导出任务"
T-->>U : "返回任务建立成功"

图表来源

详细组件分析​

1) 关联表设计与外键约束​

  • flow_blacklisted_mac
    • 字段：id、blacklistedId、mac、draft、valid
    • 说明：mac字段存储格式化后的MAC地址；valid用于审批状态；draft用于草稿记录。
  • flow_blacklisted_channel
    • 字段：id、blacklistedId、channelId、draft、valid
    • 说明：channelId指向渠道表；与黑名单主表形成多对多。
  • flow_blacklisted_region
    • 字段：id、blacklistedId、regionId、draft、valid
    • 说明：regionId指向区域表；与黑名单主表形成多对多。

外键约束策略

  • 三张子表均以 blacklistedId 关联主表 app_blacklisted，采用软删除与valid状态标记实现“级联删除/更新”的可控性。
  • 业务层在删除或更新时区分“未生效（NO）”与“已生效（YES/UPDATE/DELETE）”两类，未生效数据直接物理删除，已生效数据打上删除/修改标记并走审批流。

章节来源

2) 多对多关系维护与审批流​

  • 创建/更新/删除均通过业务层统一入口，先校验是否可编辑，再根据是否涉及主表关键字段决定是否进入审批流。
  • 草稿机制：BpmDraft 记录变更前后差异，未生效状态下可随时取消。
  • 状态机：valid字段承载“未生效/已生效/更新中/删除中/修改中”等状态，配合审批流推进。

Mermaid Diagram Code:

stateDiagram-v2
[*] --> 未生效
未生效 --> 已生效 : "审批通过"
未生效 --> 更新中 : "主表关键字段变更"
更新中 --> 已生效 : "审批通过"
已生效 --> 删除中 : "删除操作"
删除中 --> 已生效 : "审批通过"
已生效 --> 修改中 : "主表关键字段变更"
修改中 --> 已生效 : "审批通过"

图表来源

章节来源

3) 批量关联与取消关联​

  • 批量导入MAC
    • 接口：POST /flow-blacklisted-mac/import
    • 处理：逐文件解析Excel，格式化MAC，分批插入/更新（每批上限控制），最后统一更新审批状态。
  • 同步/异步导出
    • 同步导出：GET /flow-blacklisted-mac/export-excel/sync，直接生成CSV并打包下载。
    • 异步导出：GET /flow-blacklisted-mac/export-excel，创建导出任务，后续在任务中心查看进度。
  • 取消变更
    • 支持取消未审批的MAC/渠道/区域关联；未生效数据直接删除，已生效数据清除草稿并回滚状态。

Mermaid Diagram Code:

flowchart TD
Start(["开始：导入Excel"]) --> Parse["解析Excel并格式化MAC"]
Parse --> BatchInsert["分批插入/更新 flow_blacklisted_mac"]
BatchInsert --> UpdateBpm["更新主表审批状态"]
UpdateBpm --> End(["结束"])
subgraph "导出流程"
S1["选择导出模式"] --> Mode{"同步还是异步？"}
Mode --> |同步| Sync["生成CSV并打包下载"]
Mode --> |异步| Async["创建导出任务"]
end

图表来源

章节来源

4) 关联关系状态同步与缓存一致性​

  • 缓存穿透防护：Redis缓存中不存在时，通过分布式锁避免并发穿透，同时写入占位值。
  • 缓存更新：主表更新后主动清理/重建Redis缓存，确保读取一致性。
  • 本地缓存：使用本地缓存注解承载短期热点数据，降低数据库压力。

Mermaid Diagram Code:

sequenceDiagram
participant S as "业务层"
participant R as "Redis"
participant L as "分布式锁"
participant DB as "数据库"
S->>R : "查询黑名单缓存"
alt 缓存命中
R-->>S : "返回缓存"
else 缓存缺失
S->>L : "尝试获取分布式锁"
alt 获取成功
S->>R : "检查缓存(二次检查)"
S->>DB : "查询数据库"
DB-->>S : "返回数据"
S->>R : "写入缓存(含占位值)"
S->>L : "释放锁"
else 获取失败
S-->>S : "等待或放弃"
end
end

图表来源

章节来源

5) 与渠道、区域、MAC实体的集成​

  • 渠道关联：flow_blacklisted_channel 通过 channelId 关联设备模块的渠道表。
  • 区域关联：flow_blacklisted_region 通过 regionId 关联设备模块的区域表。
  • MAC关联：flow_blacklisted_mac 通过 mac 字段与设备模块的MAC类型表关联，导入前统一格式化。

章节来源

依赖分析​

  • 控制器依赖业务层；业务层依赖Mapper与任务模块；Mapper依赖设备模块的渠道/区域/设备MAC表。
  • 三类关联的CRUD接口集中在控制器中，业务层统一协调审批流与草稿机制。

Mermaid Diagram Code:

graph LR
C["AppBlacklistedController"] --> S["AppBlacklistedServiceImpl"]
S --> M1["AppBlacklistedMapper.xml"]
S --> M2["FlowBlacklistedMacMapper.xml"]
S --> M3["FlowBlacklistedChannelMapper.xml"]
S --> M4["FlowBlacklistedRegionMapper.xml"]
M2 --> DM["DeviceMacTypeMapper"]
M3 --> CH["ChannelMapper"]
M4 --> RG["SysRegionMapper"]
S --> ET["ExportTaskApi"]

图表来源

章节来源

性能考虑​

  • 批量导入
    • 分批插入：每批固定大小（如5000），减少单次事务压力与内存占用。
    • 格式化前置：导入前统一格式化MAC，避免重复转换。
  • 导出
    • 异步导出：大数据量场景优先异步，避免阻塞请求线程。
    • CSV生成与压缩：导出完成后压缩，减小IO与网络传输。
  • 缓存
    • 分布式锁：缓存缺失时加锁，避免缓存击穿。
    • 占位值：缓存穿透时写入占位值，缩短后续请求等待。
  • 审批流
    • 草稿最小化：仅记录变更差异，减少持久化开销。
    • 状态机：通过valid字段快速判断是否需要进入审批流。

故障排查指南​

  • 导入失败
    • 现象：导入Excel报错或部分数据未生效。
    • 排查：检查Excel格式、MAC格式化是否正确、是否存在重复项、是否触发审批流。
    • 参考路径：批量导入MAC实现
  • 取消变更无效
    • 现象：取消未审批的关联未生效。
    • 排查：确认关联记录状态是否为“未生效”，确认业务层取消逻辑是否执行。
    • 参考路径：取消MAC变更
  • 导出任务未完成
    • 现象：异步导出任务无响应或长时间未完成。
    • 排查：检查任务中心状态、磁盘空间、导出参数范围限制。
    • 参考路径：异步导出接口

章节来源

结论​

黑名单关联关系通过“主表 + 三类子表 + 审批流 + 草稿 + 缓存 + 任务”的组合，实现了对MAC、渠道、区域的灵活多对多管理。业务层在保证数据一致性的同时，提供了批量导入/导出、异步处理与错误恢复能力，满足大规模运营场景下的稳定性与可维护性需求。

附录​

  • 黑名单类型枚举：DELETE（卸载）、KILL（杀死/闪退），用于区分不同业务类型的关联关系与导出范围。
  • 文档入口：黑名单管理模块概览与子功能入口说明。

章节来源

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