Files

liaozhaorun 9965ce5706 refactor: 重构 API 接口模块，整合为 api_wrappers 目录结构

- 将独立 API 模块 (daily, stock_basic, trade_cal) 整合至 api_wrappers/
- 重写 sync.py 使用新的 wrapper 结构，支持更多同步功能
- 更新测试文件适配新的模块结构
- 添加 pytest.ini 配置文件

2026-02-21 03:43:30 +08:00

6.2 KiB

Raw Blame History

ProStock 数据接口封装规范

1. 概述

本文档定义了新增 Tushare API 接口封装的标准规范。所有非特殊接口必须遵循此规范，确保：

代码风格统一
自动 sync 支持
增量更新逻辑一致
减少存储写入压力

2. 接口分类

2.1 特殊接口（不参与统一 sync）

以下接口有独立的同步逻辑，不参与自动 sync 机制：

接口类型	示例	说明
交易日历	`trade_cal`	全局数据，按日期范围获取
股票基础信息	`stock_basic`	一次性全量获取，CSV 存储
辅助数据	行业分类、概念分类	低频更新，独立管理

2.2 标准接口（必须遵循本规范）

所有按股票或按日期获取的因子数据、行情数据、财务数据等，必须遵循本规范。

3. 文件结构要求

3.1 文件命名

{data_type}.py

示例：daily.py、moneyflow.py、limit_list.py

3.2 文件位置

所有接口文件必须位于 src/data/ 目录下。

3.3 导出要求

新接口必须在 src/data/__init__.py 中导出：

from src.data.{module_name} import get_{data_type}

__all__ = [
    # ... 其他导出 ...
    "get_{data_type}",
]

4. 接口设计规范

4.1 数据获取函数签名要求

函数必须返回 pd.DataFrame，参数必须包含以下之一：

4.1.1 按日期获取的接口（优先）

适用于：涨跌停、龙虎榜、筹码分布等。

函数签名要求：

def get_{data_type}(
    trade_date: Optional[str] = None,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    ts_code: Optional[str] = None,
    # 其他可选参数...
) -> pd.DataFrame:

要求：

优先使用 trade_date 获取单日全市场数据
支持 start_date + end_date 获取区间数据
ts_code 作为可选过滤参数

4.1.2 按股票获取的接口

适用于：日线行情、资金流向等。

函数签名要求：

def get_{data_type}(
    ts_code: str,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    # 其他可选参数...
) -> pd.DataFrame:

4.2 文档字符串要求

函数必须包含 Google 风格的完整文档字符串，包含：

函数功能描述
Args 部分：所有参数说明
Returns 部分：返回的 DataFrame 包含的字段说明
Example 部分：使用示例

4.3 日期格式要求

所有日期参数和返回值使用 YYYYMMDD 字符串格式
统一使用 trade_date 作为日期字段名
如果 API 返回其他日期字段名（如 date、end_date），必须在返回前重命名为 trade_date

4.4 股票代码要求

统一使用 ts_code 作为股票代码字段名
格式：{code}.{exchange}，如 000001.SZ、600000.SH

4.5 令牌桶限速要求

所有 API 调用必须通过 TushareClient，自动满足令牌桶限速要求。

5. Sync 集成规范

5.1 DATASET_CONFIG 注册要求

新接口必须在 DataSync.DATASET_CONFIG 中注册，配置项：

"{new_data_type}": {
    "api_name": "{tushare_api_name}",  # Tushare API 名称
    "fetch_by": "date",  # "date" 或 "stock"
    "date_field": "trade_date",
    "key_fields": ["ts_code", "trade_date"],  # 用于去重的主键
}

5.2 fetch_by 取值规则

优先使用 "date"：如果 API 支持按日期获取全市场数据
仅当 API 不支持按日期获取时才使用 "stock"

5.3 sync 方法要求

必须实现对应的 sync 方法或复用通用方法：

def sync_{data_type}(self, force_full: bool = False) -> pd.DataFrame:
    """Sync {数据描述}。"""
    return self.sync_dataset("{data_type}", force_full)

同时提供便捷函数：

def sync_{data_type}(force_full: bool = False) -> pd.DataFrame:
    """Sync {数据描述}。"""
    sync_manager = DataSync()
    return sync_manager.sync_{data_type}(force_full)

5.4 增量更新要求

必须实现增量更新逻辑（自动检查本地最新日期）
使用 force_full 参数支持强制全量同步

6. 存储规范

6.1 存储方式

所有数据通过 Storage 类进行 HDF5 存储。

6.2 写入策略

要求：所有数据在请求完成后一次性写入，而非逐条写入。

6.3 去重要求

使用 key_fields 配置的字段进行去重，默认使用 ["ts_code", "trade_date"]。

7. 测试规范

7.1 测试文件要求

必须创建对应的测试文件：tests/test_{data_type}.py

7.2 测试覆盖要求

测试按日期获取
测试按股票获取（如果支持）
必须 mock TushareClient
测试覆盖正常和异常情况

8. 新增接口完整流程

8.1 创建接口文件

在 src/data/ 下创建 {data_type}.py
实现数据获取函数，遵循第 4 节规范

8.2 注册 sync 支持

在 sync.py 的 DataSync.DATASET_CONFIG 中注册
实现对应的 sync 方法
提供便捷函数

8.3 更新导出

在 src/data/__init__.py 中导出接口函数。

8.4 创建测试

创建 tests/test_{data_type}.py，覆盖关键场景。

9. 检查清单

9.1 文件结构

文件位于 src/data/{data_type}.py
已更新 src/data/__init__.py 导出公共接口
已创建 tests/test_{data_type}.py 测试文件

9.2 接口实现

数据获取函数使用 TushareClient
函数包含完整的 Google 风格文档字符串
日期参数使用 YYYYMMDD 格式
返回的 DataFrame 包含 ts_code 和 trade_date 字段
优先实现按日期获取的接口（如果 API 支持）

9.3 Sync 集成

已在 DataSync.DATASET_CONFIG 中注册
正确设置 fetch_by（"date" 或 "stock"）
正确设置 date_field 和 key_fields
已实现对应的 sync 方法或复用通用方法
增量更新逻辑正确（检查本地最新日期）

9.4 存储优化

所有数据一次性写入（非逐条）
使用 storage.save(mode="append") 进行增量保存
去重字段配置正确

9.5 测试

已编写单元测试
已 mock TushareClient
测试覆盖正常和异常情况

最后更新: 2026-02-01

6.2 KiB Raw Blame History Unescape Escape