API 设计：分页、错误合同、单位 | 金融数据技术

01学完你能做到

为静态快照和持续变化的数据选择偏移分页或游标分页。
设计包含错误码、字段、可重试标记和修复提示的错误响应。
为金额、比例、数量和时间字段明确单位、精度和时区。

02这课解决什么问题

数据算对了、服务也扛得住，用户为什么仍可能用错？常见原因是 API 没把分页边界、错误处理和数字单位写成清晰的合同。

03分页

偏移分页用 page/page_size 或 offset/limit 定位，直观且能跳页，但数据在翻页期间插入或删除时可能重复或遗漏，深翻页也可能越来越慢。

游标分页使用服务端返回的书签，例如 next_page_token。调用方不需要理解令牌内容，只需原样带回。它更适合持续变化的数据和深翻页，但不方便直接跳到第 50 页。

无论采用哪种方式，都应说明稳定排序、快照边界和是否还有下一页。例如：

{
  "items": [{"code": "000001.SZ"}],
  "next_page_token": "opaque-token",
  "has_more": true
}

对一个已收盘且固定的快照，偏移分页通常足够；对逐笔成交、新闻流等持续增长的数据，游标更稳妥。

04错误合同

错误响应至少要让调用方知道：错在哪、为什么错、能否重试、如何修复。RFC 9457 Problem Details 常见字段包括 type、title、status、detail 和 instance，还可以增加 field、constraint、retryable 等扩展字段。

{
  "type": "https://example.com/problems/invalid-argument",
  "title": "参数不合法",
  "status": 400,
  "detail": "page_size 必须在 1 到 500 之间",
  "field": "page_size",
  "constraint": "1..500",
  "retryable": false
}

通常 4xx 表示调用方要修改请求，5xx 表示服务端或上游暂时异常，但是否可重试仍应由稳定字段明确表达，不要让调用方猜状态码。

05单位、精度与时间

每个数值字段都要说明单位、口径和精度：金额是元还是万元，比例是 0.0031 还是 0.31，成交量是股还是手，价格是否使用定点小数或字符串。时间要说明是 Unix 毫秒还是带时区的 RFC 3339 字符串，例如 2026-10-28T15:00:00+08:00。

金融接口尤其要避免“比例值直接加百分号”。若接口返回 turnover_rate = 0.0031，展示为百分数时是约 0.31%，不是 0.0031%。

06常见误区

分页没有稳定排序，翻页过程中结果重复或遗漏。
不返回 has_more 或下一页令牌，调用方只能多发一次空请求试探。
只返回自然语言错误，没有稳定 code 和 retryable。
所有错误都返回 200 或都返回 500，调用方无法区分责任。
单位写在另一份文档里，字段本身没有描述。
金额直接使用二进制浮点累加而不明确精度。
时间戳不注明时区，导致跨地区调用出现日期偏移。

07延伸阅读

08一分钟讲给别人

试着用自己的话讲一遍API 是一份合同。分页要保证翻完不重不漏，静态快照可用页码，持续变化的数据更适合游标。报错要说明字段、原因、能否重试和下一步。金额、比例、数量和时间都必须写清单位与口径，否则一个小数点就可能让调用方差一百倍。

想一想

5 道自测

先在心里答一遍，再展开对照。能说清理由，比答对数字更重要。

01偏移分页和游标分页分别适合什么场景？
02RFC 9457 Problem Details 的常见核心字段有哪些？
034xx 和 5xx 对调用方意味着什么？
04比例值 0.0031 展示为百分数是多少？
05为什么分页必须有稳定排序？

已看 0/5 题

练动手练习

任务：为一个股票日 K 查询接口补齐分页、错误和字段说明：稳定按代码排序；返回 has_more 与不透明游标；为 turnover、volume、turnover_rate 和时间字段补充单位、精度和时区；为参数错误增加 field、constraint 和 retryable。

完成这一课

读完讲义、看完自测答案，这一课就算学完了。

读完讲义
看完全部自测

本课为投资者教育内容，案例数字均为示意，不构成任何投资建议，也不承诺收益。规则和费率会变，实际操作前请以交易所、监管机构和产品的最新公告为准。