模块以 base.py 中的 DataLoaderProtocol(Protocol)定义统一契约:每个 loader 暴露 name、markets、requires_auth 以及 is_available()/fetch(codes, start_date, end_date, interval, fields) 方法;具体实现散落在 *_loader.py / *.py 文件中(如 tushare、yfinance、ccxt、eastmoney、okx、binance、futu、mt5、local 等),并通过 registry.py 的 @register 装饰器在首次导入时注册到全局 LOADER_REGISTRY。
- 注册与发现:
registry._ensure_registered()按需importlib.import_module所有已知 loader 模块,使调用方无需关心 import 顺序;FALLBACK_CHAINS按市场(a_share/us_equity/hk_equity/crypto/futures/fund/macro/forex 等)维护有优先级的候选源列表,resolve_loader沿链尝试is_available(),失败则抛NoAvailableSourceError。 - 网络层抽象:
_http.py提供进程内HostThrottle与throttled_get/throttled_get_json,对同一 host bucket 强制最小请求间隔 + 随机抖动,避免免费接口 IP 封禁;各 provider 通过host_key与min_interval自行声明限速策略。 - 可靠性原语:
base.py提供retry_with_budget(基于单调时钟 deadline + 指数退避的重试)、check_budget、positive_env_int/float等通用工具,被 ccxt、okx、tushare 等复用;validate_ohlc在 loader 边界校验 OHLC 不变量(high<low、非正价格等)。 - 本地缓存:
base.py内置 opt-in parquet 缓存(DuckDB 读写),键由 source/symbol/timeframe/date/fields 经 SHA-256 生成,仅对已结算日期范围生效,读/写异常均静默降级。 - Provider 专用辅助:
_fundamental_schema.py、cn_adjust.py、_symbol_utils.py、sec_edgar_client.py、yahoo_client.py、eastmoney_client.py、rsshub_events.py、sec_frames.py等文件封装特定市场的字段映射、复权、客户端或事件流。 依赖方向单向:具体 loader → base/registry/_http 等共享库,registry 不反向依赖具体 loader,仅通过字符串名反射实例化。