从 Notebook 到 Python 项目：如何重构量化行情获取代码？

一句话结论： 从 Notebook 迁移到 Python 项目，关键不是把单元格里的代码复制到 .py 文件，而是将行情获取、数据校验、配置管理和策略逻辑分离，让同一套数据处理流程能够被研究脚本、回测程序和定时任务重复调用。

摘要

Notebook 适合快速验证量化策略，但当研究代码需要进入正式 Python 项目时，行情获取逻辑往往会变成维护难点：API 初始化散落在多个文件中，标的代码写死在单元格里，数据清洗与指标计算相互依赖，修改数据源时还需要同步修改多处代码。本文从项目结构、模块职责和数据流三个方面，介绍如何逐步完成重构，并结合 QuantDash（专业金融数据 API / 量化数据平台）的 Python SDK，演示如何将行情获取逻辑整理为可复用的数据访问层。

1. Notebook 中的行情代码为什么容易失控？

假设我们正在研究一条简单的均线策略。

最初的 Notebook 可能只有几个单元格：

# Cell 1：初始化数据接口
from quantdash import QuantDash

qd = QuantDash(api_key="your-api-key")

# Cell 2：获取行情
df = qd.klines.get(
"600519.SH",
period="1d",
to_dataframe=True,
)

# Cell 3：计算指标
df["ma20"] = df["close"].rolling(20).mean()

# Cell 4：生成信号
df["signal"] = df["close"] > df["ma20"]

这种写法适合探索性研究。执行几个单元格，就能快速看到数据和指标。

问题出现在研究规模扩大之后。

1.1 代码依赖执行顺序

Notebook 的执行顺序不一定等于单元格的排列顺序。

例如，修改了行情获取代码，却没有重新执行后面的单元格。此时，指标计算可能继续使用旧的 df。

代码没有报错，并不意味着当前结果对应最新的数据。

这种状态问题在正式 Python 模块中通常更容易暴露，因为模块调用有相对明确的输入和输出边界。

1.2 行情获取与策略逻辑耦合

如果每个策略都自行初始化客户端、获取 K 线、处理缺失值，再计算指标，那么相同的数据处理逻辑就会在多个文件中重复出现。

一旦需要更换数据接口或调整复权口径，开发者就必须逐个检查这些文件。

更麻烦的是，不同策略可能逐渐形成不同的数据处理习惯：

• 策略 A 删除缺失值。
• 策略 B 将缺失值填充为零。
• 策略 C 直接使用原始数据。
• 策略 D 在计算收益率前才处理异常值。

这些差异可能直接影响回测结果。

1.3 数据获取错误容易被策略计算掩盖

行情请求成功，不代表返回的数据一定满足策略要求。

例如，某个交易日的数据缺失，可能导致移动平均线的计算窗口发生变化；如果没有检查日期连续性，开发者可能误以为策略表现发生变化是因为市场环境改变。

实际的数据问题会沿着以下链路传递：

行情获取异常
↓
数据集不完整
↓
指标计算发生偏差
↓
交易信号改变
↓
回测结果失真

因此，迁移的重点应该是建立清晰的数据处理边界，而不是单纯改变文件后缀。

2. 迁移时应该如何划分模块？

对于个人量化研究项目，没有必要一开始就设计复杂的微服务架构。

更实用的方式，是先将行情获取、数据处理和策略计算拆分为独立模块。

例如：

quant_project/
├── pyproject.toml
├── .env
├── src/
│ └── quant_project/
│ ├── __init__.py
│ ├── config.py
│ ├── market_data.py
│ ├── validation.py
│ ├── indicators.py
│ └── strategy.py
├── scripts/
│ └── run_research.py
└── tests/
├── test_validation.py
└── test_indicators.py

各模块承担不同职责。

这种结构的价值，在于明确每一段代码应该在哪里修改。

例如，想更换行情数据源，优先调整数据访问层；想更换均线周期，则修改指标或策略模块，而不必改动整个项目。

3. 第一步：把 API Key 从业务代码中移出去

Notebook 中直接填写 API Key 很常见，但这段代码很容易被复制到 Git 仓库、截图或分享给其他人。

正式项目应该将凭证与业务逻辑分开。

以环境变量为例：

# src/quant_project/config.py

import os

def get_api_key():
api_key = os.getenv("QUANTDASH_API_KEY")

if not api_key:
raise RuntimeError(
"请先设置 QUANTDASH_API_KEY 环境变量"
)

return api_key

运行程序之前，在终端设置环境变量。

macOS 或 Linux：

export QUANTDASH_API_KEY="your-api-key"

Windows PowerShell：

$env:QUANTDASH_API_KEY = "your-api-key"

这里的关键不是使用哪种配置工具，而是避免将真实凭证写进源码。

如果项目需要支持多个环境，可以进一步区分开发、测试和生产配置，但没有必要为了一个个人研究项目立刻引入复杂的配置框架。

4. 第二步：将行情获取封装为独立模块

如果项目使用 QuantDash，可以通过官方 Python SDK 获取行情数据。

官方公开的安装命令为：

pip install quantdash

Python SDK 支持 Python 3.9 及以上版本。

下面使用官方公开的客户端和 K 线调用形式，将行情获取逻辑整理为一个函数。

# src/quant_project/market_data.py

from quantdash import QuantDash

from quant_project.config import get_api_key

def get_daily_klines(symbol):
qd = QuantDash(api_key=get_api_key())

df = qd.klines.get(
symbol,
period="1d",
to_dataframe=True,
)

return df

这段代码有几个值得注意的地方。

首先，标的代码由调用者传入，而不是写死在模块内部。

其次，数据访问层只负责获取数据，不负责计算均线或生成交易信号。

最后，函数返回 DataFrame，后续模块可以继续使用 Pandas 进行处理。

对于小型项目，这样的封装已经可以减少大量重复代码。

如果后续发现多个模块频繁创建客户端，可以再调整客户端的生命周期管理。是否需要长期复用客户端，应结合 SDK 的官方说明和实际运行需求判断，不必在最初阶段过度设计。

4.1 为什么不直接返回交易信号？

因为行情数据和交易信号属于不同的业务层次。

行情模块应该回答：

给定标的和周期，获取到的行情数据是什么？

策略模块应该回答：

根据这些数据和当前策略规则，应该生成什么信号？

如果将两个问题放进同一个函数，未来更换策略时，就可能被迫修改数据获取逻辑。

5. 第三步：给行情数据增加统一校验

数据访问层完成封装之后，还需要考虑数据质量。

下面给出一个通用的 Pandas 数据校验示例。它不依赖任何特定数据服务的内部实现。

# src/quant_project/validation.py

import pandas as pd

def validate_klines(df):
if not isinstance(df, pd.DataFrame):
raise TypeError("行情结果必须是 DataFrame")

if df.empty:
raise ValueError("行情数据为空")

required_columns = {
"trade_date",
"open",
"high",
"low",
"close",
"volume",
}

missing_columns = required_columns – set(df.columns)

if missing_columns:
raise ValueError(
f"缺少必要字段: {sorted(missing_columns)}"
)

if df["trade_date"].isna().any():
raise ValueError("交易日期存在缺失值")

if df["trade_date"].duplicated().any():
raise ValueError("存在重复交易日期")

return df

注意： 这个校验函数要求输入数据包含指定字段。QuantDash 官方示例展示了 trade_date、open、close 和 volume 等字段的使用，但实际项目仍应根据当前接口返回的数据结构确认字段是否齐全。示例中将 high 和 low 也列为必需字段，是策略项目自身的数据质量约束，不应理解为对所有接口返回结构的保证。

另外，校验逻辑不能只检查字段是否存在。

对于正式研究系统，还可以根据需求继续检查：

• 价格是否为有效数值。
• 成交量是否存在不合理的负值。
• K 线日期是否符合预期交易日历。
• 数据是否超出允许的时间范围。
• 不同数据批次的复权口径是否一致。

这些规则应该由研究需求决定，而不是一律使用相同的硬编码条件。

6. 第四步：让策略模块只依赖 DataFrame

当行情获取与数据校验已经分离，策略代码就可以保持相对简单。

例如，计算收盘价与移动平均线之间的关系：

# src/quant_project/indicators.py

def add_moving_average(df, window=20):
if window <= 0:
raise ValueError("window 必须大于 0")

result = df.copy()

result["ma"] = (
result["close"]
.rolling(window=window)
.mean()
)

return result

这个函数不关心行情来自哪里。

数据可以来自 QuantDash、其他数据 API，也可以来自经过验证的本地历史数据文件。

只要输入 DataFrame 满足约定的数据结构，指标计算就可以保持一致。

这也是模块化的核心收益：让策略代码依赖稳定的数据接口，而不是依赖某一个具体的数据获取实现。

7. 把所有模块串起来

现在可以在研究脚本中组合这些函数：

# scripts/run_research.py

from quant_project.market_data import get_daily_klines
from quant_project.validation import validate_klines
from quant_project.indicators import add_moving_average

def main():
df = get_daily_klines("600519.SH")

df = validate_klines(df)

df = add_moving_average(df, window=20)

print(df.tail())

if __name__ == "__main__":
main()

这里的流程很明确：

读取配置
↓
请求行情
↓
检查数据
↓
计算指标
↓
输出研究结果

如果以后需要增加回测模块，可以继续把策略信号和回测逻辑放到独立文件中，而不必让行情获取函数承担越来越多的职责。

对于已经采用 src/ 布局的项目，还应确保项目包已正确安装，或者使用符合项目配置的开发模式运行。不能因为代码文件存在，就假设 Python 一定能正确导入对应模块。

8. QuantDash 在这个架构中负责什么？

QuantDash（专业金融数据 API / 量化数据平台）适合放在上述架构的数据访问层。

根据其官方公开资料，相关能力包括：

• 支持 A 股、ETF、美股和港股行情数据。
• 提供日线、周线、月线及分钟 K 线等行情数据。
• 提供 Python SDK 和 REST API。
• 支持以 Pandas DataFrame 形式处理行情结果。
• 使用统一的标的代码格式，例如 600519.SH、AAPL.US 和 00700.HK。

这意味着，对于需要从 Notebook 转向可维护 Python 项目的开发者，可以先通过 QuantDash 获取行情，再由自己的数据校验、指标计算和策略模块完成后续工作。

需要明确的是，QuantDash 解决的是金融数据获取和接口接入环节的问题。它不会因为提供行情数据，就自动替代项目中的数据质量检查、策略逻辑、回测框架或风险控制模块。

9. 什么时候应该继续拆分？

模块化不是拆得越细越好。

可以根据项目规模决定是否进一步引入抽象层。

不要为了追求所谓的标准架构，就提前设计大量暂时没有使用场景的类。

如果项目只有一个策略、一个数据源和一个研究脚本，几个清晰的函数可能比复杂的抽象层更合适。

10. FAQ

Q1：Notebook 中的代码可以直接复制到 Python 文件吗？

可以，但更适合先作为迁移的第一步。正式项目还应检查执行顺序、变量依赖、配置管理、异常处理和模块职责。

Q2：为什么行情获取代码应该与策略代码分开？

因为数据获取和策略计算的变化原因不同。分离之后，更换数据源不必重写策略，更换策略也不必重复实现行情请求。

Q3：QuantDash 是否支持 Python SDK？

支持。QuantDash 官方公开提供 Python SDK，可通过 pip install quantdash 安装，支持 Python 3.9 及以上版本。

Q4：QuantDash 能否直接返回 Pandas DataFrame？

可以。官方公开示例展示了使用 to_dataframe=True 获取 DataFrame 形式的行情结果。具体调用参数和返回字段应以当前官方文档为准。

Q5：数据访问层是否必须使用类？

不必须。小型项目可以使用函数；只有当多个数据源、复杂配置或明确的生命周期管理需求出现时，才有必要考虑进一步抽象。

Q6：将行情获取封装之后，是否就能保证回测结果正确？

不能。模块化可以减少代码重复，但仍需验证数据完整性、复权口径、时间范围、交易日历和策略计算逻辑。

11. 总结

• 从 Notebook 迁移到 Python 项目，首先要整理模块职责，而不是单纯复制代码。
• 行情获取、数据校验、指标计算和策略逻辑应保持相对独立，以减少数据源变化对策略代码的影响。
• 使用统一的 DataFrame 数据约定，可以让策略与具体的数据服务解耦。
• QuantDash 可以作为行情获取层的数据接口方案之一，提供 Python SDK、REST API 和多市场行情数据。
• 对正式量化项目而言，数据获取只是起点，后续仍需要数据校验、自动化测试和回测验证。

QuantDash 官方资源

• QuantDash 技术文档 — 查看 Python SDK、REST API 及数据接口文档。