easy-tdx 01001-源码分析-数据平台

评论
59 views

easy-tdx 库架构总览

easy-tdx 是一个基于 通达信（TDX）TCP 协议 的免费 A 股/港股/美股/期货行情数据客户端，提供 Python API、CLI 和 Web API 三种使用方式。

整体分层架构

┌─────────────────────────────────────────────────────────────┐
│                     用户接口层 (User Interface)               │
│  CLI (click) │ Python API │ Web API (FastAPI)                │
├─────────────────────────────────────────────────────────────┤
│                     业务逻辑层 (Business Logic)               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐  │
│  │ 行情查询   │ │ 缠论分析  │ │ 因子引擎  │ │ 回测引擎        │  │
│  │ (quotes)  │ │(chanlun) │ │ (factor) │ │ (backtest)     │  │
│  └─────┬────┘ └────┬─────┘ └────┬─────┘ └───────┬────────┘  │
│        └──────────┬─┴──────────┘                 │            │
│                   ▼                              │            │
│  ┌────────────────────────────┐    ┌────────────▼───────┐   │
│  │ 统一客户端 (UnifiedClient)  │◄───│ Portfolio/Screen   │   │
│  │ 自动路由 A股/扩展市场       │    │ 实时引擎/选股扫描   │   │
│  └────────────┬───────────────┘    └────────────────────┘   │
├───────────────┼─────────────────────────────────────────────┤
│           客户端层 (Clients)                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ TdxClient    │  │ MacClient    │  │ ExTdxClient      │   │
│  │ (基础行情PC)  │  │ (扩展行情)   │  │ (期货/衍生品)    │   │
│  │ 同步 + 异步   │  │ 同步 + 异步   │  │ 同步 + 异步       │   │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘   │
├─────────┼─────────────────┼───────────────────┼─────────────┤
│      命令层 (Commands)                                    │
│  security_bars │ quotes │ kline │ transaction │ fund_flow ...│
│  (每个命令 = build_request + parse_response)              │
├─────────┼─────────────────┼───────────────────┼─────────────┤
│      编解码层 (Codec)                                      │
│  frame │ price │ volume │ datetime │ financial │ block ...  │
├─────────┼─────────────────┼───────────────────┼─────────────┤
│      传输层 (Transport)                                     │
│  sync (socket) │ async (asyncio) │ 心跳保活                    │
└─────────────────────────────────────────────────────────────┘
                          │
                  通达信 TCP 服务器

核心模块说明

模块 路径 职责
传输层 transport/ 底层 TCP 连接管理，同步/异步双模式，心跳保活，服务器测速 (ping_all)
编解码层 codec/ 解析通达信二进制协议：帧头解析、价格/成交量/时间编码、压缩解压、财务数据/板块数据解析
命令层 commands/ 每个行情功能封装为一个 Command 类：build_request() 构造请求包 → parse_response() 解析响应
基础客户端 client.py TdxClient / AsyncTdxClient — PC 端协议，支持 K线/报价/分时/成交/资金流/财务等
扩展行情客户端 mac/client.py MacClient / AsyncMacClient — 移动端增强协议，支持港股/美股/期货/板块/资金流向/逐笔成交/集合竞价等
期货客户端 ex/client.py ExTdxClient — 期货/衍生品专用
统一客户端 unified.py UnifiedTdxClient — 自动路由 A 股→MacClient、扩展市场→MacExClient，一个入口搞定所有市场
离线数据 offline/ 读取本地通达信 VIP 文件（.dat/.zip），支持日线/分钟线/财务数据/除权信息
缠论分析 chanlun/ K线合并 → 分型识别 → 笔/线段/中枢 → 买卖点/背驰，完整的缠论技术分析实现
因子引擎 factor/ 多因子计算框架：技术因子/动量因子/质量因子/价值因子/波动率因子/成交量因子/缠论因子，支持单股+截面批量计算
回测引擎 backtest/ 向量化回测管线：策略信号 → 订单模拟 → 组合跟踪 → 绩效分析，含滑点/冲击成本/止损止盈/归因分析
CLI cli/ 基于 Click 的命令行工具，覆盖所有功能（quote/kline/tick/board/factor/backtest 等）
技术指标 indicator.py + MyTT.py 34 个内置技术指标（MACD/KDJ/RSI/BOLL 等）

核心数据流

用户调用 API (如 get_security_bars)
       │
       ▼
 TdxClient/MacClient (高层封装，重试/超时/pandas转换)
       │
       ▼
 XxxCommand.build_request() → 构造二进制请求包
       │
       ▼
 Transport (TCP 发送 → 接收帧头 → 接收body → 解压)
       │
       ▼
 XxxCommand.parse_response(body) → 解析为强类型数据对象
       │
       ▼
 返回 DataFrame / 数据模型给用户

设计亮点

  1. 双协议支持：同时实现 PC 端协议（TdxClient）和移动端增强协议（MacClient），后者数据更丰富（港股/美股/期货/板块/逐笔）
  2. 同步/异步双模式：所有客户端都提供 sync 和 async 两个版本
  3. 命令模式：每个行情功能独立为 Command 类，职责清晰，易于扩展新功能
  4. 统一入口：UnifiedTdxClient 自动根据市场类型路由到正确的底层客户端
  5. 开箱即用的量化工具链：缠论 + 多因子 + 回测 + 选股扫描，一站式解决
  6. 完全免费：无需注册/API Key，直连通达信公开服务器

我来帮你梳理整个项目的框架逻辑。首先让我查看项目的整体结构。

toolName: view_folder

status: success

/data/sourceCode/openCode/easy_tdx

toolName: file_search

status: success

file_pattern: easy_tdx/*/.py

让我尝试不同的方式来探索项目结构：

toolName: run_command

status: success

command: find /data/sourceCode/openCode/easy_tdx -type f -name "*.py" | head -50 undefined

让我查找项目的核心源代码文件，排除虚拟环境目录：

toolName: run_command

status: success

command: find /data/sourceCode/openCode/easy_tdx -type f -name ".py" -not -path "/.venv/*" | head -100 undefined

让我查看项目的核心源代码结构：

toolName: run_command

status: success

command: find /data/sourceCode/openCode/easy_tdx -type d -name "easy_tdx" | head -5 undefined

toolName: run_command

status: success

command: ls -la /data/sourceCode/openCode/easy_tdx/ undefined

让我查看核心源代码目录结构：

toolName: run_command

status: success

command: ls -la /data/sourceCode/openCode/easy_tdx/src/easy_tdx/ undefined

让我读取核心模块的入口文件和关键代码：

toolName: view_files

status: success

filePath: /data/sourceCode/openCode/easy_tdx/src/easy_tdx/init.py

toolName: view_files

status: success

filePath: /data/sourceCode/openCode/easy_tdx/src/easy_tdx/client.py

让我继续探索核心模块结构：

toolName: view_files

status: success

filePath: /data/sourceCode/openCode/easy_tdx/src/easy_tdx/unified.py

toolName: view_files

status: success

filePath: /data/sourceCode/openCode/easy_tdx/src/easy_tdx/mac/client.py

让我继续探索关键模块的结构：

toolName: run_command

status: success

command: ls -la /data/sourceCode/openCode/easy_tdx/src/easy_tdx/transport/ undefined

toolName: run_command

status: success

command: ls -la /data/sourceCode/openCode/easy_tdx/src/easy_tdx/commands/ undefined

基于对项目结构的深入分析，我来为你梳理 easy_tdx 项目的完整框架逻辑。

easy_tdx 项目框架逻辑总览

一、项目架构层次

┌─────────────────────────────────────────────────────────────────┐
│                      应用层 (Application)                       │
│    examples/      strategies/     cli/      run_all_strategies  │
├─────────────────────────────────────────────────────────────────┤
│                      接口层 (API Layer)                         │
│    UnifiedTdxClient      MacClient      TdxClient               │
│    (统一入口)           (MAC协议)      (标准协议)               │
├─────────────────────────────────────────────────────────────────┤
│                      业务层 (Business)                          │
│    backtest/    indicator.py    factor/    portfolio/          │
│    (回测引擎)    (技术指标)     (因子引擎)  (组合优化)          │
├─────────────────────────────────────────────────────────────────┤
│                      协议层 (Protocol)                          │
│    commands/       mac/commands      ex/                       │
│    (标准命令)      (MAC命令)       (扩展市场)                   │
├─────────────────────────────────────────────────────────────────┤
│                      传输层 (Transport)                         │
│    transport/sync.py      transport/async_.py                  │
│    (同步TCP)              (异步TCP)                            │
├─────────────────────────────────────────────────────────────────┤
│                      编解码层 (Codec)                           │
│    codec/block    codec/financial    codec/bitmap              │
│    (板块数据)      (财务数据)        (字段映射)                 │
├─────────────────────────────────────────────────────────────────┤
│                      数据模型层 (Models)                        │
│    models/bar    models/finance    models/security             │
│    (K线模型)      (财务模型)        (证券模型)                 │
└─────────────────────────────────────────────────────────────────┘

二、核心模块详解

1. 客户端层（Client Layer）

客户端 协议 端口 功能范围
TdxClient 标准TCP协议 7709 A股基础行情（K线、分时、财务、板块）
MacClient MAC协议 7709 A股增强行情（实时报价、Tick、监控）
MacExClient MAC扩展协议 7727 港股、美股等扩展市场
UnifiedTdxClient 自动路由 双端口 统一入口，同时访问A股和扩展市场

客户端设计模式： - 支持 with 上下文管理器，自动管理连接生命周期 - 支持同步/异步两种版本（TdxClient / AsyncTdxClient） - 自动优选最低延迟服务器（from_best_host()）

2. 命令层（Command Layer）

标准协议命令（commands/）： - security_bars.py - K线数据获取 - security_quotes.py - 实时报价 - security_list.py - 证券列表 - transaction.py - 逐笔成交 - finance_info.py - 财务数据 - block_info.py - 板块信息 - fund_flow.py - 资金流向

MAC协议命令（mac/commands/）： - SymbolQuotesCmd - 批量报价 - SymbolBarCmd - K线数据 - SymbolTickChartCmd - 分时图 - SymbolTransactionCmd - 成交明细 - BoardListCmd - 板块列表 - UnusualCmd - 异动监控

3. 传输层（Transport Layer）

# 核心职责：TCP连接管理、数据包收发、心跳保活

transport/
├── sync.py        # 同步TCP连接 (TdxConnection)
│   ├── connect()
│   ├── send()
│   ├── recv()
│   └── close()
└── async_.py      # 异步TCP连接 (AsyncTdxConnection)
    ├── connect()
    ├── send()
    ├── recv()
    └── close()

关键特性： - 自动重连机制 - 心跳保活（默认15秒） - 超时控制 - 连接池管理

4. 编解码层（Codec Layer）

codec/
├── block.py       # 板块数据解析 (block_zs.dat, block_gn.dat)
├── financial.py   # 财务数据解析
├── industry.py    # 行业分类解析
├── bitmap.py      # 字段位图映射 (MAC协议)
├── price_rules.py # 涨跌停规则计算
└── frame.py       # 通用帧解码

5. 数据模型层（Models Layer）

models/
├── bar.py         # SecurityBar, MinuteBar (K线/分钟线)
├── enums.py       # Market, KlineCategory, Period (枚举)
├── finance.py     # FinanceInfo, XdxrRecord (财务/除权)
├── security.py    # SecurityInfo, SecurityQuote (证券信息)
├── stats.py       # FundFlow, MarketStat (统计数据)
└── timeseries.py  # TransactionRecord (时序数据)

三、数据流架构

用户请求 → 客户端层 → 命令层 → 传输层 → 通达信服务器
                                      ↓
服务器响应 → 传输层 → 编解码层 → 数据模型 → DataFrame返回

完整请求流程示例：

# 1. 用户调用
with TdxClient.from_best_host() as client:
    df = client.get_security_bars(Market.SH, "600519", KlineCategory.DAY, 0, 10)

# 2. 客户端层：构建命令
cmd = GetSecurityBarsCmd(market, code, category, start, count)

# 3. 传输层：发送请求
response = connection.send(cmd.encode())

# 4. 编解码层：解析响应
bars = parse_security_bars(response)

# 5. 返回DataFrame
return pd.DataFrame(bars)

四、核心功能模块

1. 行情数据获取

功能 方法 说明
K线数据 get_security_bars() 支持1分钟~年线11种周期
实时报价 get_security_quotes() 批量获取多只股票
分时数据 get_history_minute_time_data() 历史某日分时
逐笔成交 get_transaction_data() 当日成交明细
财务数据 get_finance_info() 股本、资产负债、利润

2. 板块与行业

功能 方法 说明
板块列表 get_block_info() 行业/概念/风格板块
成分股 get_board_members() 获取板块包含的股票
所属板块 get_belong_board() 股票属于哪些板块

3. 技术指标计算

# 内置30+指标：MACD, KDJ, RSI, BOLL, ATR, CCI, WR...
from easy_tdx.indicator import compute_indicators

df = c.get_stock_kline_with_indicators(
    Market.SH, "600519", 
    indicators=["MACD", "KDJ", "RSI"],
    count=30
)

4. 高级回测引擎

from easy_tdx.backtest import BacktestEngine, Strategy

class MyStrategy(Strategy):
    def init(self):
        self.ma10 = self.I(MA, self.data.close, 10)

    def next(self):
        if self.ma10 crosses above self.data.close:
            self.buy()

# 支持多种滑点模型和执行算法
engine = BacktestEngine(
    MyStrategy,
    slippage_model=SquareRootSlippage(),
    execution_model=TWAPExecution()
)
result = engine.run(df)

5. 扩展市场支持

# 港股、美股等扩展市场
from easy_tdx import ExMarket, UnifiedTdxClient

with UnifiedTdxClient() as client:
    # A股
    df_a = client.get_stock_kline(Market.SH, "600519", Period.DAILY)
    # 港股
    df_hk = client.goods_kline(ExMarket.HK_MAIN_BOARD, "00700", Period.DAILY)
    # 美股
    df_us = client.goods_kline(ExMarket.US_STOCK, "TSLA", Period.DAILY)

五、配置与基础设施

# 配置文件：~/.easy_tdx/config.json
{
    "best_host": "180.153.18.170:7709",
    "timeout": 15,
    "heartbeat_interval": 15
}

# 服务器列表
KNOWN_HOSTS = [
    "180.153.18.170:7709",
    "119.147.212.81:7709",
    # ... 更多服务器
]

服务器优选机制： 1. ping_all() 并发测试所有候选服务器延迟 2. 选择延迟最低的服务器 3. 自动保存到配置文件 4. 后续连接优先使用最佳服务器

六、扩展能力

1. 策略框架（strategies/）

  • 内置15+经典策略：MA双均线、MACD交叉、RSI反转、布林带突破等
  • 支持策略组合回测

2. 因子引擎（factor/）

  • 因子计算、IC分析、因子正交化
  • 支持自定义因子

3. 组合优化（portfolio/）

  • 风险模型、约束优化、权重分配

4. 缠论分析（chanlun/）

  • 自动笔段划分、中枢识别

七、设计特点总结

特性 实现方式
协议抽象 命令模式封装协议细节
连接管理 上下文管理器自动生命周期
异步支持 同步/异步双版本客户端
自动路由 UnifiedTdxClient 统一入口
数据标准化 统一返回 DataFrame
可扩展性 插件化策略、因子系统
稳定性 自动重连、心跳保活、超时控制

该框架通过分层架构实现了协议抽象与业务逻辑的解耦，通过命令模式封装了通达信协议细节，通过统一客户端提供了简洁的API入口，是一个设计精良的A股行情数据获取与分析框架。