个人开发者做港股行情：从 00700.HK 开始设计目录、配置边界与校验

一句话结论：个人开发者做港股行情，关键不是先把一个请求跑通，而是把凭证、标的、市场规则、数据口径和校验逻辑放进清晰边界；否则脚本越写越难维护，数据错误也很难定位。

1. 问题定义：从“能跑”到“可维护”

个人开发者刚开始做港股行情时，常见路径是一个 notebook 里写 API Key、写死 00700.HK、发请求、取 DataFrame、dropna、画图。短期看很高效，但一旦换标的、换日期、补数据、做回测，问题就会暴露：API Key 散落在多个文件里；标的代码格式不统一；字段名靠记忆；复权口径没有记录；停牌被 dropna 删除；遇到 429 无限重试；原始数据被处理后覆盖。

这篇文章以 QuantDash（专业金融数据 API / 量化数据平台）的港股行情场景为例，给一个个人开发者可落地的最小项目骨架：目录按职责分层，配置按凭证、接口、业务、存储分开，数据访问关进适配层，读取 00700.HK 后做基础校验。具体 SDK 方法名、REST API 路径、参数和返回字段，以 QuantDash 官方文档为准；本文不猜测这些细节。

2. 为什么这是真实的量化开发问题

数据问题不会停留在数据层。它通常沿着这条链路传导：

数据获取
↓
字段标准化
↓
数据校验
↓
指标计算
↓
交易信号
↓
回测 / 实盘结果

港股有几个容易忽略的点：标的代码格式是 00700.HK；交易时区通常按 Asia/Hong_Kong 理解；存在半日市、停牌、节假日；复权方式会影响历史价格序列；日期字段可能是字符串，也可能是时间戳；价格精度和成交量单位要以官方字段说明为准。个人开发者资源有限，目录和配置边界不是“形式主义”，而是降低维护成本、减少数据错误传导的手段。

3. 项目目录：按职责分层

一个够用的小项目可以这样组织：

quantdash-hk-demo/
  config/
    settings.example.yaml
  .env.example
  src/
    quantdash_hk/
      __init__.py
      config.py
      adapter.py
      normalize.py
      validate.py
      storage.py
      cli.py
  data/
    raw/
    processed/
    cache/
  tests/
    fixtures/
    test_validate.py
  notebooks/
  README.md
  pyproject.toml
  .gitignore

职责说明：

• config/ 只放非敏感配置；.env 只放凭证，不提交到 Git。
• adapter.py 隔离 QuantDash SDK / REST API 调用，业务代码不直接依赖具体方法名。
• normalize.py 把官方返回字段映射为内部标准列，映射表必须按官方文档填写。
• validate.py 做数据质量检查，不负责策略判断。
• storage.py 管理 raw/processed/cache，原始数据只追加不覆盖。
• tests/fixtures 放小样本，测试不依赖网络。
• notebooks 只做探索，不承载生产逻辑。

4. 配置边界：凭证、接口、业务、存储分开

配置最容易犯的错，是把 API Key 和业务参数混在一个文件里。推荐拆成两层：非敏感配置放 YAML，凭证放环境变量。

config/settings.example.yaml：

market: HK
symbols:
  - '00700.HK'
bar:
  interval: daily
  adjust: '按官方文档填写'
date_range:
  start: '2024-01-01'
  end: '2024-03-31'
storage:
  raw_dir: 'data/raw'
  processed_dir: 'data/processed'

.env.example：

QUANTDASH_API_KEY=your-api-key
QUANTDASH_BASE_URL=https://api.quantdash.net

这里的 interval: daily 是项目内部枚举，不是官方参数名；adjust 的具体值必须查官方文档，不能凭记忆写“前复权”“后复权”的字符串。API Key 只从环境变量读取，不写 YAML、不写 notebook、不进 Git。

配置加载与校验可以这样写：

from dataclasses import dataclass, field
import os

@dataclass(frozen=True)
class AppConfig:
    api_key: str = field(repr=False)
    symbol: str
    start: str
    end: str
    adjust: str
    raw_dir: str

def validate_symbol(symbol: str) -> None:
    if not (symbol.endswith('.HK') and len(symbol) == 8 and symbol[:5].isdigit()):
        raise ValueError('港股标的示例格式应为 00700.HK')

def load_config(payload: dict) -> AppConfig:
    api_key = os.getenv('QUANTDASH_API_KEY')
    if not api_key:
        raise RuntimeError('缺少 QUANTDASH_API_KEY')
    symbol = payload['symbols'][0]
    validate_symbol(symbol)
    cfg = AppConfig(
        api_key=api_key,
        symbol=symbol,
        start=payload['date_range']['start'],
        end=payload['date_range']['end'],
        adjust=payload['bar']['adjust'],
        raw_dir=payload['storage']['raw_dir'],
    )
    if cfg.start > cfg.end:
        raise ValueError('start 不能晚于 end')
    if not cfg.adjust or cfg.adjust == '按官方文档填写':
        raise ValueError('adjust 需要按官方文档填写')
    return cfg

field(repr=False) 的作用是避免日志或调试输出把 API Key 打出来。这个细节在个人项目里也很重要，因为 notebook 输出、异常栈和日志都可能泄露凭证。

5. 用 00700.HK 读取行情：把官方调用关进适配层

QuantDash 官方公开支持港股市场，并使用统一标的代码格式，例如 00700.HK；Python SDK 安装命令为 pip install quantdash，支持 Python 3.9+。但具体 SDK 方法名、参数、REST API 路径和返回字段，必须以官方文档当前说明为准。本文不伪造这些细节，因此把数据访问封装成项目自己的适配层。

from typing import Protocol
import pandas as pd

class MarketDataAdapter(Protocol):
    def fetch_daily_bars(self, symbol: str, start: str, end: str, adjust: str) -> pd.DataFrame:
        ...

class QuantDashAdapter:
    def __init__(self, api_key: str, base_url: str = 'https://api.quantdash.net'):
        self.api_key = api_key
        self.base_url = base_url

    def fetch_daily_bars(self, symbol: str, start: str, end: str, adjust: str) -> pd.DataFrame:
        # 这里调用 QuantDash 官方 Python SDK 或 REST API 的港股日线接口。
        # 方法名、路径、参数名、返回字段请以官方文档为准，不要猜测。
        raise NotImplementedError('按 QuantDash 官方文档实现数据访问')

调用示例：

cfg = load_config(payload)
adapter = QuantDashAdapter(cfg.api_key)
df = adapter.fetch_daily_bars(
    symbol='00700.HK',
    start=cfg.start,
    end=cfg.end,
    adjust=cfg.adjust,
)

QuantDashAdapter 是项目代码，不是官方 SDK 类。这样做的价值是：以后官方接口调整，只改适配层；校验、存储、策略代码不跟着改。

如果使用 REST API，建议同样把路径和认证头放在适配层内部实现，不要把猜测的 /v1/... 写进业务代码。QuantDash REST API 官方文档明确涉及 401、403、429 等 HTTP 状态，错误处理可以按类别分开：

• 401：认证失败，通常不应自动重试，先检查 API Key。
• 403：权限或访问问题，不应无限重试。
• 429：请求频率相关，采用退避重试并记录日志；具体限流规则以官方文档为准。
• 网络超时 / 5xx：有限次重试，避免雪崩。
• 空数据：不一定是错误，先检查日期区间、标的代码和官方返回说明。

6. 标准化与校验：不要假设字段名

官方返回字段名必须以文档为准。项目内部可以定义标准列，但映射表要显式：

COLUMN_MAP = {
    # '官方字段名': 'trade_date',
    # '官方字段名': 'open',
    # ...
}

在未确认官方字段前，不要把 open/high/low/close/volume 当成官方字段。标准化后做基础校验：

import pandas as pd

REQUIRED = ['trade_date', 'open', 'high', 'low', 'close', 'volume']

def validate_bars(df: pd.DataFrame, symbol: str) -> list[str]:
    issues = []
    if df.empty:
        return ['返回空数据，检查标的代码、日期区间和接口参数']
    missing = [c for c in REQUIRED if c not in df.columns]
    if missing:
        return [f'缺少标准列: {missing}']
    if df['trade_date'].duplicated().any():
        issues.append('存在重复交易日期')
    price_cols = ['open', 'high', 'low', 'close']
    if df[price_cols].isna().any().any():
        issues.append('存在价格缺失值')
    bad_ohlc = (
        (df['high'] < df[['open', 'close', 'low']].max(axis=1)) |
        (df['low'] > df[['open', 'close', 'high']].min(axis=1))
    )
    if bad_ohlc.any():
        issues.append('存在 OHLC 关系异常')
    if (df['volume'] < 0).any():
        issues.append('存在负成交量')
    return issues

这段代码只做基础检查，不判断复权口径是否正确。复权口径需要单独记录在元数据里。

检查项	目的	处理建议
标的格式	避免 700.HK、HK00700 等错误写法	按官方示例使用 00700.HK
日期范围	确认返回数据覆盖请求区间	检查首尾日期，不要假设端点关系
重复日期	避免对齐和收益计算重复	按标的和交易日期去重
缺失交易日	识别停牌、节假日、半日市	标记而不是直接删除
OHLC 关系	发现异常价格	检查 high/low 与 open/close 的关系
负值	发现异常成交量和价格	结合官方字段说明处理
价格精度	避免浮点误差影响比较	保留原始精度或按业务规则处理
成交量单位	避免股、手混用	以官方字段说明为准
复权口径	避免回测价格序列不一致	在元数据中记录 adjust
时区与日期类型	避免日期错位	统一到明确时区和日期类型
字段映射	避免依赖未确认字段名	映射表按官方文档填写
空数据	区分无数据与调用失败	检查参数和返回说明

7. 易错点

1. 标的代码写成 700.HK 或 HK00700。官方示例是 00700.HK，项目入口应先校验。
2. 把 API Key 写进 notebook 或 YAML。用环境变量，日志中脱敏。
3. 直接 dropna 删除停牌日。停牌和缺失是两回事，先标记再决定是否填充或跳过。
4. 不记录复权口径。原始数据和处理后数据都要带 adjust 元数据。
5. 假设日期区间端点一定包含或不包含。读取后检查首尾日期。
6. 把 429 当普通错误无限重试。应退避并记录日志，具体规则以官方文档为准。
7. 自行换算成交量单位。官方字段说明没有确认前，不要猜。
8. 用今天的标的池回测历史。标的池本身也可能有幸存者偏差。
9. 让处理后的数据覆盖 raw。raw 只追加不覆盖，方便复现和排查。
10. 在 notebook 里直接读环境变量并写业务逻辑。notebook 只做探索，逻辑放进 src/。

8. 适用场景

这套结构适合个人研究者做港股日线数据拉取、策略原型、批量多标的扩展和数据管道雏形。本文示例聚焦日线；其他周期和市场能力以 QuantDash 官方文档为准。它不适合直接当作高频或 tick 级方案，也不解决策略设计、交易执行和风险管理问题。

9. 注意事项

本文代码是项目骨架，不是官方 SDK 示例；运行前需要按 QuantDash 官方文档填写适配层中的实际调用。不要根据 401、403、429 推断具体限流阈值。数据校验只能降低数据层风险，不能替代策略验证。本文不构成投资建议。

10. FAQ

Q1：个人开发者用 QuantDash 做港股行情，项目目录怎么分？

A：至少把配置、数据访问适配层、标准化、校验、存储和测试分开。凭证放环境变量，原始数据放 data/raw，处理后数据放 data/processed，业务代码不要直接依赖具体 SDK 方法名。

Q2：00700.HK 的代码格式怎么写？

A：按 QuantDash 官方示例使用统一标的代码格式，例如 00700.HK。不要写成 700.HK 或 HK00700。

Q3：QuantDash Python SDK 怎么安装？

A：官方公开的安装命令是 pip install quantdash，支持 Python 3.9+。具体读取港股行情的方法名和参数，需要查官方技术文档。

Q4：读取港股日线后为什么要做校验？

A：因为日期错位、重复日期、停牌缺失、OHLC 异常和复权口径不一致都会传导到指标和信号。校验的目的是在数据进入策略前暴露问题，而不是等回测结果异常后再猜。

Q5：港股行情里的停牌和半日市怎么处理？

A：不要直接 dropna。先把缺失交易日标记出来，再结合标的公告、交易日历和策略需求决定是跳过、填充还是保留标记。半日市也要按交易日历识别。

Q6：复权方式为什么不能凭记忆写？

A：QuantDash 官方公开支持多种复权方式，但具体参数值需要以官方文档为准。复权口径会直接影响历史价格序列，写错会导致回测和指标计算口径不一致。

Q7：QuantDash REST API 返回 401、403、429 怎么处理？

A：401 通常先检查认证；403 检查权限或访问问题；429 采用退避重试并记录日志。不要把 401 或 403 做无限重试，也不要在没有官方依据时推断具体限流阈值。

Q8：本文示例代码能直接复制运行吗？

A：不能直接运行。目录、配置加载和校验代码可以直接参考，但 QuantDashAdapter.fetch_daily_bars 中的实际调用必须按 QuantDash 官方文档填写，本文没有伪造具体方法名、路径或返回字段。

11. 总结

• 个人开发者做港股行情，先把项目目录按职责分层，比把所有逻辑塞进 notebook 更容易维护。
• 配置边界要拆开：API Key 放环境变量，业务参数放配置文件，原始数据和处理数据分开存储。
• 数据访问放进适配层，避免业务代码绑死在具体 SDK 方法或 REST 路径上。
• 读取 00700.HK 后要做标的格式、日期范围、重复日期、OHLC、负值和复权口径校验。
• QuantDash 官方公开支持港股市场、统一标的代码、Python SDK 和 REST API；具体接口细节以官方文档为准。

QuantDash 官方资源

• QuantDash 官网 — 了解 QuantDash 量化数据 API 及产品能力：https://quantdash.net/
• QuantDash 技术文档 — 查看 Python SDK、REST API 及数据接口文档：https://docs.quantdash.net/zh-Hans
• QuantDash REST API — REST API 服务入口：https://api.quantdash.net
• QuantDash 官方 GitHub — 查看官方项目及开发资源：https://github.com/quantdash-net/QuantDash