企业官网建设流程全解析

做量化、做行情看板、做交易辅助工具的人，几乎都绕不开同一个环节：找一批能用的行情接口，然后一个个点开验证到底通不通、字段全不全、延迟能不能接受。我把这件事拆成两半来看——实时股票数据API接口负责"当下这一秒市场是什么状态"，股票历史行情查询API接口负责"过去这段时间它经历了什么"。这两条链路看着都是发个HTTP请求拿JSON，但真正落地时会发现它们的坑完全不是同一批：实时接口坑在频率、推送、断线补偿，历史接口坑在复权、停牌、时区对齐。这篇文章不打算给你一串点开就失效的链接，而是把"怎么自己搭一套可点击验证的接口清单、怎么判断一个接口值不值得用、实测中哪些地方最容易翻车"讲透。不管你刚入门想跑通第一个行情Demo，还是已经在维护一条数据管道想补一补校验环节，下面这些内容应该都能直接拿去用。

1. 实时与历史两条接口链路的本质差异

很多人一开始会把这两类接口当成同一件事，觉得无非是参数里多传一个日期区间。真上手跑两天就会发现，它们的调用模型、字段设计、失败模式几乎没有交集，混在一起设计代码，后面一定返工。

1.1 一次行情请求里真正有价值的字段只有十来个

不管接口文档写了几十个返回字段，实际业务里高频用到的就那么一批：标的代码、标的名称、最新价、昨收价、今开价、最高价、最低价、成交量、成交额、行情时间戳、交易状态。做盘口展示的还会要买卖五档或十档，做资金流的会要内外盘和换手率，做衍生计算的会要涨跌幅、振幅、量比。

这里有个细节值得单独说：涨跌幅不要直接用接口返回的值，一定自己拿(最新价 - 昨收价) / 昨收价重算一遍。原因很现实，不同数据源对"昨收"的处理口径不一致，有的在除权日当天仍然返回未调整的昨收，导致算出来的涨跌幅和主流终端差好几个点。自己重算虽然多一行代码，但能保证你的口径是自洽的——最新价和昨收是同一套数据，比例关系不会错。

再一个是行情时间戳。这个字段必须校验，而且是整个验证环节里最容易被忽略的一环。我在排查一个"数据不刷新"的问题时，花了大半天怀疑缓存、怀疑推送断了，最后发现接口返回的ts已经停在两个小时前，服务端只是还在正常回 200。从那以后我养成了一个习惯：任何一个实时接口接进来，第一件事是打一行日志，把本地时间和接口时间戳的差值打出来。

1.2 实时推送与历史回溯的调用模型根本不兼容

实时链路的本质是"高频小包"。你关心的是最近几秒，数据量小但要求快，所以主流做法是长连接推送或者高频轮询。历史链路的本质是"低频大包"，一次要几百上千个交易日，返回体动辄几MB，要求的是完整性和一致性，而不是延迟。

把这两者塞进同一个客户端封装里是常见的错误设计。我见过一种写法：统一一个fetch(code, start, end)函数，实时场景传start=end=今天，历史场景传区间。代码看着优雅，实际跑起来问题一堆——实时场景下这个函数没法复用连接、没法做增量、没地方放断线重连逻辑；历史场景下它又被实时那套超时时间卡死。

正确的做法是拆成两个独立模块。实时模块对外只暴露"订阅某个标的集合"和"收到一条快照"两个概念，内部是轮询还是推送对上层透明。历史模块对外暴露"按标的和区间取日线/分钟线"，内部处理分页、重试、落盘缓存。两个模块共用的是标的代码规范和时间格式转换这类基础工具，业务逻辑绝不共用。

还有一点，历史数据是"可缓存、可复现"的，同一段区间今天拉和明天拉结果应该一样（除非发生复权调整）；实时数据是"一次性"的，错过了就是错过了。这个性质差异决定了历史接口可以放心做本地缓存甚至离线数据集，实时接口必须每次真打。

2. 接口清单不是收藏夹，验证测试要验的具体项目

标题里"可直接点击验证测试"这几个字，真正有价值的不是"点击"这个动作，而是点击之后你看到了什么、怎么判断通过还是失败。一堆链接点开全是"参数错误"，那不叫清单，那叫待办事项。

2.1 单接口冒烟测试：四步判断能不能用

我判断一个新接口值不值得继续投入，通常按这四步走，全程不超过三分钟。

第一步看连通性和响应头。状态码 200 只是及格线，还要看Content-Type。有些接口出错时返回 200 加一段 HTML 错误页，你按 JSON 解析直接抛异常，日志里全是解析错误，很容易误判成"接口不稳定"，其实是鉴权没过。

第二步看返回体结构。把返回内容打印出来，确认顶层是对象还是数组，业务数据藏在哪一层，错误码字段叫什么。不同来源对错误的表达五花八门，有的是 HTTP 状态码，有的是code != 0，有的是{"error": "..."}，还有的干脆返回空数组表示失败。这一步摸清楚了，后面所有异常处理才有依据。

第三步看关键字段是否齐全且类型正确。价格是字符串还是数字，这个差异会咬人。字符串"12.30"直接参与算术运算在某些语言里会隐式转换，在另一些语言里会报错或者拼接。我一般会在接入层统一做一次类型归一化，把价格转成浮点、成交量转成整数、时间统一成毫秒时间戳。

第四步看数据合理性。这一步是真正拉开差距的地方，很多人跳过。合理的判断规则很朴素：最高价必须大于等于最低价；最新价必须落在最高和最低之间（盘前除外）；成交量、成交额不能为负；成交量大于 0 时成交额也必须大于 0；成交额除以成交量得到的均价，应该落在最低价和最高价之间。这几条规则拦不住所有脏数据，但能拦住绝大多数明显错误的记录。

def sanity_check(tick): # 以任意HTTP客户端取到数据后，先做合理性校验 if tick["high"] < tick["low"]: return False, "最高价低于最低价" if tick["volume"] < 0 or tick["amount"] < 0: return False, "成交量为负" if tick["volume"] > 0: avg = tick["amount"] / tick["volume"] if not (tick["low"] * 0.95 <= avg <= tick["high"] * 1.05): return False, "均价偏离价格区间，疑似单位不一致" if tick["last"] and not (tick["low"] <= tick["last"] <= tick["high"]): return False, "最新价越界" return True, "ok"

注意上面那个 0.95 和 1.05 的容差。为什么留这么宽？因为成交量单位有的是股、有的是手，成交额单位有的是元、有的是万元，不同来源混用时均价会差一个数量级。留宽一点先让你的校验规则不误杀，等确认了单位口径再收紧。这个"先宽后紧"的思路，比一上来就写死精确阈值实用得多。

2.2 用脚本批量跑一遍，把结果落成一张表

手工点几十个接口不现实，也不可复现。写个批量探测脚本，把所有待验证的接口配置成一张表，跑一遍输出结果表，这是最省事的做法。

配置表里每个条目至少包含：接口标识、请求地址、请求方法、鉴权方式、关键参数、期望字段列表、超时时间。跑的时候并发开小一点，比如 4 到 8 个并发，控制住节奏，别一上来就把自己的额度打光。每个请求记录：状态码、耗时、返回体大小、期望字段命中率、合理性校验结果、失败原因。

results = [] for item in endpoint_list: t0 = now_ms() try: resp = http_get(item["url"], item["params"], headers=item["headers"], timeout=item["timeout"]) cost = now_ms() - t0 body = try_parse_json(resp.text) if body is None: results.append((item["id"], "FAIL", cost, "非JSON返回")) continue missing = [f for f in item["fields"] if f not in flatten(body)] ok, reason = sanity_check(extract_tick(body)) status = "OK" if not missing and ok else "WARN" results.append((item["id"], status, cost, f"缺失字段:{missing} 校验:{reason}")) except TimeoutError: results.append((item["id"], "TIMEOUT", now_ms() - t0, "超时")) except Exception as e: results.append((item["id"], "ERROR", now_ms() - t0, str(e)))

跑完之后你手上会有一张表，哪几个能直接用、哪几个字段缺、哪几个超时，一目了然。这张表的另一个价值是"留痕"——过一个月再跑一遍，两张表一对比，就知道哪些接口悄悄改了返回结构。我吃过这个亏，某个接口把价格字段从数字改成了字符串，我的解析逻辑没报错，但下游排序全乱了，查了很久才发现是源头变了。

提示：批量探测一定要在非交易时段也跑一遍。有些接口在收盘后返回的是上一交易日的收盘快照，字段齐全、格式正确，看起来一切正常，但你在盘中用它做实时展示就会出问题。非交易时段的测试结果，要和盘中结果分开看。

3. 实时行情接口落地：轮询和推送各自要处理的麻烦

实时这块没有银弹，就两条路：定时轮询或者长连接推送。选哪条不取决于哪个"更先进"，取决于你的标的数量、刷新频率要求和可用的调用额度。

3.1 轮询方案的分批计算与限速设计

轮询最大的问题不是技术难度，是额度。假设你要覆盖全市场约 5000 个标的，接口单次最多返回 100 个标的的快照，那么完整刷一轮需要 50 次请求。如果你希望 3 秒刷新一次，就需要每秒约 17 次请求。这时候去查接口的限频说明，如果限制是每分钟 300 次，也就是每秒 5 次，那你的目标根本达不到。

这个计算一定要提前做，别写完代码跑起来才发现被限流。算完之后有三条出路：降低刷新频率，比如改成 10 秒一轮，那么 50 次请求摊到 10 秒，每秒 5 次，刚好卡在限频线上，但没有任何余量，稍有波动就会被限；减少标的范围，只盯你真正关心的那几百个；或者换推送方案。

我个人偏好一种折中做法：把标的池分层。核心池（自选、持仓、监控列表）高频刷新，比如 3 秒；外围池（全市场概览、涨跌分布统计）低频刷新，比如 30 秒甚至 60 秒。这样既保证了关键数据的时效性，又把总请求量压到可控范围。实现上就是两个独立的轮询调度器，各自维护自己的间隔和批次。

分批的时候还有一个细节：批次之间的间隔要均匀打散，不要 50 个批次连着发完然后空等 3 秒。均匀打散能让服务端压力平滑，也能让你在某一批失败时只影响那一小部分标的，而不是整轮数据都拿不到。我的做法是把一轮的 3 秒切成 50 个时间片，每个时间片发一批，用定时器驱动，而不是用一个 for 循环加 sleep。

BATCH = 100 INTERVAL_MS = 3000 def schedule_round(codes): batches = [codes[i:i+BATCH] for i in range(0, len(codes), BATCH)] slot = INTERVAL_MS / max(len(batches), 1) for idx, batch in enumerate(batches): delay = idx * slot timer_after(delay, lambda b=batch: fetch_and_store(b))

失败处理上，批次级别的重试要克制。一批失败就记一次失败，连续失败超过阈值才降级，别一批失败就立刻重试三次，那样在服务端抖动的时候会形成放大效应，把自己推入更深的限流里。

3.2 推送方案的重连、去重与乱序三件套

长连接推送省额度，实时性也好，但你要自己处理三件事，缺一件都会在生产环境里出问题。

重连。网络抖动、服务端重启、空闲超时，都会导致连接断开。重连不能是死循环狂试，要用指数退避，比如 1 秒、2 秒、4 秒、8 秒，上限 30 秒，并且加一点随机抖动，避免大量客户端在同一时刻同时重连。另外要加心跳，客户端定期发一个轻量消息，超过两三个心跳周期没收到回应就主动断开重连，别指望 TCP 层帮你发现"连接还在但对面已经不推数据了"这种半死状态。

去重。同一条快照可能被推两次，特别是重连之后服务端补发的时候。去重键用"标的代码 + 行情时间戳"，维护一个最近时间戳的映射表，收到新数据先比对，时间戳不新就丢掉。这个映射表不需要很大，保留最近几千条就够了，定期清理。

乱序。推送通道不保证顺序，尤其是在多路复用或者重连补发的场景下，你完全可能先收到 10:30:05 的数据，再收到 10:30:03 的数据。如果直接覆盖本地状态，界面上的价格会莫名其妙往回跳。处理办法和去重合并成一件事：永远只接受时间戳比当前值更新的数据。这一条规则同时解决了去重和乱序。

还有断线补偿一定要做。重连成功之后，不要干等着收推送，立刻主动发一次全量快照请求，把断线期间丢失的状态补齐。这个补偿请求是必须的，因为推送通常只推变化，断线期间没变化但状态已经变了的标的，你永远等不到推送。

注意：连接建立成功不等于订阅成功。有些推送服务需要你先发一条订阅消息，收到确认回执之后才会真正开始推数据。我见过只判断了连接状态就以为万事大吉的实现，结果跑了半小时一条数据没收到，日志里干干净净。

4. 历史行情接口最容易翻车的三个地方

历史接口看起来最老实——给个区间，返回一堆K线。但真拿去做回测或者做长期图表，三个坑等着你：复权、停牌、时区。

4.1 复权方式选错，回测结果能差出一倍

先说清楚三种口径。不复权就是原始成交价，除权除息当天价格会出现一个跳空缺口，这个缺口不是市场行为，是股本变化导致的。前复权以最新价格为基准，把历史价格按复权因子往下调整，让整条曲线连续。后复权以上市首日为基准，把后面的价格往上调整。

选哪个取决于你要干什么。做近期走势图、做技术指标计算、做短线策略回测，用前复权，因为你的关注点在最近，历史价格被调整不影响你对当前价位的判断。做长期收益统计、做跨越多个年度的策略回测、做分红再投资收益计算，用后复权，因为后复权的历史值一旦确定就不会再变，你今天算出来的 2018 年收益率，明年再算还是同一个数。

这一点特别关键：前复权的历史数据是会变的。每次发生新的除权除息，整条历史曲线都要重新调整。这意味着你不能把前复权数据当成静态数据集缓存起来长期使用，缓存必须带失效机制，或者在每次除权日之后主动刷新。我见过把前复权日线落成本地文件、半年不更新的实现，跑出来的回测收益率漂亮得离谱，纯粹是因为数据口径错位。

复权因子的计算本身不复杂，核心是累计：后复权价 = 不复权价 × 累计复权因子，前复权价 = 不复权价 × 累计复权因子 / 最新累计复权因子。实际落地时建议直接使用数据源提供的复权因子字段，自己从分红送配明细推算容易在配股、转增这些边角情况上出错。

4.2 停牌与缺失交易日：别用"有数据"当"有交易"

历史接口返回的日线，停牌日通常是没有记录的。如果你的回测逻辑是"按返回的K线逐条推进"，那停牌就被自动跳过了，看起来没问题。但如果你的逻辑是"按自然交易日历逐日推进，每天去查当天数据"，那停牌日你就会拿到空值，轻则报错，重则被当成 0 价格参与计算，收益率直接爆表。

正确做法是维护一份交易日历，把"该交易日有没有这只标的的数据"和"这一天是不是交易日"分开判断。停牌日的处理方式取决于策略语义：如果是持仓策略，停牌期间持仓还在，只是不能交易，价格应该沿用停牌前最后一个有效收盘价；如果是选股策略，停牌标的直接排除出候选池。这两种处理方式的结果差异很大，一定要在代码里显式写清楚，别靠默认行为。

还有一种情况是数据源本身的缺失，不是停牌，是接口没返回。这种情况要靠"区间完整性校验"来发现：请求 2020-01-01 到 2020-12-31，返回的记录数应该和交易日历里这段时间的交易日数大致吻合，差几个可能是停牌，差几十个就是数据缺失。我一般会在拉取之后立刻做一次这个比对，缺失超过阈值就重新拉一次或者换源补。

def check_coverage(bars, calendar): have = {b["date"] for b in bars} expect = {d for d in calendar if d >= start and d <= end} missing = expect - have ratio = 1 - len(missing) / max(len(expect), 1) if ratio < 0.95: raise DataIncomplete(f"覆盖率{ratio:.2%}，缺失{len(missing)}个交易日") return missing # 少量缺失大概率是停牌，记录备查

4.3 时区和时间精度：一个不小心就错一天

时间戳的坑在两个地方。一是时区，很多接口返回的是 UTC 时间或者带时区偏移的字符串，你本地按东八区解析，日期就可能整体偏一天，尤其是凌晨的数据。二是精度，秒级和毫秒级时间戳混用，13 位的时间戳被当 10 位解析，日期直接飞到几万年后。

统一策略很简单：进来就归一化。所有接口的时间字段，无论原始格式是什么，接入层统一转成一个标准格式，比如毫秒时间戳或者YYYY-MM-DD字符串。日线的日期字段尤其要注意，不要用时间戳表示日期，因为同一根日线的"日期"在不同时区下会落在不同的自然日。日线就用纯日期字符串，分钟线用毫秒时间戳，两套各管各的，不要互相转换。

另外提醒一个容易忽略的点：分钟线的时间戳通常标记的是这根K线的开始时间还是结束时间，不同数据源不一样。1 分钟K线标记 09:30，可能是 09:30:00 到 09:30:59 这一分钟，也可能是 09:29:00 到 09:30:00。做跨源拼接或者做分钟级策略时，这个偏移会导致信号提前或滞后一分钟，回测和实盘的差异往往就出在这里。

5. 多源交叉校验与故障兜底

单个接口跑通了不代表数据可信。真正稳的做法是引入第二个来源做对账，再加上一套缓存降级，保证接口挂了页面不至于白屏。

5.1 三字段对账，用最小成本揪出脏数据

不需要全字段比对，比三个字段就够了：收盘价、成交量、成交额。这三个字段覆盖了价格、数量、金额三个维度，任何一个维度出问题都能被发现。

对账的规则要设容差，不能要求完全相等。价格容差可以设 0.01 或者 0.1%，成交量容差设 1%，成交额容差设 1%。超过容差就标记为"待确认"，不直接判定哪个错。为什么要留容差？因为不同来源对成交量的统计口径可能是"股"和"手"，对成交额可能是含大宗交易和不含，强行要求相等会产生大量误报，最后你对账报告就没人看了。

除了跨源对账，单源内部也可以做一致性检查，成本更低。比如：连续两根日线，今天的开盘价相对昨天的收盘价，如果偏差超过 30% 且不是除权日，那大概率有一根是错的；成交额除以成交量得到的均价，如果落在当天最高最低价区间之外，说明单位或者字段错位；某只标的连续多日成交量为 0 但价格在变，这明显不合理。

对账结果我建议落成一张表，按标的和日期记录差异幅度和差异方向，定期看一眼。如果某个数据源在特定类型的标的上持续偏离，那就是系统性问题，不是偶发脏数据，该换源就换源。

5.2 缓存、熔断与降级：接口不可用时页面该显示什么

任何依赖外部接口的系统都要回答一个问题：接口挂了怎么办。行情类应用的答案通常是"显示最后一次拿到的数据，并明确标注数据时间"。

本地缓存分两层。内存缓存放最近一次的实时快照，按标的索引，TTL 设得很短，比如一个刷新周期的两倍，过期就不用它做实时展示。持久化缓存放历史日线和基础信息，这类数据变化慢，TTL 可以按天算，甚至可以在每天收盘后统一刷新一次。

熔断要有，但不能太敏感。连续失败 5 次、持续 10 秒以上才熔断，熔断期间直接返回缓存数据并标记为降级状态，同时后台用较低的频率继续探测，探测成功就自动恢复。熔断阈值设得太低，服务端稍微抖一下就熔断，用户看到的是频繁的数据闪烁；设得太高，接口真挂了还在那儿傻等超时，页面卡死。

降级状态下前端一定要给用户可见的提示，标明"当前展示的是 XX 时刻的数据"。这不是产品体验问题，是数据诚信问题。我见过行情页面上的价格停在半小时前但界面上毫无提示，用户照着这个价格做决策，后果比接口报错严重得多。

提示：缓存键的设计要考虑复权口径。同一个标的的前复权日线和后复权日线必须用不同的缓存键，否则某次代码改动切换了口径，缓存里混着两套数据，排查起来极其费劲。我的做法是把口径作为缓存键的一部分，bars:{code}:{period}:{adjust}这样，宁可多占点空间。

6. 把接口清单做成可点击验证的页面

回到标题里"可直接点击验证测试"这件事。如果只是在自己的笔记里存一堆链接，价值有限；做成一个能随时打开、点一下就看到实时结果的页面，价值会高很多，尤其是团队协作场景。

6.1 清单的字段设计：按能力维度分而不是按供应商分

我见过不少清单是按数据来源分组的，一大类下面挂几十个接口。这种组织方式的问题是，当你需要"找所有支持分钟线的接口"时，得把每一组都翻一遍。

更好的组织维度是按能力分：基础信息类（标的列表、交易日历、行业分类）、实时快照类（单标的、批量、盘口）、历史K线类（日线、周线、分钟线）、衍生数据类（复权因子、指数成分、资金流）。按能力分好之后，每个接口条目再记录来源、鉴权方式、限频、字段完整度、实测延迟。

每个条目的核心字段建议这样设计：

"实测延迟"这一列特别值得保留。文档上写的延迟和实际打出来的延迟经常差一个数量级，而且同一批接口在不同时段表现也不一样。我一般会在盘中和非盘中各采样一次，记录中位数而不是平均值，避免个别超长请求把均值拉高。

"鉴权方式"这一列是为了避免泄露。如果接口是"URL 带密钥"的形式，那这个链接一旦发到群里、写进文档、提交到代码仓库，密钥就等于公开了。这类接口在清单里一定要把密钥部分做脱敏处理，写成占位符。

6.2 自建验证页的最小实现：后端代理加状态标记

直接在前端页面里写请求地址和密钥是最省事也最危险的做法。打开浏览器开发者工具，密钥一览无余。正确做法是加一层后端代理：前端只传"接口标识"，后端根据标识找到真实的地址和密钥，发起请求，把结果返回给前端。

这样做还有个额外好处：浏览器的跨域限制和后端的签名计算都在代理层解决，前端逻辑可以非常简单。一个最小的验证页只需要三块内容——接口列表（按能力分组，带状态标记）、点击后的请求详情（请求URL脱敏后展示、响应状态码、耗时、返回体前若干字符）、字段解析结果（关键字段表格化展示加合理性校验结论）。

后端这边，把接口配置放在一个独立的配置文件里，密钥从环境变量读取，不要硬编码。代理接口本身也要做限制，只允许白名单内的接口标识通过，否则就变成了一个开放代理，别人可以拿你的服务器去打任意地址。

对于实时推送类接口，验证页面没法用简单的请求-响应模型测。我的做法是单独做一个"连接测试"按钮：后端建立连接，收满 N 条消息或者等 M 秒，把收到的消息条数、首条消息到达时间、消息间隔的中位数统计出来返回。这三个指标基本能判断推送是否正常工作——条数为 0 就是没通，首条到达时间过长说明有握手延迟，间隔中位数异常说明推送频率和文档不符。

最后分享一个我一直在用的小习惯：每次验证完一批接口，把结果表连同日期一起存下来。过一段时间回头看，能清楚地看到哪些接口悄悄改了字段名、哪些延迟变差了、哪些开始返回限流错误。这份历史记录的价值，比当下这一刻的验证结果大得多。