KlineDataFiller 与 KlineDataFillerLazy 说明
KlineDataFiller 与 KlineDataFillerLazy 说明
本文档说明 kline_data_filler.py 与 kline_data_filler_lazy.py 两个模块的差异、在项目中的调用方式，以及为何通用服务与 HYPE 服务使用不同的类。
一、模块关系与技术差异
1.1 角色关系
kline_data_filler.py：基类KlineDataFiller，实现完整的 K 线校验与补充逻辑（连续性校验、窗口长度校验、冷却、拉取并写入等）。kline_data_filler_lazy.py：子类KlineDataFillerLazy，继承KlineDataFiller，仅改变「何时、如何创建 Hyperliquid 客户端」，其余逻辑全部复用基类。
1.2 核心区别：Info 的创建时机（Eager vs Lazy）
| 方面 | KlineDataFiller（基类） | KlineDataFillerLazy（子类） |
|---|---|---|
| 初始化策略 | 立即创建 | 延迟创建 |
_init_info() |
在 __init__ 里调用，直接 return Info(...) |
重写为 return None，启动时不建连接 |
| Info 何时创建 | 构造时就会建好 Info |
第一次调用 fill_missing_data 或 fill_missing_data_precise 时才建 |
因此：
- 基类：一 new 出来就会连 Hyperliquid（eager）。
- Lazy 版：只有第一次真正要补数据时才连（lazy），并带有重试和线程安全。
1.3 Lazy 版独有的行为
_ensure_info_initialized()：双重检查锁，仅在首次需要时创建Info；创建失败只打日志、返回 False，不抛异常。- 超时配置：基类写死
timeout=30；Lazy 使用配置项KLINE_FILLER_LAZY_TIMEOUT_MS。 - 线程安全：Lazy 增加
threading.RLock()（_exchange_lock），保证多线程下只初始化一次 Info。 - 重试与降级：在
fill_missing_data_precise/fill_missing_data中，先循环最多 3 次调用_ensure_info_initialized()，失败则间隔指数退避再试；若最终_info仍为 None，打错误日志并 直接 return 0（跳过本次补充，不抛异常）。
二、在项目中的调用方式
2.1 实时 K 线服务（通过 data_filler_class 注入）
基类 RealtimeKlineServiceBase 在初始化时用配置里的「数据填充器类」创建实例：
# realtime_kline_service_base.py
self.data_filler = self._config.data_filler_class(kline_repo=self.kline_repo)
-
通用版
RealtimeKlineService（realtime_kline_service.py）- 配置中写死使用
KlineDataFiller（立即建连）。
- 配置中写死使用
-
HYPE/PURR 专用版
RealtimeKlineServiceHypePurr（realtime_kline_service_hype.py）- 配置中使用
KlineDataFillerLazy（首次补数时才建连）。
- 配置中使用
2.2 实时服务内对 data_filler 的调用
在 realtime_kline_service_base.py 的 _fetch_and_validate_price_data() 中，统一通过 self.data_filler 做校验和补数：
- 校验：
validate_continuity()、validate_window_length()（基准币种与目标币种各一次）。 - 补数：若有具体缺失时间点则
fill_missing_data_precise()，否则fill_missing_data()；基准与目标各补一次，补完再重新查库。 - 统计：
get_stats()会出现在服务统计中。
2.3 数据修复（RepairExecutor）
src/utils/data_healing/repair_executor.py 中仅使用 KlineDataFiller（来自 kline_data_filler.py），不使用 Lazy 版：
- 查缺口：
self.kline_filler.validate_continuity(klines, timeframe)。 - 补 K 线：
self.kline_filler.fill_missing_data_precise(symbol, timeframe, missing_timestamps=kline_gaps)，对 symbol 与 base_symbol 各补一次。
2.4 调用关系小结
| 调用方 | 使用的类 | 来源文件 | 主要调用 |
|---|---|---|---|
| RealtimeKlineService（通用） | KlineDataFiller | kline_data_filler.py | validate_continuity、validate_window_length、fill_missing_data_precise、fill_missing_data、get_stats |
| RealtimeKlineServiceHypePurr（HYPE） | KlineDataFillerLazy | kline_data_filler_lazy.py | 同上（接口一致，仅首次补数时建连） |
| RepairExecutor（数据自愈） | KlineDataFiller | kline_data_filler.py | validate_continuity、fill_missing_data_precise |
三、为何通用版与 HYPE 版使用不同的类？
3.1 技术上的唯一区别
只有一点：Hyperliquid 的 Info 客户端什么时候被创建。
- RealtimeKlineService（通用）：服务一起动就创建
Info（在 Filler 的__init__里）。 - RealtimeKlineServiceHypePurr（HYPE）：第一次需要补数据时才创建（第一次调用
fill_missing_data/fill_missing_data_precise时）。 - 若从不补数：通用版仍会建好一个到 MAINNET 的连接；HYPE 版永远不会建这个连接。
除此以外，校验与补数逻辑、冷却、重试等均一致。
3.2 设计原因
-
通用版（RealtimeKlineService）
- 订阅大量活跃币种，分析多对关系，数据缺口出现概率高，补数几乎是预期会走到的路径。
- 使用 eager 的 KlineDataFiller：启动时就建好
Info，若 Hyperliquid 不可用可尽早失败，便于发现部署/网络问题；主引擎多一个常驻连接通常可接受。
-
HYPE 版（RealtimeKlineServiceHypePurr）
- 仅 HYPE + PURR 两个币种，订阅数少、数据量小，很多时候 K 线已连续，可能很久都不会触发补数。
- 使用 lazy 的 KlineDataFillerLazy：
- 不补数就不建连，减少不必要的 HTTP 连接和资源占用；
- 适合资源更紧或“能少连就少连”的环境；
- 首次补数时再建连，建连失败有重试和“跳过本次补数、返回 0”的降级，不影响服务其它逻辑。
结论：两个服务的业务逻辑（校验与补数）相同，差异在于「是否几乎一定会补数、对连接与失败时机的期望」。通用版用“启动就建连”的类，HYPE 版用“按需建连”的类。