跳到主要内容

黑名单基础操作

引用文件

本文引用的文件

目录​

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

简介​

本文件围绕黑名单模块的“基础 CRUD 操作”展开，覆盖黑名单配置的创建、更新、删除、查询等核心能力；同时明确 API 设计规范（HTTP 方法、URL 路径、请求参数、响应格式）、业务校验规则（包名限制、版本号校验、必填字段检查）、数据持久化机制（MySQL 主表与子表、TDengine 统计明细、Redis 缓存与分布式锁）、以及常见使用场景与排障建议。目标是帮助开发者快速理解并正确使用黑名单基础功能。

项目结构​

黑名单模块采用“API 层-服务层-数据访问层”的分层架构，配合 Redis 缓存、分布式锁、审批流（BPM）与导出任务队列，形成完整的黑名单配置与执行控制链路。

Mermaid Diagram Code:

graph TB
subgraph "API 层"
C["AppBlacklistedController<br/>REST 控制器"]
end
subgraph "服务层"
S["AppBlacklistedService<br/>接口"]
SI["AppBlacklistedServiceImpl<br/>实现"]
end
subgraph "数据访问层"
M["AppBlacklistedMapper<br/>主表"]
CM["FlowBlacklistedChannelMapper<br/>渠道子表"]
MM["FlowBlacklistedMacMapper<br/>MAC 子表"]
DM["FlowBlacklistedDeviceMapper<br/>设备明细子表"]
TK["AppKillRecordMapper<br/>TDengine 杀死明细"]
end
subgraph "基础设施"
R["Redis 缓存/分布式锁"]
E["导出任务队列"]
B["审批流(BPM)"]
end
C --> S
S --> SI
SI --> M
SI --> CM
SI --> MM
SI --> DM
SI --> TK
SI --> R
SI --> E
SI --> B

图表来源

章节来源

核心组件​

  • 控制器层：提供 REST API，负责权限校验、参数校验、调用服务层并返回统一响应。
  • 服务层：定义黑名单配置及其子表（渠道、MAC、国家）的增删改查、审批流集成、导出任务、缓存与分布式锁等。
  • 数据访问层：MyBatis Mapper 负责 MySQL 主子表；TDengine Mapper 负责“杀死(闪退)”明细统计。
  • 枚举与常量：API 前缀、版本、黑名单类型、错误码等。

章节来源

架构总览​

黑名单基础操作贯穿“控制器-服务-数据访问-基础设施”，并结合审批流与导出任务，形成闭环。

Mermaid Diagram Code:

sequenceDiagram
participant U as "客户端"
participant C as "AppBlacklistedController"
participant S as "AppBlacklistedService"
participant SI as "AppBlacklistedServiceImpl"
participant DB as "MySQL 主子表"
participant T as "TDengine 杀死明细"
participant R as "Redis 缓存/锁"
U->>C : 发起请求(创建/更新/删除/查询)
C->>C : 权限校验/参数校验
C->>S : 调用服务层方法
S->>SI : 业务处理(事务/缓存/锁/BPM)
SI->>DB : 读写主子表
SI->>T : 写入杀死明细(按需)
SI->>R : 缓存/分布式锁
SI-->>C : 返回结果
C-->>U : 统一响应

图表来源

详细组件分析​

API 设计规范与接口清单​

  • 服务名与前缀
    • 服务名：blacklist-server
    • API 前缀：/admin/blacklist
    • 版本：1.0.0
  • 基础路径：/blacklist/app-blacklisted
  • 权限注解：@PreAuthorize，按功能点授权（创建/更新/删除/查询/导出/导入/流程）

常用接口（HTTP 方法 + URL + 请求体/参数 + 响应）：

  • 创建黑名单配置
    • 方法：POST
    • 路径：/blacklist/app-blacklisted/create
    • 请求体：AppBlacklistedSaveReqVO（包含包名、版本、类型、渠道ID列表、国家ID列表、MAC 文件）
    • 响应：Long（主键 ID）
  • 更新黑名单配置
    • 方法：PUT
    • 路径：/blacklist/app-blacklisted/update
    • 请求体：AppBlacklistedSaveReqVO（支持全量替换渠道/国家/MAC）
    • 响应：Boolean（true）
  • 删除黑名单配置
    • 方法：DELETE
    • 路径：/blacklist/app-blacklisted/delete
    • 参数：id（Long）
    • 响应：Boolean（true）
  • 查询单个配置
    • 方法：GET
    • 路径：/blacklist/app-blacklisted/get
    • 参数：id（Long）
    • 响应：AppBlacklistedRespVO（含渠道ID、设备数量、操作次数等）
  • 分页查询配置
    • 方法：GET
    • 路径：/blacklist/app-blacklisted/page
    • 参数：分页与筛选条件（AppBlacklistedPageReqVO）
    • 响应：PageResult<AppBlacklistedRespVO>
  • 导出配置为 Excel
    • 方法：GET
    • 路径：/blacklist/app-blacklisted/export-excel
    • 参数：分页与筛选（导出全部）
    • 响应：Excel 文件流
  • 渠道子表
    • 创建/更新/删除/查询/分页/导出/取消未审批更新
    • 路径前缀：/blacklist/app-blacklisted/flow-blacklisted-channel/*
  • MAC 子表
    • 创建/更新/删除/查询/分页/导入/导出/取消未审批更新
    • 路径前缀：/blacklist/app-blacklisted/flow-blacklisted-mac/*
  • 设备明细（杀死/闪退）
    • 分页/导出（异步/同步）
    • 路径前缀：/blacklist/app-blacklisted/flow-blacklisted-device/*
  • 国家子表
    • 创建/更新/删除/查询/分页/导出/取消未审批更新
    • 路径前缀：/blacklist/app-blacklisted/flow-blacklisted-region/*

章节来源

业务验证规则​

  • 包名限制
    • 系统保留包名禁止删除：若请求包名为保留集合中的包名，则拒绝创建/更新。
  • 版本号校验
    • 使用 VersionCodeValidator 对版本号进行合法性校验。
  • 必填字段检查
    • 控制器层通过 @Valid 与 VO 参数进行必填/格式校验。
  • 导出限制
    • 杀死(闪退)明细导出必须提供时间范围；同步导出时间跨度不超过3天。
  • 子表更新限制
    • 渠道/MAC/国家子表不支持直接更新，仅支持“全量替换/新增/删除标记”等策略。

章节来源

数据持久化机制​

  • 主表与子表
    • 主表：AppBlacklistedDO（黑名单配置）
    • 子表：渠道 FlowBlacklistedChannelDO、MAC FlowBlacklistedMacDO、国家 FlowBlacklistedRegionDO、设备明细 FlowBlacklistedDeviceDO
    • 事务：服务层方法标注 @Transactional，确保主子表一致性。
  • TDengine 明细
    • 杀死(闪退)明细表 app_kill_record，按日期与主键聚合，用于统计与导出。
  • 缓存与分布式锁
    • Redis 缓存：LocalCacheConstants 缓存黑名单信息，避免频繁读库；缓存穿透值处理。
    • 分布式锁：针对缓存重建场景加锁，防止击穿。
  • 导出任务
    • 异步导出：触发任务并返回任务建立结果，后续可在任务中心查看进度。
    • 同步导出：直接生成 CSV 并打包下载，适合小批量导出。

章节来源

审批流（BPM）与草稿​

  • 草稿机制
    • 更新/删除均以草稿形式暂存，未生效前可取消。
  • 审批状态
    • 未生效、已生效、更新中、删除中等状态由 BpmBusinessValid 管理。
  • 取消未审批更新
    • 支持取消主表或主子表全部未审批更新，恢复到上一个生效状态。

章节来源

API 工作流（以“创建黑名单配置”为例）​

Mermaid Diagram Code:

sequenceDiagram
participant C as "AppBlacklistedController"
participant S as "AppBlacklistedService"
participant SI as "AppBlacklistedServiceImpl"
participant DB as "MySQL"
participant R as "Redis"
participant B as "BPM"
C->>C : 校验包名与版本
C->>S : createAppBlacklisted(req)
S->>SI : 业务处理
SI->>DB : 插入主表(未生效草稿)
SI->>DB : 批量导入渠道/国家/MAC
SI->>R : 清理/写入缓存
SI->>B : 初始化审批草稿
SI-->>S : 返回ID
S-->>C : 返回ID
C-->>C : 统一响应

图表来源

数据模型与关系​

Mermaid Diagram Code:

erDiagram
APP_BLACKLISTED {
bigint id PK
string package_name
string version
int type
int valid
json draft
datetime create_time
datetime update_time
}
FLOW_BLACKLISTED_CHANNEL {
bigint id PK
bigint blacklisted_id FK
bigint channel_id
int valid
json draft
}
FLOW_BLACKLISTED_MAC {
bigint id PK
bigint blacklisted_id FK
string mac
int valid
json draft
}
FLOW_BLACKLISTED_REGION {
bigint id PK
bigint blacklisted_id FK
bigint region_id
int valid
json draft
}
FLOW_BLACKLISTED_DEVICE {
bigint id PK
bigint blacklisted_id FK
string mac
string cpu_id
int frequency
timestamp ts
datetime create_time
}
APP_BLACKLISTED ||--o{ FLOW_BLACKLISTED_CHANNEL : "拥有"
APP_BLACKLISTED ||--o{ FLOW_BLACKLISTED_MAC : "拥有"
APP_BLACKLISTED ||--o{ FLOW_BLACKLISTED_REGION : "拥有"
APP_BLACKLISTED ||--o{ FLOW_BLACKLISTED_DEVICE : "产生"

图表来源

依赖关系分析​

  • 控制器依赖服务接口，服务实现依赖多个 Mapper 与外部服务（规则、导出、Kafka 等）。
  • 服务层通过 Redis 缓存与分布式锁提升读性能，降低数据库压力。
  • TDengine 作为高性能时序存储，承载“杀死(闪退)”明细统计与导出。

Mermaid Diagram Code:

graph LR
C["AppBlacklistedController"] --> S["AppBlacklistedService"]
S --> SI["AppBlacklistedServiceImpl"]
SI --> M["AppBlacklistedMapper"]
SI --> CM["FlowBlacklistedChannelMapper"]
SI --> MM["FlowBlacklistedMacMapper"]
SI --> DM["FlowBlacklistedDeviceMapper"]
SI --> TK["AppKillRecordMapper"]
SI --> R["Redis 缓存/锁"]
SI --> E["导出任务"]
SI --> B["BPM 审批"]

图表来源

章节来源

性能与扩展性​

  • 缓存策略
    • 主表信息通过本地缓存与 Redis 缓存组合，命中率高、延迟低；缓存穿透值与分布式锁保障一致性。
  • 批量导入
    • MAC 导入采用分批写入（默认 5000），减少内存占用与数据库压力。
  • 导出优化
    • 异步导出适合大批量数据；同步导出限制时间窗口，避免阻塞。
  • 事务边界
    • 关键操作（创建/更新/删除/取消）均在事务内执行，保证主子表一致性。

章节来源

故障排查指南​

  • 常见错误码
    • 黑名单配置不存在、渠道关系不存在、MAC 关系不存在、设备明细不存在、正在审批中、导入失败、不允许修改、已存在关联、国家关系不存在。
  • 常见问题定位
    • 创建/更新被拒：检查包名是否为保留包名、版本号是否合法。
    • 删除失败：确认配置是否已审批，未审批可直接删除，已审批需走审批流程。
    • 导出异常：杀死(闪退)导出需提供时间范围且不超过3天；同步导出失败检查日志。
    • 子表更新报错：渠道/MAC/国家子表不支持直接更新，需通过“全量替换/删除标记”方式。
  • 诊断步骤
    • 查看控制器抛出的 ServiceException 或统一响应错误码。
    • 检查 Redis 缓存是否命中、分布式锁是否释放。
    • 核对审批状态与草稿字段，确认是否需要取消未审批更新。

章节来源

结论​

黑名单基础操作以清晰的分层架构、严格的业务校验与完善的持久化机制为基础，结合 Redis 缓存、分布式锁、审批流与导出任务，满足高并发下的黑名单配置与执行需求。开发者可基于本文档快速完成创建、更新、删除、查询等核心操作，并在遇到问题时依据故障排查指南快速定位与解决。

附录​

API 接口一览（摘要）​

  • 基础路径：/blacklist/app-blacklisted
  • 创建：POST /create
  • 更新：PUT /update
  • 删除：DELETE /delete
  • 查询单个：GET /get?id=...
  • 分页查询：GET /page
  • 导出 Excel：GET /export-excel
  • 子表接口：渠道/国家/MAC/设备明细均有对应的 CRUD 与导出接口
  • 审批流：/bpm/create、/bpm/cancel
  • 缓存刷新：/refresh/bloomFilter

章节来源

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