Iceberg HDP 文件监听与 Spark 任务自动提交模块设计文档
Iceberg HDP 文件监听与 Spark 任务自动提交模块设计文档
文档信息
归属服务：cspservhdp
核心实现类：IcebergSqlWatchService
触发机制：Spring 定时轮询
下游执行：Spark 集群完成 Iceberg 建表、老化数据清理
一、业务流程（文字流程图）
流程文字对应说明
- HDFS 分两个独立目录存放上游生成的建表、老化 sql.yaml；
- 服务开启两条独立定时任务，每小时分别扫描对应目录；
- 进入统一通用扫描方法，自动检测 Spark 运行所需配置文件，缺失则通过本地模板渲染生成 app-config.yaml、config.yaml；
- 读取 sql.yaml 文件修改时间，和内存 ConcurrentHashMap 缓存的上一次时间做对比；
- 文件无变更：直接结束本轮扫描；
- 文件发生更新：更新缓存时间，调用 Spark 客户端异步提交任务；
- Spark 集群读取 yaml 执行对应建表或数据老化清理逻辑。
二、分层组件及职责
1. 定时调度层
- 两套独立定时方法，互不干扰，扫描间隔统一 1 小时
fullScan：扫描建表目录，任务标识 icebergCreateTableTask，启动延迟 5 秒
scanAgingTaskDir：扫描老化目录，任务标识 icebergAgingTask，启动延迟 10 秒 - 每次扫描先校验 HDFS 集群连通状态，HDFS 不可用直接终止本轮扫描并打印错误日志
- 各自独立 try-catch 捕获异常，其中一个目录扫描失败不阻塞另一个定时任务
2. 通用目录扫描工具方法 scanSingleDir
统一复用逻辑，接收监听目录、配置路径、任务标识、修改时间缓存 Map、根目录、应用名称入参
- 判断监听 sql 目录是否存在，不存在打印警告日志直接返回
- 调用方法自动补全 app-config.yaml、config.yaml 两份 Spark 运行配置
- 获取目录下 sql.yaml 文件，进入文件变更判断逻辑
3. 模板渲染子能力
- loadTemplate：读取 classpath 内置 yaml 模板，使用并发 Map 缓存模板文本，避免重复读取本地资源
- renderTemplate：识别 ${key} 占位符，替换应用名、HDFS 根目录等参数，生成完整配置文本
- writeHdfsFile：将渲染后的配置写入指定 HDFS 路径，打印生成成功 / 失败日志
4. 文件变更判断逻辑 processFileChange
- 维护两套独立 ConcurrentHashMap，分别缓存建表、老化 sql.yaml 上次修改时间，保证线程安全
- 对比当前文件修改时间与缓存值，一致则直接返回，不提交任务
- 时间发生变化则更新缓存记录，发起 Spark 任务提交
5. Spark 任务提交能力 submitSparkTask
依赖 SparkClientUDA 客户端实现异步任务提交，传入任务名称、HDFS 任务配置文件路径；
提交过程出现异常抛出 ScheduleProcessingException，由上层定时方法捕获记录错误日志。
三、输入输出定义
输入
- 上游产出：aggregation-schedule 模块生成，存放在 HDFS 两套目录的 sql.yaml（建表 DDL、老化 DML）
- 静态资源：classpath 下 app-config-template.yaml、config-template.yaml 任务模板
- 底层依赖工具：HdfsClient、SparkClientUDA
输出
- 自动产物：HDFS 目录下 Spark 运行配置文件 app-config.yaml、config.yaml
- 执行动作：异步提交 Spark 任务，分为两类执行逻辑
建表任务：执行 CREATE NAMESPACE、CREATE TABLE IF NOT EXISTS
老化任务：执行 DELETE 过期数据、expire_snapshots 清理快照、remove_orphan_files 清理孤立文件
四、隔离设计
- 存储隔离：建表、老化使用完全独立 HDFS 根目录、独立 sql 监听子目录
- 资源隔离：独立任务名称、独立定时方法、独立修改时间缓存 Map
- 异常隔离：两个定时任务独立捕获异常，故障互不影响
五、核心设计规则
- 轮询周期：固定 3600000 毫秒（1 小时）执行一次扫描
- 幂等设计：基于文件修改时间缓存做增量判断，文件无更新不会重复提交 Spark 任务
- 免人工运维：Spark 依赖的配置文件缺失时自动根据模板生成，无需人工上传维护
- 性能优化：模板文本全局内存缓存，减少频繁 IO 读取本地模板文件
六、容错处理规则
- HDFS 集群离线：直接跳过本次扫描，输出错误日志
- 监听 sql 目录不存在：仅打印警告日志，不中断服务运行
- 模板读取、HDFS 文件写入异常：捕获异常记录错误日志，不终止服务
- Spark 任务提交失败：抛出业务调度异常，可对接监控告警
- 单目录扫描异常仅中断当前任务，另一套定时扫描正常执行不受影响