AllTick
-
市场数据实时市场数据金融数据 交易技术

实时行情接口收到的时间戳为什么和本地时间对不上?

实时行情时间戳与本地时间不一致,可能与时区转换、时间戳单位、服务器时钟或交易时间有关。本文介绍秒级与毫秒级时间戳、UTC转换及行情时间与接收时间的正确处理方式。

AllTick阅读 5 分钟

接入实时行情接口后,有些开发者会遇到一个看似奇怪的问题:价格能够正常更新,但页面显示的行情时间却与电脑本地时间相差几个小时。有时差 8 小时,有时差 4 小时,还有些情况下,转换后的日期甚至直接跳到了 1970 年。

遇到这种情况,第一反应往往是怀疑 API 返回了错误的时间,或者行情数据存在延迟。但实际上,问题可能出在时间戳单位、时区转换、服务器系统时间,甚至是对行情更新时间的理解上。

想要准确判断实时行情数据是否延迟,首先需要弄清楚接口返回的时间究竟代表什么。

先分清行情时间和本地接收时间

行情接口返回的时间戳,并不一定是数据到达开发者服务器的时间。

在实时行情系统中,至少有三个时间需要区分:

  • 行情时间:行情记录对应的时间,例如某条 Tick 或盘口数据的报价时间。
  • 接收时间:应用程序实际收到这条数据的时间,由自己的服务器或客户端记录。
  • 显示时间:前端按照用户所在时区转换后展示的时间。

这三个时间并不一定相同。

例如,行情数据对应的时间是 10:00:00,但服务器在 10:00:00.150 才收到数据。此时两个时间相差 150 毫秒,并不意味着时间戳转换错误。

另外,Unix 时间戳表示的是一个绝对时间点,并不直接携带北京时间、纽约时间等本地时区信息。如果程序直接把时间戳转换成本地日期,却没有明确指定时区,那么不同服务器、不同运行环境就可能出现不同的显示结果。

因此,建议在后端统一使用 UTC 保存原始行情时间,前端再根据用户的时区进行转换。这样既能避免不同时区的数据混乱,也方便后续计算行情更新间隔。

毫秒和秒混用也是常见原因

如果时间相差不是固定几个小时,而是出现 1970 年、远未来日期等异常,就需要优先检查时间戳单位。

常见的 Unix 时间戳有两种:

  • 秒级时间戳:通常为 10 位数字。
  • 毫秒级时间戳:通常为 13 位数字。

例如,某接口返回的时间戳是 1793260800000,如果程序按照秒级时间戳解析,就会得到完全不合理的日期。

这里还有一个容易忽略的问题:不同接口的时间字段,即使都叫 timestamp 或 tick_time,也不代表使用相同的单位。

以 AllTick 为例,其 HTTP 盘口数据中的 tick_time 使用毫秒时间戳,而 K 线数据中的 timestamp 使用秒级时间戳。开发者如果将两种数据交给同一个未经区分的转换函数,就可能出现时间异常。

可以将时间解析逻辑集中处理,但必须根据具体字段定义选择对应的单位。

下面以 Python 为例:

text
from datetime import datetime, timezone
from zoneinfo import ZoneInfo

# 示例使用北京时间
DISPLAY_TZ = ZoneInfo("Asia/Shanghai")

def tick_time_to_utc(value):
    # 毫秒级时间戳
    return datetime.fromtimestamp(
        int(value) / 1000,
        tz=timezone.utc
    )

def kline_timestamp_to_utc(value):
    # 秒级时间戳
    return datetime.fromtimestamp(
        int(value),
        tz=timezone.utc
    )

# quote 为已解析的 HTTP 盘口数据记录
quote_time_utc = tick_time_to_utc(quote["tick_time"])

# 转换为指定时区进行展示
quote_time_local = quote_time_utc.astimezone(DISPLAY_TZ)

# 在收到行情消息时记录本地接收时间
received_at_utc = datetime.now(timezone.utc)

# 计算观测到的时间差,单位为毫秒
observed_gap_ms = (
    received_at_utc - quote_time_utc
).total_seconds() * 1000

这里需要注意,Asia/Shanghai 只是展示示例。如果系统面向美国股票市场,可以使用 America/New_York;如果需要按用户所在时区展示,则应使用对应的时区标识。

对于 K 线数据,调用 kline_timestamp_to_utc() 即可,不应该直接套用毫秒转换逻辑。

交易时间和行情更新时间不能混为一谈

还有一种情况容易被误判为时间戳异常:行情时间长时间没有变化。

例如,应用正在订阅某只股票的实时行情,WebSocket 连接正常,但价格和时间戳都停留在上一条数据。

这时不一定是 API 出现故障。股票市场可能已经进入午间休市或收盘时段,也可能暂时没有产生新的报价或成交数据。

需要注意的是,交易时间不等于行情持续更新时间。交易所的交易日历、开盘时间和休市安排,都会影响行情更新情况。不同市场的交易时间也不相同。

排查时,可以同时观察三个信息:当前是否处于该产品的交易时段、WebSocket 连接和心跳是否正常,以及接口是否收到了新的行情消息。

如果行情时间戳在持续更新,但与本地接收时间之间的差值逐渐增大,还应该检查服务器系统时钟。生产环境建议使用 NTP 或 Chrony 同步系统时间,否则服务器自身的时钟偏差也会影响延迟判断。

接入实时行情接口时建立统一时间处理逻辑

对于需要同时展示股票、外汇、加密货币等多种市场数据的应用,最好不要在每个业务模块中单独处理时间转换。

更合理的做法是,在数据接入层根据接口定义解析时间戳,统一转换为带 UTC 时区信息的时间对象,再将行情时间、接收时间分别保存。展示层则根据用户时区或对应市场时区进行转换。

AllTick 提供 REST API 和 WebSocket API,开发者可以根据业务需求获取实时行情、盘口以及历史 K 线数据。不同接口的数据字段和时间定义需要分别核对,尤其不要将 Tick、盘口和 K 线数据直接套用同一套时间解析规则。

如果正在开发实时行情监控页面或量化数据处理系统,可以查看 AllTick 官方产品与开发入口,了解支持的行情数据类型及相关接口。

对于时间戳异常,排查顺序其实很明确:先确认字段代表的时间,再检查秒与毫秒的转换,接着核对时区,最后比较行情时间和实际接收时间。把这几个环节分开处理,才能判断问题究竟出在数据解析、服务器时钟,还是行情更新本身。

立即开始接入市场数据

几秒内生成免费 API 密钥,通过一个端点连接所有市场。