fasttushare 需求分析

项目概述

fasttushare 是一个在 TuShare Pro 之上封装的高性能缓存层与访问库，通过智能缓存、并发调度与数据一致性策略显著提升数据获取速度，减少重复网络请求与配额消耗。项目最终以 Python 库形式发布，库名为 fasttushare，作者为张大鹏。

背景与动机

TuShare Pro 提供海量金融数据，但存在接口调用配额与速率限制，且重复查询会浪费调用额度与时间。
研究、回测、报表生成等场景中对历史数据的重复访问频繁，适合以本地缓存命中来节约时间与额度。
需要一个兼容 TuShare Pro 的透明代理层，最大化命中缓存、最小化网络调用、可控地保证数据新鲜度。

目标与不做事项

项目目标

在不改变业务逻辑的前提下，加速 TuShare 数据访问，显著降低接口调用次数。
提供「透明使用」体验：尽量保持与 TuShare Pro 原有调用方式一致，用户迁移成本低。
可配置的缓存策略（TTL、LRU、层级缓存、预热、离线模式），满足不同场景的新鲜度与性能需求。
统一的元数据与一致性管理，保证数据准确性可追溯。
可观测性：提供命中率、节省调用数、耗时等指标，辅助优化策略。

不做事项（当前版本）

不提供 TuShare 数据的二次分发服务，仅在本机/可控存储层做缓存。
不绕过合法配额与协议限制，缓存仅用于减少重复调用而非规避服务条款。
不实现数据清洗/加工流水线，聚焦于高效获取与缓存。

用户画像与使用场景

量化研究员：频繁回放与回测历史行情/因子数据，关注批量读取与高命中率。
数据工程师：周期性构建数据集市，关注稳定性、可观测性与批处理效率。
个人研究者/学生：脚本化查询，关注易用性与安装成本。

典型场景：

重复查询同一 ts_code 在多天或多次实验中复用。
回测时按交易日序列拉取同一端点的一致参数组合。
离线分析时在无网络或额度不足情况下依然可读缓存数据。

成功指标与性能目标

命中率：常用端点在稳定工作集下缓存命中率 ≥ 80%。
延迟：命中缓存的单次查询延迟 ≤ 30ms（本地存储）。
吞吐：并发 16 线程下无显著退化（<10%）。
节省额度：对重复查询的调用节省比例 ≥ 70%。
可观测性：提供命中/未命中、节省次数、平均耗时等指标接口。

业务需求与用户故事

作为研究员，我希望像调用 TuShare 一样调用 fasttushare，而无需重写业务代码。
作为工程师，我希望配置不同端点的缓存 TTL 与刷新策略，以平衡准确性与性能。
作为用户，我希望在网络不可用时读取历史缓存，以保证任务不中断。
作为维护者，我希望能查看每个端点的缓存占用、命中率与最近刷新时间。

功能性需求

透明代理：对 TuShare Pro 的端点调用进行包装，参数与返回结构保持一致。
可插拔缓存后端：
- 默认本地文件/SQLite 存储；可扩展到 Redis/Parquet 等。
键空间设计：端点名 + 规范化参数 + 数据版本号 → 稳定 Key（含分页与日期范围）。
缓存策略：
- TTL：端点级/参数级可配置存活时间。
- LRU：在容量受限时淘汰最少使用项。
- 预热：支持按端点/参数批量预取。
- 离线模式：强制只读缓存，避免任何网络调用。
一致性与新鲜度：
- 支持「强一致」（强制刷新）与「最终一致」（TTL 过期后后台刷新）。
并发与队列：
- 统一调度队列，限制并发与速率，避免触发服务端限流。
监控与日志：
- 命中率、耗时、缓存大小、刷新次数、错误码分布。
管理接口：
- 清理缓存（按端点/Key/时间范围）。
- 查看与导出缓存元数据。

非功能性需求

性能：读取缓存延迟与序列化开销可控；批量查询吞吐稳定。
可靠性：写入原子性、崩溃恢复、元数据一致。
可移植性：Windows/macOS/Linux；Python 3.9+。
安全：不记录或泄露敏感 Token；支持本地安全存储。
可维护性：模块化设计、清晰接口与单元测试覆盖。

系统设计概述

组件划分

核心代理层（Proxy）：拦截并封装 TuShare 调用；路由至缓存或网络。
缓存存储层（Store）：提供统一接口：get/set/delete/scan；实现本地文件/SQLite。
键与元数据（Key/Meta）：生成稳定键；记录端点、参数摘要、TTL、最后刷新时间、校验和。
调度与并发（Scheduler）：控制并发、速率、重试与退避；支持后台刷新。
监控与日志（Metrics/Logging）：记录指标并对外暴露查询接口。

数据流

用户调用 fasttushare → 生成 Key → 查询缓存。
命中：返回数据；更新命中计数与最近访问时间。
未命中/过期：进入调度队列；按策略从 TuShare 拉取；写入缓存与元数据；返回数据。
后台刷新（可选）：TTL 过期后异步刷新，前台仍使用旧数据直到刷新完成。

缓存策略设计

TTL 策略：端点默认 TTL；可针对参数（如日期范围）覆盖。
LRU 容量：支持按总大小/条目数限制；淘汰策略可配置。
一致性级别：
- strict：每次强制刷新；适用于高度时效数据。
- eventual：TTL 内使用缓存，过期后台刷新。
- offline_only：仅读缓存，不触网。
预热与批量：支持对常用端点/参数列表预拉取以填充缓存。
失效触发：手动清理、TTL 到期、版本号变化、数据校验失败。

数据模型与存储

本地目录结构：~/.fasttushare/（可配置）。
SQLite 模式：
- 表 cache_entries(key PRIMARY, endpoint, params_hash, created_at, ttl, last_refresh_at, size, checksum)。
- 表 cache_blobs(key PRIMARY, blob) 或外置文件；支持分块。
文件模式：
- data/<endpoint>/<key>.parquet 或 .json；meta/<key>.json 存放元数据。
- 支持压缩与校验。

API 设计与库结构（草案）

python 复制代码

import fasttushare as fts

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

# 透明调用：等价于 ts.pro_api().query(endpoint, params)
df = client.query("daily", ts_code="000001.SZ", start_date="20240101", end_date="20240131")

# 策略配置
client.set_policy(endpoint="daily", ttl="1d", consistency="eventual")

# 管理与监控
client.metrics()           # 命中率、耗时、节省调用数
client.cache_clear("daily")
client.offline(True)       # 离线模式

模块结构：

client.py：公共入口、策略管理、透明代理。
store/：sqlite_store.py、file_store.py 等后端实现。
scheduler.py：并发、速率限制、重试与后台刷新。
key.py：键生成与参数规范化、哈希。
meta.py：元数据模型与校验。
metrics.py：指标采集与查询。
config.py：默认配置、加载与校验。

配置与安装

通过 pip install fasttushare 安装。
默认使用本地目录与 SQLite；可通过环境变量或代码设置存储后端与路径。
支持 FASTTUSHARE_HOME 指定缓存根目录。

授权与安全

Token 管理：不写入缓存内容或日志；仅保存在进程内存或用户安全存储。
日志脱敏：参数中出现 Token 时自动屏蔽。

错误处理与重试

网络错误：指数退避重试，最大次数可配置。
数据错误：校验失败触发强制刷新或标记不可信。
部分页失败：分页断点续传与合并；失败页标注并重试。

监控与日志

指标：hits/misses/saved_calls/avg_latency/bytes_used/refresh_count。
日志：关键路径、错误与策略决策；支持调试级别开关。

兼容性与依赖

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

测试策略

单元测试：键生成、TTL、LRU、存储接口、一致性策略。
集成测试：与真实 TuShare 对接的调度与刷新路径（需隔离 Token）。
性能测试：命中与未命中的延迟、并发吞吐、容量压力。

发布与版本

版本语义化（SemVer）。
初始里程碑：
- v0.1：透明代理 + 本地 SQLite/文件存储 + TTL + 指标。
- v0.2：LRU 容量、后台刷新、预热与离线模式。
- v0.3：可插拔后端、CLI 管理工具（可选）。

风险与缓解

服务条款合规风险：坚持仅缓存重复查询结果，避免绕过限制的滥用；在文档中明确用途与合规建议。
数据过期导致分析偏差：提供强制刷新与一致性级别选择；默认谨慎 TTL。
文件损坏或 SQLite 崩溃：引入校验和与原子写；提供恢复工具与重建策略。
并发导致写冲突：事务化写入与文件锁；调度层串行化关键写路径。

里程碑计划（建议）

原型与接口草案（1 周）：完成 Client.query 透明调用与本地文件存储；基本 TTL。
SQLite 后端与元数据（1 周）：稳定键空间与元数据结构；指标初版。
调度与并发（1 周）：重试、速率限制、后台刷新；离线模式。
LRU 容量与预热（1 周）：容量控制、批量预取；CLI/管理接口（可选）。
文档与发布（1 周）：README、示例、打包与 PyPI 发布；基础测试覆盖。

------ 本需求分析旨在为 fasttushare 的架构与实现提供清晰边界与度量标准，确保在提升访问速度与节省配额的同时，维持数据质量与合规性。