805 lines
23 KiB
Markdown
805 lines
23 KiB
Markdown
# ProStock 数据接口封装规范
|
||
## 1. 概述
|
||
本文档定义了新增 Tushare API 接口封装的标准规范。所有非特殊接口必须遵循此规范，确保：
|
||
- 代码风格统一
|
||
- 自动 sync 支持
|
||
- 增量更新逻辑一致
|
||
- 减少存储写入压力
|
||
- 类型安全（强制类型提示）
|
||
|
||
### 1.1 技术栈
|
||
|
||
- **存储层**: DuckDB（高性能嵌入式 OLAP 数据库）
|
||
- **数据格式**: Pandas DataFrame / Polars DataFrame
|
||
- **速率限制**: 令牌桶算法（TokenBucketRateLimiter）
|
||
- **并发**: ThreadPoolExecutor 多线程
|
||
- **类型系统**: Python 3.10+ 类型提示
|
||
|
||
### 1.2 自动化支持
|
||
|
||
项目提供 `prostock-api-interface` Skill 来自动化接口封装流程。在 `api.md` 中定义接口后，调用该 Skill 可自动生成：
|
||
- 数据模块文件（`src/data/api_wrappers/api_{data_type}.py`）
|
||
- 数据库表管理配置
|
||
- 测试文件（`tests/test_{data_type}.py`）
|
||
|
||
## 2. 接口分类
|
||
|
||
### 2.1 特殊接口（不参与统一 sync）
|
||
|
||
以下接口有独立的同步逻辑，不参与自动 sync 机制：
|
||
|
||
| 接口类型 | 文件名 | 说明 |
|
||
|---------|--------|------|
|
||
| 交易日历 | `api_trade_cal.py` | 全局数据，按日期范围获取，使用 HDF5 缓存 |
|
||
| 股票基础信息 | `api_stock_basic.py` | 一次性全量获取，CSV 存储 |
|
||
| 辅助数据 | `api_industry`, `api_concept` | 低频更新，独立管理 |
|
||
|
||
### 2.2 标准接口（必须遵循本规范）
|
||
|
||
所有按股票或按日期获取的因子数据、行情数据、财务数据等，必须遵循本规范：
|
||
|
||
- 按日期获取：**优先选择**，支持全市场批量获取
|
||
- 按股票获取：仅当 API 不支持按日期获取时使用
|
||
|
||
## 3. 文件结构要求
|
||
|
||
### 3.1 文件命名
|
||
|
||
```
|
||
api_{data_type}.py
|
||
```
|
||
|
||
- 示例：`api_daily.py`、`api_moneyflow.py`、`api_limit_list.py`
|
||
- **必须**以 `api_` 前缀开头
|
||
- 使用小写字母和下划线
|
||
|
||
### 3.2 文件位置
|
||
|
||
所有接口文件必须位于 `src/data/api_wrappers/` 目录下。
|
||
|
||
### 3.3 导出要求
|
||
|
||
新接口必须在 `src/data/api_wrappers/__init__.py` 中导出：
|
||
|
||
```python
|
||
from src.data.api_wrappers.api_{data_type} import get_{data_type}
|
||
__all__ = [
|
||
# ... 其他导出 ...
|
||
"get_{data_type}",
|
||
]
|
||
```
|
||
|
||
## 4. 接口设计规范
|
||
|
||
### 4.1 数据获取函数签名要求
|
||
|
||
函数必须返回 `pd.DataFrame`，参数必须包含以下之一：
|
||
|
||
#### 4.1.1 按日期获取的接口（优先）
|
||
|
||
适用于：涨跌停、龙虎榜、筹码分布、每日指标等。
|
||
|
||
**函数签名要求**：
|
||
|
||
```python
|
||
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` 作为可选过滤参数
|
||
- **性能优势**: 单日全市场数据一次 API 调用即可完成
|
||
|
||
#### 4.1.2 按股票获取的接口
|
||
|
||
适用于：日线行情、资金流向等。
|
||
|
||
**函数签名要求**：
|
||
|
||
```python
|
||
def get_{data_type}(
|
||
ts_code: str,
|
||
start_date: Optional[str] = None,
|
||
end_date: Optional[str] = None,
|
||
# 其他可选参数...
|
||
) -> pd.DataFrame:
|
||
```
|
||
|
||
**要求**：
|
||
- `ts_code` 为必选参数
|
||
- 需要遍历所有股票获取全市场数据
|
||
|
||
### 4.2 文档字符串要求
|
||
|
||
函数必须包含 **Google 风格**的完整文档字符串，包含：
|
||
|
||
```python
|
||
def get_{data_type}(...) -> pd.DataFrame:
|
||
"""Fetch {数据描述} from Tushare.
|
||
|
||
This interface retrieves {详细描述}.
|
||
|
||
Args:
|
||
ts_code: Stock code (e.g., '000001.SZ', '600000.SH')
|
||
trade_date: Specific trade date (YYYYMMDD format)
|
||
start_date: Start date (YYYYMMDD format)
|
||
end_date: End date (YYYYMMDD format)
|
||
# 其他参数...
|
||
|
||
Returns:
|
||
pd.DataFrame with columns:
|
||
- ts_code: Stock code
|
||
- trade_date: Trade date (YYYYMMDD)
|
||
- {其他字段}: {字段描述}
|
||
|
||
Example:
|
||
>>> # Get single date data for all stocks
|
||
>>> data = get_{data_type}(trade_date='20240101')
|
||
>>>
|
||
>>> # Get date range data
|
||
>>> data = get_{data_type}(start_date='20240101', end_date='20240131')
|
||
>>>
|
||
>>> # Get specific stock data
|
||
>>> data = get_{data_type}(ts_code='000001.SZ', trade_date='20240101')
|
||
"""
|
||
```
|
||
|
||
### 4.3 日期格式要求
|
||
|
||
- 所有日期参数使用 **YYYYMMDD** 字符串格式
|
||
- 统一使用 `trade_date` 作为日期字段名
|
||
- 如果 API 返回其他日期字段名（如 `date`、`end_date`），必须在返回前重命名为 `trade_date`：
|
||
|
||
```python
|
||
if "date" in data.columns:
|
||
data = data.rename(columns={"date": "trade_date"})
|
||
```
|
||
|
||
### 4.4 股票代码要求
|
||
- 统一使用 `ts_code` 作为股票代码字段名
|
||
- 格式：`{code}.{exchange}`，如 `000001.SZ`、`600000.SH`
|
||
- 确保返回的 DataFrame 包含 `ts_code` 列
|
||
|
||
### 4.5 字段名规范（重要）
|
||
|
||
**必须使用 Tushare API 返回的原始字段名，禁止进行不必要的重命名。**
|
||
|
||
这是为了确保：
|
||
- 代码可读性：使用 API 文档中的标准字段名
|
||
- 维护简单性：避免因字段名映射导致的混淆和错误
|
||
- 数据一致性：数据库字段名与 API 返回字段名保持一致
|
||
|
||
**禁止做法**（以下代码是不允许的）：
|
||
```python
|
||
# 错误：将 Tushare 的原始字段名改为自定义名称
|
||
column_mapping = {
|
||
"turnover_rate": "tor", # 不要这样做
|
||
"volume_ratio": "vr", # 不要这样做
|
||
}
|
||
data = data.rename(columns=column_mapping)
|
||
```
|
||
|
||
**正确做法**（直接使用原始字段名）：
|
||
```python
|
||
# 正确：保留 Tushare 返回的原始字段名
|
||
# Tushare 返回 'turnover_rate'，就直接使用 'turnover_rate'
|
||
# Tushare 返回 'volume_ratio'，就直接使用 'volume_ratio'
|
||
|
||
# 表结构定义应使用原始字段名
|
||
TABLE_SCHEMA = {
|
||
"ts_code": "VARCHAR(16) NOT NULL",
|
||
"trade_date": "DATE NOT NULL",
|
||
"turnover_rate": "DOUBLE", # 使用原始字段名
|
||
"volume_ratio": "DOUBLE", # 使用原始字段名
|
||
# ... 其他字段
|
||
}
|
||
```
|
||
|
||
**例外情况**（允许重命名）：
|
||
- 日期字段：如果 API 返回 `date`，应重命名为 `trade_date` 以符合项目规范
|
||
- 必须重命名的情况：如果两个不同 API 返回相同含义但不同名称的字段，需要统一命名
|
||
|
||
**教训**（真实案例）：
|
||
`api_pro_bar.py` 早期版本将 `turnover_rate` 重命名为 `tor`，`volume_ratio` 重命名为 `vr`，
|
||
导致：
|
||
1. 代码与 Tushare 文档不一致，增加学习成本
|
||
2. 数据库字段名与 API 字段名不一致，造成混淆
|
||
3. 需要额外的数据迁移脚本修复历史数据
|
||
|
||
### 4.6 令牌桶限速要求
|
||
|
||
所有 API 调用必须通过 `TushareClient`，自动满足令牌桶限速要求。
|
||
|
||
#### 4.6.1 基本用法（单线程场景）
|
||
|
||
```python
|
||
from src.data.client import TushareClient
|
||
|
||
def get_{data_type}(...) -> pd.DataFrame:
|
||
client = TushareClient()
|
||
|
||
# Build parameters
|
||
params = {}
|
||
if trade_date:
|
||
params["trade_date"] = trade_date
|
||
if ts_code:
|
||
params["ts_code"] = ts_code
|
||
# ...
|
||
|
||
# Fetch data (rate limiting handled automatically)
|
||
data = client.query("{api_name}", **params)
|
||
|
||
return data
|
||
```
|
||
|
||
**注意**: `TushareClient` 自动处理：
|
||
- 令牌桶速率限制
|
||
- API 重试逻辑（指数退避）
|
||
- 配置加载
|
||
|
||
#### 4.6.2 多线程/并发场景（重要）
|
||
|
||
**问题**: 多线程并发调用时，如果每个线程创建独立的 `TushareClient` 实例，每个实例会有独立的限流器，导致实际并发请求数 = 线程数 × 单个限流器速率，**限流失效**。
|
||
|
||
**解决方案**: 数据获取函数必须接受可选的 `client` 参数，Sync 类传递共享的客户端实例。
|
||
|
||
**数据获取函数签名**（必须支持 client 参数）：
|
||
|
||
```python
|
||
from src.data.client import TushareClient
|
||
from typing import Optional
|
||
|
||
def get_{data_type}(
|
||
ts_code: str,
|
||
start_date: Optional[str] = None,
|
||
end_date: Optional[str] = None,
|
||
client: Optional[TushareClient] = None, # 新增：可选客户端参数
|
||
) -> pd.DataFrame:
|
||
"""Fetch {数据描述} from Tushare.
|
||
|
||
Args:
|
||
ts_code: Stock code
|
||
start_date: Start date (YYYYMMDD)
|
||
end_date: End date (YYYYMMDD)
|
||
client: Optional TushareClient instance for shared rate limiting.
|
||
If None, creates a new client. For concurrent sync operations,
|
||
pass a shared client to ensure proper rate limiting.
|
||
|
||
Returns:
|
||
pd.DataFrame with data
|
||
"""
|
||
client = client or TushareClient() # 如果没有提供则创建新实例
|
||
|
||
params = {"ts_code": ts_code}
|
||
if start_date:
|
||
params["start_date"] = start_date
|
||
if end_date:
|
||
params["end_date"] = end_date
|
||
|
||
data = client.query("{api_name}", **params)
|
||
return data
|
||
```
|
||
|
||
**Sync 类实现**（必须传递共享 client）：
|
||
|
||
```python
|
||
from concurrent.futures import ThreadPoolExecutor
|
||
from src.data.client import TushareClient
|
||
from src.data.storage import ThreadSafeStorage
|
||
|
||
class {DataType}Sync:
|
||
def __init__(self, max_workers: Optional[int] = None):
|
||
self.storage = ThreadSafeStorage()
|
||
self.client = TushareClient() # 共享客户端实例
|
||
self.max_workers = max_workers or 10
|
||
|
||
def sync_single_stock(
|
||
self,
|
||
ts_code: str,
|
||
start_date: str,
|
||
end_date: str,
|
||
) -> pd.DataFrame:
|
||
"""同步单只股票的数据。"""
|
||
# 传递共享 client 以确保多线程下的限流生效
|
||
data = get_{data_type}(
|
||
ts_code=ts_code,
|
||
start_date=start_date,
|
||
end_date=end_date,
|
||
client=self.client, # 关键：传递共享客户端
|
||
)
|
||
return data
|
||
|
||
def sync_all(self, ...):
|
||
# 使用 ThreadPoolExecutor 并发执行
|
||
with ThreadPoolExecutor(max_workers=self.max_workers) as executor:
|
||
# 所有线程共享 self.client，限流器正常工作
|
||
...
|
||
```
|
||
|
||
**关键规则**:
|
||
1. 所有按股票获取的接口必须接受 `client: Optional[TushareClient] = None` 参数
|
||
2. Sync 类在 `__init__` 中创建 `self.client = TushareClient()`
|
||
3. Sync 类的同步方法必须将 `self.client` 传递给数据获取函数
|
||
4. 数据获取函数使用 `client = client or TushareClient()` 模式
|
||
|
||
所有 API 调用必须通过 `TushareClient`，自动满足令牌桶限速要求：
|
||
|
||
```python
|
||
from src.data.client import TushareClient
|
||
|
||
def get_{data_type}(...) -> pd.DataFrame:
|
||
client = TushareClient()
|
||
|
||
# Build parameters
|
||
params = {}
|
||
if trade_date:
|
||
params["trade_date"] = trade_date
|
||
if ts_code:
|
||
params["ts_code"] = ts_code
|
||
# ...
|
||
|
||
# Fetch data (rate limiting handled automatically)
|
||
data = client.query("{api_name}", **params)
|
||
|
||
return data
|
||
```
|
||
|
||
**注意**: `TushareClient` 自动处理：
|
||
- 令牌桶速率限制
|
||
- API 重试逻辑（指数退避）
|
||
- 配置加载
|
||
|
||
## 5. DuckDB 存储规范
|
||
|
||
### 5.0 强制落库要求（关键）
|
||
|
||
**所有封装的 API 接口必须将数据落库到 DuckDB。**
|
||
|
||
这是数据同步的核心原则，确保：
|
||
- 数据持久化：避免重复调用 API，节省 token
|
||
- 增量更新：基于本地数据状态进行智能同步
|
||
- 数据一致性：所有数据都有统一的存储和访问方式
|
||
- 离线可用：数据可以在没有网络的情况下查询
|
||
|
||
**落库检查清单**：
|
||
- [ ] 在 `storage.py` 的 `_init_db()` 方法中创建对应的表
|
||
- [ ] 表结构必须包含 `ts_code` 和 `trade_date` 作为主键
|
||
- [ ] 实现 `sync_{data_type}()` 函数，使用 `Storage` 或 `ThreadSafeStorage` 保存数据
|
||
- [ ] 确保同步逻辑正确处理增量更新
|
||
|
||
**反例警示**：`api_pro_bar.py` 早期版本虽然实现了 `sync_pro_bar()` 函数，但忘记在 `storage.py` 中创建 `pro_bar` 表，导致同步的数据无法落库，造成 token 浪费和数据丢失。
|
||
|
||
### 5.1 存储架构
|
||
|
||
### 5.1 存储架构
|
||
|
||
项目使用 **DuckDB** 作为持久化存储：
|
||
|
||
- **单例模式**: `Storage` 类确保单一数据库连接
|
||
- **线程安全**: `ThreadSafeStorage` 提供并发写入支持
|
||
- **UPSERT 支持**: `INSERT OR REPLACE` 自动处理重复数据
|
||
- **查询下推**: WHERE 条件在数据库层过滤
|
||
|
||
### 5.2 表结构设计
|
||
|
||
每个数据类型对应一个 DuckDB 表：
|
||
|
||
```sql
|
||
CREATE TABLE {data_type} (
|
||
ts_code VARCHAR(16) NOT NULL,
|
||
trade_date DATE NOT NULL,
|
||
# 其他字段...
|
||
PRIMARY KEY (ts_code, trade_date)
|
||
);
|
||
|
||
CREATE INDEX idx_{data_type}_date_code ON {data_type}(trade_date, ts_code);
|
||
```
|
||
|
||
**主键要求**:
|
||
- 必须包含 `ts_code` 和 `trade_date`
|
||
- 使用 UPSERT 确保幂等性
|
||
|
||
### 5.3 存储写入策略
|
||
|
||
**批量写入模式**（推荐用于多线程场景）：
|
||
|
||
```python
|
||
from src.data.storage import ThreadSafeStorage
|
||
|
||
def sync_{data_type}(self, ...):
|
||
storage = ThreadSafeStorage()
|
||
|
||
# 收集数据到队列（不立即写入）
|
||
for data_chunk in data_generator:
|
||
storage.queue_save("{data_type}", data_chunk)
|
||
|
||
# 批量写入所有数据
|
||
storage.flush()
|
||
```
|
||
|
||
**直接写入模式**（适用于简单场景）：
|
||
|
||
```python
|
||
from src.data.storage import Storage
|
||
|
||
storage = Storage()
|
||
storage.save("{data_type}", data, mode="append")
|
||
```
|
||
|
||
### 5.4 数据类型映射
|
||
|
||
标准字段类型映射（`DEFAULT_TYPE_MAPPING`）：
|
||
|
||
```python
|
||
DEFAULT_TYPE_MAPPING = {
|
||
"ts_code": "VARCHAR(16)",
|
||
"trade_date": "DATE",
|
||
"open": "DOUBLE",
|
||
"high": "DOUBLE",
|
||
"low": "DOUBLE",
|
||
"close": "DOUBLE",
|
||
"vol": "DOUBLE",
|
||
"amount": "DOUBLE",
|
||
# ... 其他字段
|
||
}
|
||
```
|
||
|
||
## 6. Sync 集成规范
|
||
|
||
### 6.1 使用 db_manager 进行同步
|
||
|
||
项目使用 `db_manager` 模块提供高级同步功能：
|
||
|
||
```python
|
||
from src.data.db_manager import SyncManager, ensure_table
|
||
|
||
def sync_{data_type}(force_full: bool = False) -> pd.DataFrame:
|
||
"""Sync {数据描述} to DuckDB."""
|
||
|
||
manager = SyncManager()
|
||
|
||
# 确保表存在
|
||
ensure_table("{data_type}", schema={
|
||
"ts_code": "VARCHAR(16)",
|
||
"trade_date": "DATE",
|
||
# ... 其他字段
|
||
})
|
||
|
||
# 执行同步
|
||
result = manager.sync(
|
||
table_name="{data_type}",
|
||
fetch_func=get_{data_type},
|
||
start_date=start_date,
|
||
end_date=end_date,
|
||
force_full=force_full,
|
||
)
|
||
|
||
return result
|
||
```
|
||
|
||
### 6.2 增量更新逻辑
|
||
|
||
`SyncManager` 自动处理增量更新：
|
||
|
||
1. **检查本地最新日期**: 从 DuckDB 获取 `MAX(trade_date)`
|
||
2. **获取交易日历**: 从 `api_trade_cal` 获取交易日范围
|
||
3. **计算需要同步的日期**: 本地最新日期 + 1 到最新交易日
|
||
4. **批量获取数据**: 按日期或按股票获取
|
||
5. **批量写入**: 使用 `ThreadSafeStorage` 队列写入
|
||
|
||
### 6.3 便捷函数
|
||
|
||
每个接口必须提供顶层便捷函数：
|
||
|
||
```python
|
||
def sync_{data_type}(force_full: bool = False) -> pd.DataFrame:
|
||
"""Sync {数据描述} to local storage.
|
||
|
||
Args:
|
||
force_full: If True, force full reload from 20180101
|
||
|
||
Returns:
|
||
DataFrame with synced data
|
||
"""
|
||
# Implementation...
|
||
```
|
||
|
||
## 7. 代码模板
|
||
|
||
### 7.1 按日期获取接口模板
|
||
|
||
```python
|
||
"""{数据描述} interface.
|
||
|
||
Fetch {数据描述} data from Tushare.
|
||
"""
|
||
|
||
import pandas as pd
|
||
from typing import Optional
|
||
from src.data.client import TushareClient
|
||
|
||
|
||
def get_{data_type}(
|
||
trade_date: Optional[str] = None,
|
||
start_date: Optional[str] = None,
|
||
end_date: Optional[str] = None,
|
||
ts_code: Optional[str] = None,
|
||
client: Optional[TushareClient] = None, # 关键：可选客户端参数，用于共享速率限制
|
||
) -> pd.DataFrame:
|
||
"""Fetch {数据描述} from Tushare.
|
||
|
||
This interface retrieves {详细描述}.
|
||
|
||
Args:
|
||
trade_date: Specific trade date (YYYYMMDD format)
|
||
start_date: Start date (YYYYMMDD format)
|
||
end_date: End date (YYYYMMDD format)
|
||
ts_code: Stock code filter (optional)
|
||
client: Optional TushareClient instance for shared rate limiting.
|
||
If None, creates a new client. For concurrent sync operations,
|
||
pass a shared client to ensure proper rate limiting.
|
||
|
||
Returns:
|
||
pd.DataFrame with columns:
|
||
- ts_code: Stock code
|
||
- trade_date: Trade date (YYYYMMDD)
|
||
- {字段1}: {描述}
|
||
- {字段2}: {描述}
|
||
|
||
Example:
|
||
>>> # Get all stocks for a single date
|
||
>>> data = get_{data_type}(trade_date='20240101')
|
||
>>>
|
||
>>> # Get date range data
|
||
>>> data = get_{data_type}(start_date='20240101', end_date='20240131')
|
||
"""
|
||
client = client or TushareClient() # 如果没有提供则创建新实例
|
||
|
||
# Build parameters
|
||
params = {}
|
||
if trade_date:
|
||
params["trade_date"] = trade_date
|
||
if start_date:
|
||
params["start_date"] = start_date
|
||
if end_date:
|
||
params["end_date"] = end_date
|
||
if ts_code:
|
||
params["ts_code"] = ts_code
|
||
|
||
# Fetch data
|
||
data = client.query("{tushare_api_name}", **params)
|
||
|
||
# Rename date column if needed
|
||
if "date" in data.columns:
|
||
data = data.rename(columns={"date": "trade_date"})
|
||
|
||
return data
|
||
```
|
||
|
||
### 7.2 按股票获取接口模板
|
||
|
||
```python
|
||
"""{数据描述} interface.
|
||
|
||
Fetch {数据描述} data from Tushare (per stock).
|
||
"""
|
||
|
||
import pandas as pd
|
||
from typing import Optional
|
||
from src.data.client import TushareClient
|
||
|
||
|
||
def get_{data_type}(
|
||
ts_code: str,
|
||
start_date: Optional[str] = None,
|
||
end_date: Optional[str] = None,
|
||
client: Optional[TushareClient] = None, # 关键：可选客户端参数，用于共享速率限制
|
||
) -> pd.DataFrame:
|
||
"""Fetch {数据描述} for a specific stock.
|
||
|
||
Args:
|
||
ts_code: Stock code (e.g., '000001.SZ')
|
||
start_date: Start date (YYYYMMDD format)
|
||
end_date: End date (YYYYMMDD format)
|
||
client: Optional TushareClient instance for shared rate limiting.
|
||
If None, creates a new client. For concurrent sync operations,
|
||
pass a shared client to ensure proper rate limiting.
|
||
|
||
Returns:
|
||
pd.DataFrame with {数据描述} data
|
||
"""
|
||
client = client or TushareClient() # 如果没有提供则创建新实例
|
||
|
||
params = {"ts_code": ts_code}
|
||
if start_date:
|
||
params["start_date"] = start_date
|
||
if end_date:
|
||
params["end_date"] = end_date
|
||
|
||
data = client.query("{tushare_api_name}", **params)
|
||
|
||
return data
|
||
```
|
||
|
||
### 7.3 Sync 函数模板
|
||
|
||
```python
|
||
from src.data.db_manager import SyncManager, ensure_table
|
||
from src.data.api_wrappers import get_{data_type}
|
||
|
||
|
||
def sync_{data_type}(force_full: bool = False) -> pd.DataFrame:
|
||
"""Sync {数据描述} to local DuckDB storage.
|
||
|
||
Args:
|
||
force_full: If True, force full reload from 20180101
|
||
|
||
Returns:
|
||
DataFrame with synced data
|
||
"""
|
||
manager = SyncManager()
|
||
|
||
# Ensure table exists with proper schema
|
||
ensure_table("{data_type}", schema={
|
||
"ts_code": "VARCHAR(16)",
|
||
"trade_date": "DATE",
|
||
# Add other fields...
|
||
})
|
||
|
||
# Perform sync
|
||
result = manager.sync(
|
||
table_name="{data_type}",
|
||
fetch_func=get_{data_type},
|
||
force_full=force_full,
|
||
)
|
||
|
||
return result
|
||
```
|
||
|
||
## 8. 测试规范
|
||
|
||
### 8.1 测试文件要求
|
||
|
||
必须创建对应的测试文件：`tests/test_{data_type}.py`
|
||
|
||
### 8.2 测试覆盖要求
|
||
|
||
```python
|
||
import pytest
|
||
import pandas as pd
|
||
from unittest.mock import patch, MagicMock
|
||
from src.data.api_wrappers.api_{data_type} import get_{data_type}
|
||
|
||
|
||
class Test{DataType}:
|
||
"""Test suite for {data_type} API wrapper."""
|
||
|
||
@patch("src.data.api_wrappers.api_{data_type}.TushareClient")
|
||
def test_get_by_date(self, mock_client_class):
|
||
"""Test fetching data by date."""
|
||
# Setup mock
|
||
mock_client = MagicMock()
|
||
mock_client_class.return_value = mock_client
|
||
mock_client.query.return_value = pd.DataFrame({
|
||
"ts_code": ["000001.SZ"],
|
||
"trade_date": ["20240101"],
|
||
# ... other columns
|
||
})
|
||
|
||
# Test
|
||
result = get_{data_type}(trade_date="20240101")
|
||
|
||
# Assert
|
||
assert not result.empty
|
||
assert "ts_code" in result.columns
|
||
assert "trade_date" in result.columns
|
||
mock_client.query.assert_called_once()
|
||
|
||
@patch("src.data.api_wrappers.api_{data_type}.TushareClient")
|
||
def test_get_by_stock(self, mock_client_class):
|
||
"""Test fetching data by stock code."""
|
||
# Similar setup...
|
||
pass
|
||
|
||
@patch("src.data.api_wrappers.api_{data_type}.TushareClient")
|
||
def test_empty_response(self, mock_client_class):
|
||
"""Test handling empty response."""
|
||
mock_client = MagicMock()
|
||
mock_client_class.return_value = mock_client
|
||
mock_client.query.return_value = pd.DataFrame()
|
||
|
||
result = get_{data_type}(trade_date="20240101")
|
||
assert result.empty
|
||
```
|
||
|
||
### 8.3 Mock 规范
|
||
|
||
- 在导入位置打补丁：`patch('src.data.api_wrappers.api_{data_type}.TushareClient')`
|
||
- 测试正常和异常情况
|
||
- 验证参数传递正确
|
||
|
||
## 9. 使用 Skill 自动生成
|
||
|
||
### 9.1 准备工作
|
||
|
||
1. 在 `api.md` 中定义接口信息，包含：
|
||
- 接口名称和描述
|
||
- 输入参数（名称、类型、必选、描述）
|
||
- 输出参数（名称、类型、描述）
|
||
|
||
### 9.2 调用 Skill
|
||
|
||
告知 Claude 要封装的接口名称：
|
||
|
||
> "帮我封装 {data_type} 接口"
|
||
|
||
> "为 {data_type} 接口生成代码"
|
||
|
||
### 9.3 自动生成内容
|
||
|
||
Skill 会自动：
|
||
1. 解析 `api.md` 中的接口定义
|
||
2. 生成 `src/data/api_wrappers/api_{data_type}.py`
|
||
3. 更新 `src/data/api_wrappers/__init__.py` 导出
|
||
4. 生成 `tests/test_{data_type}.py` 测试文件
|
||
5. 提供 `sync_{data_type}()` 函数模板
|
||
|
||
## 10. 检查清单
|
||
|
||
### 10.1 文件结构
|
||
- [ ] 文件位于 `src/data/api_wrappers/api_{data_type}.py`
|
||
- [ ] 已更新 `src/data/api_wrappers/__init__.py` 导出公共接口
|
||
- [ ] 已创建 `tests/test_{data_type}.py` 测试文件
|
||
### 10.2 接口实现
|
||
- [ ] 数据获取函数使用 `TushareClient`
|
||
- [ ] **关键**：数据获取函数接受 `client: Optional[TushareClient] = None` 参数用于共享速率限制
|
||
- [ ] **关键**：Sync 类在 `fetch_single_date()` / `fetch_single_stock()` 中传递 `self.client`
|
||
- [ ] 函数包含完整的 Google 风格文档字符串
|
||
- [ ] 日期参数使用 `YYYYMMDD` 格式
|
||
- [ ] 返回的 DataFrame 包含 `ts_code` 和 `trade_date` 字段
|
||
- [ ] 优先实现按日期获取的接口（如果 API 支持）
|
||
- [ ] 参数传递前检查是否为 None
|
||
|
||
### 10.3 存储集成
|
||
- [ ] 使用 `Storage` 或 `ThreadSafeStorage` 进行数据存储
|
||
- [ ] 表结构包含 `ts_code` 和 `trade_date` 作为主键
|
||
- [ ] 使用 UPSERT 模式（`INSERT OR REPLACE`）
|
||
- [ ] 多线程场景使用 `queue_save()` + `flush()` 模式
|
||
|
||
### 10.4 Sync 集成
|
||
- [ ] 使用 `db_manager` 模块进行同步管理
|
||
- [ ] 实现 `sync_{data_type}()` 便捷函数
|
||
- [ ] 支持 `force_full` 参数
|
||
- [ ] 增量更新逻辑正确
|
||
|
||
### 10.5 测试
|
||
- [ ] 已编写单元测试
|
||
- [ ] 已 mock `TushareClient`
|
||
- [ ] 测试覆盖按日期和按股票获取
|
||
- [ ] 测试覆盖正常和异常情况
|
||
## 11. 示例参考
|
||
|
||
### 11.1 完整示例：api_pro_bar.py
|
||
|
||
参见 `src/data/api_wrappers/api_pro_bar.py` - 按股票获取 Pro Bar 行情数据的完整实现（主力行情表）。
|
||
|
||
### 11.2 完整示例：api_trade_cal.py
|
||
|
||
参见 `src/data/api_wrappers/api_trade_cal.py` - 特殊接口（交易日历）的实现，包含 HDF5 缓存逻辑。
|
||
|
||
### 11.3 完整示例：api_stock_basic.py
|
||
|
||
参见 `src/data/api_wrappers/api_stock_basic.py` - 特殊接口（股票基础信息）的实现，包含 CSV 存储逻辑。
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-03-26
|
||
|
||
**版本**: v2.1 - 更新速率限制规范，强调多线程场景下 client 参数传递 |