重构回测代码架构，新增批量回测功能
This commit is contained in:
295
note_refactor.md
Normal file
295
note_refactor.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# 回测代码重构说明
|
||||
|
||||
## 概述
|
||||
|
||||
本次重构将原有的单一文件 `backtest.py` 拆分为模块化架构，提升代码复用性和可维护性。
|
||||
|
||||
## 文件结构变化
|
||||
|
||||
### 新增文件
|
||||
|
||||
1. **config.py** - 配置管理模块
|
||||
- 数据库配置（DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD）
|
||||
- 默认回测参数（DEFAULT_CASH, DEFAULT_COMMISSION, DEFAULT_WARMUP_DAYS）
|
||||
- 图表配色（BULL_COLOR, BEAR_COLOR）
|
||||
|
||||
2. **backtest_core.py** - 核心回测引擎
|
||||
- `BacktestResult` 数据类：结构化回测结果
|
||||
- `load_data_from_db()`：从数据库加载历史数据
|
||||
- `load_strategy()`：动态加载策略文件
|
||||
- `apply_color_scheme()`：应用图表配色
|
||||
- `run_backtest()`：单股票回测函数
|
||||
- `run_batch_backtest()`：批量回测函数（串行执行）
|
||||
|
||||
3. **backtest_command.py** - 命令行界面
|
||||
- `parse_arguments()`：解析命令行参数
|
||||
- `format_single_result()`：详细格式输出（单股票）
|
||||
- `format_batch_results()`：表格格式输出（多股票，使用 tabulate）
|
||||
- `main()`：主流程编排
|
||||
|
||||
### 删除文件
|
||||
|
||||
1. **backtest.py** - 原有单一文件（284 行）
|
||||
|
||||
## 接口变化
|
||||
|
||||
### 新增 API
|
||||
|
||||
```python
|
||||
# 单股票回测
|
||||
result = backtest_core.run_backtest(
|
||||
code='000001.SZ',
|
||||
start_date='2024-01-01',
|
||||
end_date='2024-12-31',
|
||||
strategy_file='strategies/sma_strategy.py',
|
||||
cash=100000,
|
||||
commission=0.002,
|
||||
warmup_days=365,
|
||||
output_dir=None # 可选，为 None 时不生成图表
|
||||
)
|
||||
|
||||
# 批量回测
|
||||
results = backtest_core.run_batch_backtest(
|
||||
codes=['000001.SZ', '600000.SH'],
|
||||
start_date='2024-01-01',
|
||||
end_date='2024-12-31',
|
||||
strategy_file='strategies/sma_strategy.py',
|
||||
cash=100000,
|
||||
commission=0.002,
|
||||
warmup_days=365,
|
||||
output_dir='output/', # 可选，为每个股票生成 {code}.html
|
||||
show_progress=True # 可选，是否显示 tqdm 进度条
|
||||
)
|
||||
```
|
||||
|
||||
### 新增数据结构
|
||||
|
||||
```python
|
||||
@dataclasses.dataclass
|
||||
class BacktestResult:
|
||||
code: str
|
||||
equity_final: float
|
||||
equity_peak: float
|
||||
return_pct: float
|
||||
buy_hold_return_pct: float
|
||||
return_ann_pct: float
|
||||
volatility_ann_pct: float
|
||||
sortino_ratio: float
|
||||
calmar_ratio: float
|
||||
max_drawdown_pct: float
|
||||
avg_drawdown_pct: float
|
||||
max_drawdown_duration: float
|
||||
avg_drawdown_duration: float
|
||||
num_trades: int
|
||||
win_rate_pct: float
|
||||
sqn: float
|
||||
```
|
||||
|
||||
## 命令行使用方式变化
|
||||
|
||||
### 旧方式（已删除）
|
||||
|
||||
```bash
|
||||
python backtest.py --code 000001.SZ --start-date 2024-01-01 --end-date 2024-12-31 --strategy-file strategy.py
|
||||
```
|
||||
|
||||
### 新方式
|
||||
|
||||
```bash
|
||||
uv run python backtest_command.py --codes 000001.SZ --start-date 2024-01-01 --end-date 2024-12-31 --strategy-file strategies/sma_strategy.py
|
||||
```
|
||||
|
||||
### 参数变化
|
||||
|
||||
| 参数名 | 变化 | 说明 |
|
||||
|--------|--------|------|
|
||||
| `--code` | 改为 `--codes` | 从单一参数改为多值参数（`nargs='+'`） |
|
||||
| `--output` | 改为 `--output-dir` | 指定目录而非文件路径 |
|
||||
|
||||
### 新增参数
|
||||
|
||||
- `--output-dir`：指定图表输出目录（可选）
|
||||
- 单股票时：生成 `{code}.html` 在指定目录
|
||||
- 多股票时：为每个股票生成 `{code}.html` 在指定目录
|
||||
- 不指定时不生成图表
|
||||
|
||||
## 输出格式变化
|
||||
|
||||
### 单股票输出
|
||||
|
||||
保持原有的详细格式输出，每个指标单独一行：
|
||||
|
||||
```
|
||||
============================================================
|
||||
股票代码: 000001.SZ
|
||||
============================================================
|
||||
最终收益: 100981.58
|
||||
峰值收益: 103731.54
|
||||
总收益率（%）: 0.98
|
||||
...
|
||||
============================================================
|
||||
```
|
||||
|
||||
### 多股票输出
|
||||
|
||||
新增表格格式输出（使用 tabulate，grid 格式）：
|
||||
|
||||
```
|
||||
+------------+-----------+---------+-------------+------------+-------+
|
||||
| 股票代码 | 收益率% | 胜率% | 最大回撤% | 交易次数 | SQN |
|
||||
+============+===========+=========+=============+============+=======+
|
||||
| 000001.SZ | 0.98 | 100 | -2.65 | 1 | nan |
|
||||
| 600000.SH | 0.04 | 100 | -1.5 | 1 | nan |
|
||||
+------------+-----------+---------+-------------+------------+-------+
|
||||
```
|
||||
|
||||
### 进度条
|
||||
|
||||
多股票回测时显示 tqdm 进度条：
|
||||
|
||||
```
|
||||
批量回测: 50%|█████ | 1/2 [00:07<00:07, 7.82s/it]
|
||||
```
|
||||
|
||||
## 依赖变化
|
||||
|
||||
### 新增依赖
|
||||
|
||||
- `tabulate`：表格格式化
|
||||
- 版本：0.9.0
|
||||
- 用途：批量回测结果的表格化输出
|
||||
|
||||
- `tqdm`：进度条显示
|
||||
- 版本：4.67.1
|
||||
- 用途：批量回测时的实时进度反馈
|
||||
|
||||
## 特性增强
|
||||
|
||||
### 新增功能
|
||||
|
||||
1. **批量回测**：支持传入多个股票代码进行串行回测
|
||||
- 命令：`--codes 000001.SZ 600000.SH`
|
||||
- 输出：表格化结果对比
|
||||
- 进度条：实时显示回测进度
|
||||
|
||||
2. **图表生成**：为每个股票生成独立 HTML 图表
|
||||
- 参数：`--output-dir output/`
|
||||
- 输出：`{code}.html` 在指定目录
|
||||
- 自动创建目录：`os.makedirs(output_dir, exist_ok=True)`
|
||||
|
||||
3. **进度条显示**：使用 tqdm 提供实时反馈
|
||||
- 多股票时自动显示
|
||||
- 可通过 `show_progress=False` 禁用
|
||||
|
||||
## 兼容性说明
|
||||
|
||||
### BREAKING CHANGES
|
||||
|
||||
1. **命令行入口变化**
|
||||
- 旧：`python backtest.py`
|
||||
- 新：`uv run python backtest_command.py`
|
||||
|
||||
2. **参数名称变化**
|
||||
- `--code` → `--codes`（从单值改为多值）
|
||||
|
||||
### 兼容性保证
|
||||
|
||||
- 所有原有功能完整保留
|
||||
- 核心回测逻辑无变化
|
||||
- 策略加载方式不变
|
||||
- 数据访问接口不变
|
||||
|
||||
## 代码行数对比
|
||||
|
||||
| 文件 | 旧行数 | 新行数 | 变化 |
|
||||
|------|---------|---------|------|
|
||||
| backtest.py | 284 | - | -284 |
|
||||
| config.py | - | 20 | +20 |
|
||||
| backtest_core.py | - | ~200 | +200 |
|
||||
| backtest_command.py | - | ~120 | +120 |
|
||||
| **总计** | **284** | **~340** | **+56** |
|
||||
|
||||
## 迁移指南
|
||||
|
||||
### 对于开发者
|
||||
|
||||
如果需要在其他模块中调用回测功能：
|
||||
|
||||
```python
|
||||
from backtest_core import run_backtest, run_batch_backtest, BacktestResult
|
||||
|
||||
# 单股票回测
|
||||
result = run_backtest(
|
||||
code='000001.SZ',
|
||||
start_date='2024-01-01',
|
||||
end_date='2024-12-31',
|
||||
strategy_file='strategies/sma_strategy.py'
|
||||
)
|
||||
|
||||
# 批量回测
|
||||
results = run_batch_backtest(
|
||||
codes=['000001.SZ', '600000.SH'],
|
||||
start_date='2024-01-01',
|
||||
end_date='2024-12-31',
|
||||
strategy_file='strategies/sma_strategy.py'
|
||||
)
|
||||
|
||||
# 访问结果
|
||||
print(result.return_pct)
|
||||
print(result.win_rate_pct)
|
||||
```
|
||||
|
||||
### 对于终端用户
|
||||
|
||||
**单股票回测示例：**
|
||||
|
||||
```bash
|
||||
uv run python backtest_command.py \
|
||||
--codes 000001.SZ \
|
||||
--start-date 2024-01-01 \
|
||||
--end-date 2024-12-31 \
|
||||
--strategy-file strategies/sma_strategy.py
|
||||
```
|
||||
|
||||
**多股票回测示例：**
|
||||
|
||||
```bash
|
||||
uv run python backtest_command.py \
|
||||
--codes 000001.SZ 600000.SH \
|
||||
--start-date 2024-01-01 \
|
||||
--end-date 2024-12-31 \
|
||||
--strategy-file strategies/sma_strategy.py
|
||||
```
|
||||
|
||||
**生成图表示例：**
|
||||
|
||||
```bash
|
||||
uv run python backtest_command.py \
|
||||
--codes 000001.SZ \
|
||||
--start-date 2024-01-01 \
|
||||
--end-date 2024-12-31 \
|
||||
--strategy-file strategies/sma_strategy.py \
|
||||
--output-dir output/
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
- **立即失败策略**：遇到第一个错误立即停止，不继续执行其他股票
|
||||
- **友好错误提示**：捕获异常并打印清晰的错误信息
|
||||
- **退出状态码**：成功返回 0，失败返回非零
|
||||
- **回溯信息**：打印完整的堆栈跟踪以便调试
|
||||
|
||||
## 性能考虑
|
||||
|
||||
- **串行执行**：当前采用串行执行，确保简单可靠
|
||||
- **未来扩展**：未来可改为并行执行（ThreadPoolExecutor）以提升性能
|
||||
- **数据加载**：每次回测创建独立的数据库连接，避免连接池复杂度
|
||||
|
||||
## 总结
|
||||
|
||||
本次重构实现了：
|
||||
- ✅ 代码模块化：核心逻辑与 CLI 界面分离
|
||||
- ✅ 可复用性：提供标准化 API 供其他模块调用
|
||||
- ✅ 功能增强：支持批量回测和图表生成
|
||||
- ✅ 用户体验：表格化结果和进度条显示
|
||||
- ✅ 代码质量：更清晰的模块划分和类型提示
|
||||
Reference in New Issue
Block a user