Files
pytdxdata/docs/internals/architecture.md
T
openbot-coder 3e0beb27a6 release: v0.6.0(统一对外接口重构)
按「数据类型」合并同类查询接口:一个数据类型 = 一个方法,跨市场自动选路。

- 28 个统一接口(get_universe/get_quotes/get_bars/get_indicators/get_ticks/
  get_minutes/get_f10/get_file/get_boards/get_board_of/get_snapshot 等),
  标的统一字符串写法(sz000001 / hk00700 / usAAPL / cffex:IFL0);
  同名旧方法不再兼容 (market, code) 元组。
- 旧 51 个按通道/市场分裂的接口:33 个保留为 deprecated 别名(1.0 移除),
  18 个同名升级为统一接口。公开方法共 63 个。
- 新增库层标的解析 pytdxdata.symbols;数据模型追加 symbol/name/fields 兜底字段。
- 修复:分页器连接泄漏、日期区间 K线返回 0 条(偏移方向探测)、池子全冷却死等。
- 文档/README/SKILL/llms.txt 全量同步;新增 docs/refactor-audit.md 审查报告。
- 测试 127 个用例全绿(含 tests/test_all_interfaces.py 全 63 方法回归)。
2026-09-17 11:34:52 +08:00

4.6 KiB
Raw Blame History

架构总览

分层

调用链是单向的,每一层只依赖它下面的一层——想加新接口时先想清楚「这属于哪一层」。

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           # 服务器清单加载(servers.json)
├── 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 的完整路径

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 移除),老代码在兼容窗口内仍可用

下一步