liaozhaorun
c0d996f39b
实现全面的白名单管理系统，支持策略自动启动： - 添加 WhitelistManager 类用于持久化白名单配置存储 - 将白名单功能集成到 StrategyManager 核心模块 - 添加用于白名单 CRUD 操作的 REST API 端点 - 通过 start.py 创建用于白名单管理的 CLI 命令 - 更新前端 UI，添加白名单状态指示器和批量操作功能 - 实现每日 08:58 的自动启动调度 - 为白名单操作添加配置验证和日志记录 同时添加项目文档： - 代码格式规则（缩进、行长度、导入、命名） - 文件、变量、常量、函数、类的命名规范 - 受限制文件和目录的保护规则
129 lines
4.3 KiB
Markdown
129 lines
4.3 KiB
Markdown
# 命名约定规则 (Naming Conventions)
|
||
|
||
本项目定义了一套统一的命名约定，以确保代码库的一致性和可读性。
|
||
|
||
## 1. 文件命名规范
|
||
|
||
### 1.1 Python 文件
|
||
- 使用 **小写字母 + 下划线**：`backtest_engine.py`, `data_manager.py`
|
||
- 避免使用连字符或空格
|
||
- 测试文件以 `test_` 前缀开头：`test_backtest_engine.py`
|
||
|
||
### 1.2 配置文件
|
||
- 使用小写字母和下划线：`config.json`, `strategy_params.yaml`
|
||
- 环境配置文件使用 `.env` 或 `.env.{environment}` 格式
|
||
|
||
### 1.3 数据文件
|
||
- 遵循 `{数据类型}_{日期范围}.{扩展名}` 格式
|
||
- 示例：`btc_ohlcv_2023_2024.csv`, `strategy_results_202401.json`
|
||
|
||
## 2. 变量命名规范
|
||
|
||
### 2.1 普通变量
|
||
- 使用 **小写字母 + 下划线**（snake_case）
|
||
- 使用描述性名称，避免缩写
|
||
- ✅ 正确示例：`current_price`, `trade_volume`, `stop_loss_price`
|
||
- ❌ 错误示例：`cp`, `tv`, `sl`
|
||
|
||
### 2.2 布尔变量
|
||
- 使用 `is_`, `has_`, `are_` 等前缀
|
||
- ✅ 正确示例：`is_valid`, `has_position`, `are_orders_filled`
|
||
- ❌ 错误示例：`valid`, `position`, `filled`
|
||
|
||
### 2.3 私有变量
|
||
- 使用单下划线前缀（约定俗成的私有）
|
||
- ✅ 正确示例：`_internal_cache`, `_last_order_id`
|
||
- ❌ 错误示例：`__private_var`（除非确实需要 name mangling）
|
||
|
||
### 2.4 临时变量
|
||
- 循环变量可使用单字母或简短名称
|
||
- ✅ 正确示例：`for i in range(n):`, `for bar in bars:`
|
||
|
||
## 3. 常量命名规范
|
||
|
||
### 3.1 全局常量
|
||
- 使用 **全大写字母 + 下划线**（SCREAMING_SNAKE_CASE）
|
||
- 定义在文件顶部或单独的 `constants.py` 模块中
|
||
- ✅ 正确示例：`MAX_POSITION = 5`, `DEFAULT_COMMISSION_RATE = 0.0003`
|
||
- ❌ 错误示例：`max_position`, `default_commission_rate`
|
||
|
||
### 3.2 配置常量
|
||
- 使用全大写字母和下划线
|
||
- ✅ 正确示例：`SYMBOL_FUTURES_SUFFIX = ".FG"`
|
||
|
||
## 4. 函数命名规范
|
||
|
||
### 4.1 普通函数
|
||
- 使用 **小写字母 + 下划线**（snake_case）
|
||
- 函数名应清晰表达其功能
|
||
- ✅ 正确示例：`calculate_metrics()`, `get_bar_history()`, `send_order()`
|
||
- ❌ 错误示例：`calc()`, `getData()`, `send()`
|
||
|
||
### 4.2 返回布尔值的函数
|
||
- 使用 `is_`, `has_`, `are_` 等前缀
|
||
- ✅ 正确示例：`is_trending_up()`, `has_active_orders()`, `are_positions_valid()`
|
||
|
||
### 4.3 私有函数
|
||
- 使用单下划线前缀
|
||
- ✅ 正确示例：`_validate_params()`, `_calculate_pnl()`
|
||
|
||
## 5. 类命名规范
|
||
|
||
### 5.1 公共类
|
||
- 使用 **大驼峰命名法**（PascalCase）
|
||
- ✅ 正确示例：`BacktestEngine`, `SimpleLimitBuyStrategy`, `DataManager`
|
||
- ❌ 错误示例：`backtest_engine`, `simple_limit_buy_strategy`
|
||
|
||
### 5.2 抽象基类
|
||
- 使用 `ABC` 后缀或 `Base` 前缀
|
||
- ✅ 正确示例：`Strategy(ABC)`, `BaseIndicator`
|
||
|
||
### 5.3 异常类
|
||
- 使用 `Error` 或 `Exception` 后缀
|
||
- ✅ 正确示例：`BacktestError`, `OrderExecutionException`
|
||
|
||
## 6. 特定领域命名规范
|
||
|
||
### 6.1 交易相关
|
||
- 方向：`BUY`, `SELL`, `CLOSE_LONG`, `CLOSE_SHORT`
|
||
- 订单类型：`LIMIT`, `MARKET`, `STOP`
|
||
- 持仓：`LONG`, `SHORT`, `FLAT`
|
||
|
||
### 6.2 策略参数
|
||
- 使用描述性名称，包含参数含义
|
||
- ✅ 正确示例：`stop_loss_points`, `take_profit_points`, `range_factor`
|
||
- ❌ 错误示例：`sl`, `tp`, `rf`
|
||
|
||
### 6.3 K线数据
|
||
- 时间周期：`1m`, `5m`, `15m`, `1h`, `4h`, `1d`
|
||
- OHLCV：`open`, `high`, `low`, `close`, `volume`
|
||
|
||
## 7. 数据库/缓存命名规范
|
||
|
||
### 7.1 缓存键
|
||
- 使用冒号分隔的层次结构
|
||
- ✅ 正确示例：`strategy:rb:positions`, `market:btc:price`
|
||
|
||
### 7.2 日志文件
|
||
- 使用 `{策略名}/{品种}.log` 格式
|
||
- ✅ 正确示例：`logs/SpectralTrendStrategy/rb.log`
|
||
|
||
## 8. 命名一致性检查清单
|
||
|
||
在提交代码前，请确认以下检查项：
|
||
|
||
- [ ] 所有变量名使用 snake_case
|
||
- [ ] 所有类名使用 PascalCase
|
||
- [ ] 所有常量使用 SCREAMING_SNAKE_CASE
|
||
- [ ] 函数名清晰表达功能
|
||
- [ ] 命名具有描述性，避免模糊缩写
|
||
- [ ] 私有成员使用下划线前缀
|
||
- [ ] 布尔变量使用适当的前缀
|
||
|
||
## 9. 命名反模式（应避免）
|
||
|
||
- ❌ 使用单个字母 `l`, `O`, `I` 作为变量名（容易与数字 1, 0 混淆）
|
||
- ❌ 使用魔法数字或字符串（应定义为常量）
|
||
- ❌ 使用不一致的命名风格混合
|
||
- ❌ 使用过于通用的名称如 `data`, `info`, `temp`
|
||
- ❌ 使用项目保留名称如 `strategy`, `engine`, `manager` |