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/
This commit is contained in:
openbot-coder committed 2026-09-15 13:57:31 +08:00
1 parent 02ec5b6e33
commit c4dd61665b
26 files changed
+2934 -1

No files matched your search

+113
View File
@@ -0,0 +1,113 @@
# 连接池与缓存
这个项目相比同类实现快 **约 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) — 缓存与超时的排查