Files
pytdxdata/docs/internals/architecture.md
T
openbot-coder 7e830c7579 docs: 补齐测速缓存相关文档,并修掉 0.6.0 遗留的过时描述
上一提交只补了 getting-started / routing / llms.txt / SKILL.md 四处,本轮把其余
教程类页面与接口清单补齐,并顺手修正 v0.6.0 统一接口改造后遗留的过时说明。

补齐(当日测速缓存):

- README「已知限制」:说明当日首次启动会自动后台测速并缓存
- FAQ 新增「启动时会变慢吗?会不会在后台偷偷联网?」:无感保证 + 三个环境变量开关
- FAQ「连不上服务器怎么办」:加入"删当日测速缓存 / 环境变量指定主机"两条前置排查
- API_REFERENCE 四、辅助模块:config 补全当日测速相关函数与优先级链说明,
  新增 pytdxdata.pool.probe_cache 一节(ProbeCache / schedule_probe / get_probe_cache)
- internals/architecture.md 目录树:config.py、probe_cache.py 的职责注释更新
- internals/cache-pool.md「下一步」:补「服务器是怎么选出来的」交叉链接

修正(v0.6.0 遗留过时描述):

- FAQ / api/enums.md:删掉「所有接口的第一个参数都是 market」——统一接口已改为字符串标的
- FAQ / cookbook:`*_batch` 已并入 `get_bars`(多标的),不再作为批量入口
- FAQ / getting-started「自建服务器清单」:`standard_servers` 实际是 Sequence[str]
  而非 (host, port) 元组(端口由统一的 port= 指定);原示例照抄会取到错的主机名
  (已实测:字符串写法正确,元组写法不会被解析)

校验:check_docs.py exit 0;mkdocs build --strict 无告警;新增交叉链接
#当日自动测速无感 / #daily-probe 均正确渲染且目标锚点存在;全量 164 项通过;
src/pytdxdata/servers.json 跑测前后逐字节不变。
2026-09-21 18:26:37 +08:00

110 lines
4.7 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.
# 架构总览
## 分层
调用链是单向的,每一层只依赖它下面的一层——想加新接口时先想清楚「这属于哪一层」。
```mermaid
flowchart TD
A["api.py — TdxData<br/>唯一对外入口,28 个统一方法 + 33 个废弃别名"] --> B["router.py<br/>按命令选通道"]
B --> C["pool/ — 动态连接池<br/>标准池 / MAC 池 / EX 池"]
B --> D["scheduler/ — 并发分页调度<br/>Paginator"]
C --> E["protocol/ — 协议层<br/>帧 / 变长整数 / 价格 / 日期 / 命令"]
E --> F["TCP 通达信服务器<br/>7709 标准+MAC · 7727 EX"]
A --> G["cache/ — 双层 TTL 缓存<br/>Memory LRU → Disk SQLite"]
A --> H["codec/ — 解析与序列化<br/>缓存载荷 / 服务器文件"]
H --> I["models/ — dataclass + 枚举"]
```
## 目录
```
src/pytdxdata/
├── api.py # 统一接口 TdxData(对外唯一入口)
├── symbols.py # 标的解析:字符串 → Symbol(parse_symbol / format_symbol / market_targets)
├── router.py # 标准 / MAC / EX 通道选路
├── config.py # 服务器清单加载 + 选路优先级链 + 用户级测速缓存路径
├── indicator.py # 技术指标(纯函数,无依赖)
├── server_probe.py # 服务器探测,可 python -m 运行
├── protocol/ # 协议层
│ ├── frame.py # 标准帧
│ ├── mac_frame.py # MAC 帧
│ ├── _binary.py # 变长整数等底层字节工具
│ ├── price.py # 自定义浮点价格还原
│ ├── volume.py # 成交量差分还原
│ ├── datetime_.py # 日期 / 时间编码
│ └── commands/ # 16 个命令模块
├── pool/ # 连接池
│ ├── connection.py # 单连接(含重连)
│ ├── pool.py # 标准 / MAC 动态池
│ ├── ex_pool.py # EX 池
│ ├── health.py # 健康分与选路
│ └── probe_cache.py # 当日全量测速 + 用户级缓存(后台、无感)
├── scheduler/
│ └── paginator.py # 并发分页调度(3 连接并行)
├── cache/
│ ├── key.py # 缓存键规范化
│ ├── ttl.py # TTL 分级策略
│ ├── memory.py # 内存 LRU
│ ├── disk.py # 磁盘 SQLite(WAL)
│ └── manager.py # 两级协同 + single-flight
├── models/ # dataclass + 枚举(单文件,无子模块)
└── codec/ # 缓存载荷序列化 + 服务器文件解析
├── payload.py # 缓存载荷 pickle + zlib
├── block.py # 板块 .dat
├── industry.py # tdxhy.cfg
└── financial.py # gpcw.txt / gpcw*.zip
```
## 一次 `get_bars` 的完整路径
```mermaid
sequenceDiagram
participant U as 调用方
participant A as api.py
participant C as cache/
participant R as router.py
participant P as pool/
participant S as scheduler/
U->>A: get_bars("sh600000", DAY, count=2400)
A->>A: 规范化缓存键
A->>C: 查缓存
alt 命中
C-->>A: list[SecurityBar]
A-->>U: 直接返回(0 网络 0 解析)
else 未命中
A->>C: 登记 single-flight
A->>R: 选通道
R-->>A: 标准通道
A->>S: 分页(count=2400 → 3 页)
S->>P: 并发取 3 个连接
P->>P: 健康分 + EWMA 延迟选路
P-->>S: 3 个连接
S->>S: 并行拉取 → 按序拼接
S-->>A: 完整 bars
A->>C: 写入内存 + 磁盘
A-->>U: 返回
end
```
关键点:
- **缓存查在选路之前**——命中就完全不走网络,所以重复请求是 0.016s 量级
- **single-flight 在缓存层**——同一个键的并发请求会合并成一次回源,其余等待结果
- **分页与选路分离**——`scheduler` 只管拆分与拼接,不知道通道差异;`pool` 只管给连接
## 三个设计约束
| 约束 | 原因 |
|---|---|
| **零运行时依赖** | 用 `socket` / `zlib` / `struct` / `sqlite3` / `asyncio` 全部搞定,避免依赖地狱和版本冲突 |
| **返回 `list[dataclass]`** | 不让调用方被 pandas 绑架;需要 DataFrame 自己转一行 |
| **API 向后兼容** | 一个数据类型收敛为一个跨市场统一方法;旧方法名保留为 deprecated 别名(1.0 移除),老代码在兼容窗口内仍可用 |
## 下一步
- [协议与命令](protocol.md) — 最底层在做什么
- [通道与数据源](routing.md) — 为什么有的请求走不同的服务器
- [连接池与缓存](cache-pool.md) — 性能来自哪里