Files
pytdxdata/docs/internals/cache-pool.md
T
openbot-coder c4dd61665b docs: 建立 MkDocs 文档站与 AI 层文档
- 新增 MkDocs + Material 文档站(19 页):入门、CLI、场景示例、FAQ、
  Contributing、Changelog、API 参考(mkdocstrings 自动渲染)、内部原理
  (架构 / 协议 / 三池路由 / 缓存)
- 新增 docs/llms.txt:面向 LLM 的结构化摘要(枚举取值、方法速查、常见陷阱)
- 新增 scripts/check_docs.py:校验文档与 api.py 公开方法清单是否漂移
- 新增根 CHANGELOG.md 作为版本记录唯一来源,docs/changelog.md 用 snippet 引入
- 新增 .github/workflows/docs.yml:push main 自动构建并部署 GitHub Pages
- 修正文档口径:TdxData 公开方法 53 个(51 数据方法 + start/close);
  API_REFERENCE 版本号 v0.3.2 -> v0.4.0
- pyproject.toml 新增 docs 依赖组;.gitignore 忽略 site/
2026-09-15 13:57:31 +08:00

114 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 连接池与缓存
这个项目相比同类实现快 **约 2 倍**,来源就是这两块。
## 缓存
### 两级结构
```
内存 LRU ──miss──▶ 磁盘 SQLite (WAL) ──miss──▶ 回源网络
↑ ↑
快,进程内 跨进程 / 跨重启持久
```
- **内存层**:进程内 LRU,命中就是字典查找
- **磁盘层**:单文件 SQLite,开 WAL 模式,**可多进程共享**
- 未传 `cache_dir` 时只有内存层(进程退出即失效)
### TTL 分级
不同数据的「新鲜度要求」差了几个数量级,所以 TTL 是分级的:
| 数据类型 | TTL | 理由 |
|---|---|---|
| 五档报价 | **5s** | 变化最快 |
| 分钟 K 线 | **60s** | 边界处才会新增一根 |
| 日 K 线 | **当天** | 当天数据在盘中会变 |
| 复权 K 线 | **1 天** | 复权因子一天最多变一次 |
| 历史逐笔 | **永久** | 已经成交的不会变 |
| 证券列表 | **1 天** | 只有新股上市才变 |
### 缓存的是「已解析记录」
缓存里存的是**解析好的 dataclass 对象**(`codec/payload.py` 做 pickle + zlib),
不是原始响应字节。所以缓存命中时是 **0 网络 + 0 解析**,只有一次反序列化。
这也是为什么重复请求能从 0.31s 降到 **0.016s**。
### single-flight
同一时刻对**同一个缓存键**的并发请求会自动合并:第一个去回源,其余的等待并共享结果。
```python
# 100 个协程同时请求同一只股票的同一段 K 线
# → 只发 1 次网络请求
results = await asyncio.gather(*[
td.get_kline(Market.SH, "600000", KlinePeriod.DAY, count=800)
for _ in range(100)
])
```
上限由 `max_inflight`(默认 `64`)控制。
> 缓存键会做**规范化**——`get_quotes` 的键是排序去重后的股票集合,
> 所以 `[A, B]` 和 `[B, A]` 共享缓存。
## 连接池
### 动态扩缩容
| 参数 | 默认 | 含义 |
|---|---|---|
| `pool_min` | `3` | 保底连接数 |
| `pool_max` | `12` | 上限 |
| `mac_pool_cap` | `4` | **单台** MAC 服务器连接上限 |
| `timeout` | `3.0` | 连接超时(秒) |
按**等待队列长度**与**空闲时长**动态扩缩容,不是启动时就拉满。
### 健康分与选路
每台服务器维护一个健康分,取连接时按健康分 **+ EWMA 延迟**综合选路:
| 事件 | 健康分变化 |
|---|---|
| 请求失败 | **× 0.5** |
| 请求成功 | **+ 0.2** |
| 连续失败 | 进入 **120s 冷却**,冷却期内不再被选中 |
失败会**跨服务器故障转移**——重试用的是另一台,而不是同一台重连。
EWMA(指数加权移动平均)延迟让选路对「最近变慢」敏感,而不是被历史均值拖住。
### 为什么 MAC 池更小
MAC 通道可用服务器只有数台(见 [通道与数据源](routing.md#server-groups)),
所以 `mac_pool_cap` 默认只有 `4`——这是**对端限制**,不是本项目的选择。
逐笔 / 分时的并发能力天然弱于日线,原因就在这里。
## 并发分页
大请求会被拆成多页,每页带**显式 `start` 偏移**——**无状态,所以可以并行**。
多连接并行拉取 → 按序拼接 → 某页失败就换连接重试该页。
```
count=2400 → 3 页 → 3 个连接并行 → 按序拼接
```
两种例外:
| 场景 | 策略 | 原因 |
|---|---|---|
| `KlinePeriod.MIN_1` | **单连接串行** | 各服务器历史深度不一致,并发会导致非确定性空洞 |
| MAC 通道复权 K 线 | **单连接串行**(`_fetch_mac_kline_serial`) | 同上 |
!!! tip "调参建议"
`concurrency` 超过 `pool_max` 之后只会排队。实践值 **8~16**。
MAC 类请求(逐笔 / 分时)并发能力受 `mac_pool_cap` 限制,调大 `concurrency` 无用。
## 下一步
- [架构总览](architecture.md) — 这些模块在整体里的位置
- [常见问题](../faq.md) — 缓存与超时的排查