fasttushare 技术架构设计

架构目标

高命中率与低延迟的缓存命中，显著减少 TuShare Pro 调用次数。
与 TuShare Pro 透明兼容，最小迁移成本，尽量保留原有调用方式与返回结构。
可配置的新鲜度与一致性策略，支持离线模式与后台刷新。
强健的数据一致性与崩溃恢复，保证缓存数据可靠可追溯。
完整可观测性：命中率、耗时、节省调用数、缓存占用、错误分布。

总体架构

接口层（Client/Proxy）：提供透明 API；拦截调用 → 生成稳定键 → 查询缓存 → 调度刷新。
策略层（Policy）：端点/参数级 TTL、一致性、容量控制与离线开关。
存储层（Store）：统一缓存接口，支持 SQLite 与文件两种实现，可插拔扩展 Redis/Parquet。
调度层（Scheduler）：并发与速率限制、重试退避、后台刷新、分页合并。
键与元数据（Key/Meta）：参数规范化、哈希与版本标识；记录 TTL、刷新时间、校验和等。
可观测性（Metrics/Logging）：指标采集与查询；日志记录与脱敏。
配置与集成（Config/Adapter）：默认配置、环境变量注入；与 TuShare Pro 集成。

模块划分

client.py
- 封装 Client.query(endpoint, **params) 透明代理。
- 管理策略：set_policy() / offline() / cache_clear()。
- 注入 Store、Scheduler、KeyFactory、Metrics。
key.py
- 参数规范化（排序、类型归一、日期规范、分页标注）。
- 稳定序列化与哈希（推荐 xxhash 或 sha256）。
- 键结构：<endpoint>:<params_hash>:<version>。
meta.py
- 元数据模型：endpoint, params_hash, ttl, created_at, last_refresh_at, size, checksum, hits。
- 校验策略：读取后校验 checksum；失败触发强制刷新。
store/
- sqlite_store.py：
  - 表 cache_entries(key PRIMARY, endpoint, params_hash, created_at, ttl, last_refresh_at, size, checksum, hits)。
  - 表 cache_blobs(key PRIMARY, blob) 或外置文件路径；事务化写入，崩溃恢复。
- file_store.py：
  - 目录 data/<endpoint>/<key>.parquet|json，meta/<key>.json。
  - 原子写（临时文件 + 交换）、校验和、压缩支持。
- 统一接口：get(key) -> Blob|DataFrame, set(key, blob, meta), delete(key), scan(endpoint, prefix)。
scheduler.py
- 请求队列与并发控制（ThreadPool/AsyncIO 可选）。
- 速率限制（令牌桶/漏桶），防止触发服务端限流。
- 重试与退避（指数退避、抖动），错误分类与最大重试次数。
- 后台刷新与前台透传旧值（最终一致）。
- 分页拉取与合并，断点续传与失败页重试。
metrics.py
- 指标：hits, misses, saved_calls, avg_latency, bytes_used, refresh_count。
- 对外查询：metrics()，并提供结构化输出。
config.py
- 默认策略与阈值，环境变量（如 FASTTUSHARE_HOME）。
- 端点级配置覆盖与校验。
adapter/tushare.py
- 与 ts.pro_api() 对接，统一分页与参数映射；返回 DataFrame。

运行时数据流

前台请求：Client.query → KeyFactory 生成键 → Store.get。
命中：直接返回；更新 hits 与最近访问时间；采集耗时指标。
未命中/过期：进入 Scheduler 队列 → 受限并发与速率 → 调用 TuShare → 写入 Store 与 Meta → 返回。
后台刷新：TTL 到期后异步刷新；前台继续返回旧值直到刷新完成或过渡到严格模式。

键与参数规范化

规范化规则：
- 字典键排序、列表去重与排序、数值类型统一（int/float），字符串去空格。
- 日期格式统一为 YYYYMMDD；None/缺省 映射为固定占位符。
- 分页参数统一标注到键（如 limit/offset）。
哈希生成：
- 采用稳定序列化（例如 JSON with sorted keys，禁止不确定浮点格式）。
- 哈希算法：sha256(params_serialized)；可选 xxhash 提升性能。

缓存策略与一致性

一致性级别：
- strict：每次强制刷新；适用于高时效端点。
- eventual：TTL 内缓存，过期后台刷新。
- offline_only：仅读缓存，完全不触网。
TTL 策略：
- 端点级默认 TTL；参数级覆盖（如日期跨度、实时行情）。
LRU 容量：
- 按总大小/条目数限制；淘汰策略：最近最少使用；命中更新 hits/last_access。
预热：
- 支持对工作集端点/参数批量预取，减少首轮冷启动。

并发与速率限制

并发模型：
- 默认 ThreadPoolExecutor；I/O 受限场景优先线程模型，后续可支持 asyncio。
速率限制：
- 令牌桶：capacity, refill_rate；每次网络调用消耗令牌。
重试与退避：
- 网络类错误重试，指数退避与随机抖动；业务类错误（参数错误）直接失败。

存储实现细节

SQLite：
- 事务化写入；WAL 模式提升并发读取；表级索引（endpoint, params_hash）。
- 大对象策略：cache_blobs 存储二进制或外置文件路径；分块与压缩可选。
文件：
- 原子写：tmp 文件落盘后 rename；失败清理临时文件。
- 格式：优先 parquet（列式压缩与类型保持），兼容 json/csv。
- 元数据独立存储；读取时先校验 checksum 与 ttl/refresh。

可观测性与日志

指标：
- hits/misses/saved_calls/avg_latency/bytes_used/refresh_count/errors。
日志：
- 关键路径与策略决策；参数与 Token 脱敏；可配置日志级别。
输出接口：
- client.metrics() 返回结构化数据；后续可集成 Prometheus/OTLP（可选）。

安全与合规

Token 管理：仅保存在进程内存或用户安全存储；不写入日志/缓存内容。
合规边界：缓存用于减少重复调用，不提供二次分发；文档明确用途与限制。

API 设计（草案）

python 复制代码

import fasttushare as fts

client = fts.Client(token="...")

df = client.query("daily", ts_code="000001.SZ", start_date="20240101", end_date="20240131")

client.set_policy(endpoint="daily", ttl="1d", consistency="eventual")
client.cache_clear("daily")
client.offline(True)
client.metrics()

配置与部署

安装：pip install fasttushare。
环境变量：FASTTUSHARE_HOME（缓存目录）、FASTTUSHARE_BACKEND（sqlite|file|redis）。
默认配置：SQLite 后端与本地目录；端点级 TTL 提供合理初值，用户可覆盖。

依赖与兼容性

Python 3.9+；Windows/macOS/Linux。
依赖：tushare、pandas、sqlite3（标准库）；可选 pyarrow、xxhash、redis。

测试与质量保证

单元测试：键规范化、TTL/LRU、存储接口、一致性策略、速率限制与重试。
集成测试：真实 TuShare 对接（使用隔离 Token）；分页与后台刷新路径。
性能测试：命中与未命中延迟、并发吞吐、容量压力与淘汰准确性。
崩溃恢复测试：原子写、事务回滚、文件锁并发冲突。

性能与容量目标

命中率 ≥ 80%（稳定工作集）。
命中延迟 ≤ 30ms（本地读取）。
并发 16 线程下吞吐退化 < 10%。
可承载百万级键空间（SQLite 索引与文件分层）。

扩展性设计

Store 接口可插拔：新增 RedisStore/ParquetStore 无需改动上层逻辑。
策略可扩展：端点自定义 TTL/一致性；动态调整。
观测可扩展：导出到外部监控系统。

迁移与兼容

透明代理：与 TuShare Pro 的 query 调用保持参数与返回结构一致。
逐步替换：在现有代码中仅需替换入口创建与调用路径。

里程碑与交付

v0.1：Client 透明代理、SQLite/文件后端、TTL、基础指标。
v0.2：LRU 容量、后台刷新、预热、离线模式、分页合并。
v0.3：可插拔后端、CLI 管理工具、Prometheus 集成（可选）。

------ 该架构在保证透明兼容与合规前提下，通过稳定键空间、可靠存储与受控并发实现高性能缓存层，满足量化研究与数据工程的核心诉求。