📚 课程目录第4章项目结构解析

4. 项目结构解析

当我们用 LEAN CLI 执行 lean init 或 lean project-create 之后，磁盘上会出现一套看似“目录很多、文件很杂”的工程结构。很多初学者第一次打开时，会本能地只盯着 Main.py 或 Main.cs，把其余内容当成脚手架忽略掉。但在回测转实盘的过程中，真正决定“能不能跑起来、跑得对不对、换环境是否可复现”的，恰恰是这些目录与配置文件的组织方式。本节把 LEAN 项目结构拆成四个层次：项目根目录、配置文件、算法文件、数据文件夹，并说明它们之间的依赖关系。

一、核心原理：LEAN 用“约定目录”替代硬编码路径

LEAN 的设计哲学是：算法代码只关心“我要什么数据、什么标的、什么时间范围”，而不关心数据实际存放在哪个盘符、哪个文件夹。为此，LEAN 通过一套约定目录来定位资源。CLI 在初始化时会创建全局数据目录（通常位于用户目录下的 data/），而每个项目又拥有自己的项目目录。算法运行时，LEAN 会按优先级在“项目目录 → 全局数据目录 → 远程数据源”之间查找数据。理解这条查找链，是排查“本地能跑、换机器就报数据缺失”的关键。

二、方法流程：从目录到配置的阅读顺序

面对一个陌生的 LEAN 项目，建议按以下顺序阅读，而不是直接打开算法文件：

先看项目根目录：确认 Main.py（或 Main.cs）、config.json、research.ipynb、backtests/、data/ 是否存在。缺少 config.json 时，CLI 会使用默认配置，容易导致回测结果与预期不符。
再读 config.json：重点看 algorithm-language、data-folder、environment、parameters 四项。它们分别决定语言、数据位置、运行环境和参数注入。
然后看算法文件：确认 Initialize 中订阅了哪些标的、OnData 中如何处理数据、是否使用了 SetStartDate 与 SetEndDate。
最后核对数据文件夹：用 lean data download 或手动检查 data/ 下是否已有对应市场、分辨率、时间范围的数据。

一个典型的 config.json 片段如下，注意 data-folder 的路径写法：

{
  "algorithm-language": "Python",
  "data-folder": "../../data",
  "environment": "backtesting",
  "parameters": {
    "symbol": "SPY",
    "fast-period": 10,
    "slow-period": 30
  }
}

三、案例/场景：同一算法在回测与实盘间的目录差异

假设我们有一个双均线策略，回测时使用 data/equity/usa/daily/spy.zip，实盘时改为订阅券商实时行情。此时目录结构本身不变，但 config.json 中的 environment 会从 backtesting 切换为 live，同时 data-folder 可能指向一个只包含元数据、不包含历史行情的目录。算法文件中的 Initialize 需要根据环境判断是否调用 SetBrokerageModel。如果忽略这一点，回测中能成交的订单在实盘可能因最小交易单位、交易时段不同而被拒绝。

目录/文件	作用	回测关注点	实盘关注点
`Main.py`	算法入口，定义 Initialize / OnData	订阅标的、时间范围	订单路由、风控逻辑
`config.json`	运行配置与参数注入	data-folder、environment	brokerage、live 模式
`data/`	本地行情与元数据	历史数据完整性	实时数据订阅配置
`backtests/`	回测结果与日志	统计指标、订单记录	实盘日志另行存放
`.lean/`	CLI 缓存与运行状态	可清理重建	避免误删导致重连

四、误区与复盘

常见误区一：把数据直接放进项目根目录。LEAN 默认按市场/资产类别/分辨率分层查找，随意放置会导致 FileNotFound 或静默使用远程数据，回测速度骤降。

常见误区二：修改 config.json 后不重启 CLI。部分配置在进程启动时读取，热修改可能不生效，表现为“改了参数但结果没变”。

常见误区三：忽略 .lean 缓存。当数据文件被替换但缓存未失效时，回测仍使用旧数据。排查时应先清理缓存再重跑。

复盘建议：每次回测转实盘前，用 lean backtest 与 lean live 各跑一次最小用例，确认 config.json 中的 environment、data-folder、brokerage 三项与目标环境一致。把这三项写进项目 README，能显著降低换机、换人后的沟通成本。

总结来说，LEAN 项目结构不是“一堆自动生成的文件”，而是一套以约定目录和配置文件为核心的资源定位体系。算法文件负责策略逻辑，配置文件负责运行环境，数据文件夹负责数据供给，三者通过 CLI 的查找链串联。掌握这套结构，才能在回测与实盘之间平滑迁移，而不是每次换环境都重新踩一遍路径与配置的坑。