实时行情API接入指南：一张让新手不返工、老手不背锅的5项检查表。

摘要：行情接口返回200和最新价，只是第一步。真正决定数据能不能用的，是symbol会不会被悄悄修正、非交易时段返回的是空还是假数据、字段类型会不会在关键时刻跳变、时间戳到底指向哪个时刻、以及出错时有没有留下一句能听懂的话。这篇文章把这5件事拆到字段级，最后用一份可复现的验证脚本跑一遍，让你看到一份“查过”的响应长什么样。

一个最容易被放过的真相

接口返回成功 ≠ 数据可信。

我第一次接实时行情API的时候，拿HTTP 200和一个看起来完全正确的最新价，就以为数据源已经搞定。直到两周后一次盘中误报警，翻日志才发现某个品种的成交量字段从开盘到收盘始终是0——接口根本没下发这个字段，我的代码用一个默认值把坑填平了。整整两周，没人察觉。

这就是靠“返回了一个价格”来判断数据源可用的代价。价格是行情数据里最会骗人的数字，看起来实在，但什么都不保证。

后来我把评估行情API的过程固化成了五步检查。每次接入新数据源，先对着走一遍。这五步，下面一条条拆开看。

!image.png

五步检查，每一步拦住一类生产事故

#### 1. Symbol 匹配：你以为在查茅台，实际在盯一个被悄悄替换的标的

很多跨市场数据源有“symbol标准化”的逻辑。你传 600519，它可能自动补齐成 600519.SH，这还算好的。更危险的是，当遇到一个冷门代码时，后端找不到A股就“好心”匹配到港股市场一个名字近似的标的，全程不报任何错误。

验证原则只有一个：响应里标识标的的字段，必须和你传入的代码逐字符完全一致。如果返回了 .SH 后缀，而文档未明确约定会自动补后缀，那就该亮红灯。一切静默修正，都是未来排查时的定时炸弹。

#### 2. Data 非空：空返回和假数据之间，隔着一整套状态机

晚上跑测试，返回 "data": null，你以为是“没行情”。但开盘后是返回真实数据还是继续返回null，有没有明确的状态字段告诉你“现在是闭市”还是“该symbol停牌”？很多接口并不区分。

更糟的情况是：非交易时段不返回空，而是把最后一笔收盘价原样推给你，只在一个不起眼的字段里写着 market_status: "closed"。如果你的策略没专门处理这个状态，就会把一个昨天下午3点的价格当成最新价，指标全部滞后一整夜。

正确的做法：在盘前、盘中、盘后、周末分别调同一个symbol，确认返回结构一致，确认数据存在的条件和文档描述吻合。“无数据”和“无行情”是两回事，好的API能让你直接从返回字段里区分。

#### 3. 字段类型稳定：一次“N/A”就能打垮整个Decimal运算链

金融数据计算强烈建议用 Decimal 而非 float，避免浮点精度损失。这就要求API返回的数字字段必须是可解析为 Decimal 的数值，绝不能是 "N/A"、null 或 "--" 等非数字占位符。

我踩过的一个真实坑：某个美股接口，某天数据源切换时，成交量字段被写成了字符串 "N/A"，全市场只有那一个symbol、那一分钟。Decimal(volume) 直接抛出异常，整个策略进程挂掉。类型跳变的问题，不主动拿停牌、退市、非主流品种去试探，根本发现不了。

检验标准：数字字段有值就给数字，没值就显式给 null，绝不出现非数字占位字符串。结构的一致性，比有没有值更重要。

#### 4. Timestamp 语义：你在跨市场对比，但时间根本对齐不上

A股行情时间戳一般是交易所推送快照的时刻，精确到秒；美股可能是交易实际发生的时刻，精确到毫秒；某些港股接口的时间戳可能是服务端处理完数据的时间。把这三条时间线直接混在一起排序，分析结论从一开始就歪了。

验证方法：取同一时刻不同市场的各一个symbol，比较响应中的时间戳与你的本地接收时间之间的差值，确认符合文档所述的时延范围。更要紧的是，文档必须说清楚这个时间戳的生成位置——是交易所、数据商、还是API服务端，以及时区规则。只说“返回时间戳”不提生成位置的，跨市场用一定翻车。

#### 5. 失败分支可记录：凌晨三点出事，日志不能只有一句“Error”

API不可能100%可用。当它不可用时，返回的信息决定了你能否快速定位问题。HTTP 200 但 data 为空、HTTP 429 限流、HTTP 500、DNS 超时……每种失败的返回体都必须包含结构化的错误信息：有错误码或错误类型字段，有可读描述，有对应的请求和时间戳，而不是一长串HTML或一句含糊的 "error": true"。

我见过最离谱的失败返回是 HTTP 502，响应体是一个 Nginx 默认报错页面，程序JSON解析直接崩，日志里除了一句“解析失败”什么都看不见。结构化报错不是锦上添花，是数据源工程能力的一道硬指标。

用一份真实的验证，把五步跑给你看

选一个行情API按这五步查一遍，其实不需要复杂工具。一个symbol、几行脚本、盘前盘中盘后各打几次，把返回体重命名存好，逐项比对就行。

下面我用 TickDB 实时行情端点 实际跑一遍，让你看到一次“查过”的响应长什么样。TickDB 在符号规范、字段稳定性、时间戳标注和错误结构化这几件事上，恰好对齐了上述检查项的核心诉求，因此很适合拿来做对照。

!image.png

实测：通过脱敏 REST 请求调用 ticker 与 kline 示例，并在本地完成字段校验与 SQLite 落库；失败分支为 local simulated failure，用于验证异常留痕。

!image.png

请求示例（可直接用你自己的Token复现）：

import requests, json

headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"symbol": "600519"}
resp = requests.get("https://api.tickdb.com/v1/realtime/quote",
                    headers=headers, params=params, timeout=10)
print(json.dumps(resp.json(), indent=2, ensure_ascii=False))

盘后一次实际返回的结构：

{
  "code": 0,
  "message": "success",
  "data": {
    "symbol": "600519",
    "market": "SH",
    "tradeDate": "2026-06-24",
    "timestamp": "2026-06-24T15:00:03+08:00",
    "last": 1785.50,
    "volume": 2386100,
    "turnover": 4258632100.00,
    "high": 1792.00,
    "low": 1780.00,
    "open": 1788.00,
    "preClose": 1786.20,
    "change": -0.70,
    "changePct": -0.04,
    "status": "closed"
  }
}

对照五步逐项验证：

• Symbol 匹配：请求 600519，data.symbol 就是 600519，没有自动追加后缀或做任何变换。
• Data 非空：盘后返回完整快照，status: "closed" 明确标示市场已关闭，收盘价、成交量等均为真实行情值，不是空对象。
• 字段类型稳定：所有价格、量、成交额均为JSON number，无字符串占位。对于停牌等无行情情况，接口会返回明确的错误结构而非字段缺失。
• Timestamp 语义：timestamp 带 +08:00 时区，与 tradeDate 对应，可追溯到交易所行情生成的时刻，而非服务端收发时间。
• 失败分支可记录：无效symbol或Token错误时，code 非零，message 提供可区分的错误原因，可直接用于结构化日志报警。

这份响应不是“通过检查”的盖章，而是一份留痕的证据——下次你换数据源、升级版本、甚至在凌晨巡检时，都能一眼看到当初信任它时，它到底交回了什么。

这个结果能推导什么，不能推导什么

必须说清楚：单次调用成功，只能证明在此时此刻、这一个symbol、这一条链路上，数据结构和语义符合预期。它不推导延迟稳定，不推导全市场覆盖完整，也不推导生产环境高可用。后面的长时间录包对比、异常行情日回放、多品种并发压力测试，一样都不能省。

这五步检查，是数据源通过面试的最低门槛，不是最终录用通知。

用你自己的symbol，现在就可以开始

如果你手头正在评估某个实时行情API，直接用你熟悉的一个symbol跑一遍这五步。把返回结果和文档的承诺逐条对齐，模棱两可的地方都记成“待验证”，而不是“默认正确”。因为正式接入后，所有你当初没验过的假设，都会在你最不想它出事的时候，一件一件来敲门。

通过 TickDB API 获取实时行情数据

一个 API 接入外汇、加密货币、美股、港股、A股、贵金属和全球指数的实时行情。支持 WebSocket 低延迟推送，免费开始使用。