分数线列表接口接入：分页、科类与空值处理｜数据鱼API

省考试院公布投档线后的两天，是志愿填报工具访问量最高的时候。有团队图省事，把整省数据打包成静态 JSON 交给前端，首屏要等几秒，切换科类还会卡顿；改成按条件分页查询、只取当前页需要的字段之后，页面才稳定下来。

这次拿数据鱼API的「全国高考数据查询」服务做示例，对应「分数线列表」分支（GET /v1/api/gaokao/score-list）。分页返回分数线。

分数线列表接口 GET /v1/api/gaokao/score-list 面向的就是这种列表读取：先确定省份，再叠加科类、批次条件，返回分页后的投档线记录。它不负责搜索院校，也不做位次换算，定位很单纯。

省份是硬条件，科类和批次决定口径

province 是必填参数，不传会返回 400。服务端不会默认返回全国数据，调用方必须先明确省份，这一点和多数学科类接口不同。

subject 和 batch 可选，但业务上几乎一定会用到。subject 的取值跟随各省高考模式：北京常见“综合”，河北常见“物理”“历史”，少数省份仍是“理工”“文史”。batch 对应“本科批”“本科提前批A段”这类批次名称。不要把这两个枚举写死在前端，比较稳妥的做法是按省份从数据里聚合候选值，或者维护一份可配置的映射。

分页由 page 和 page_size 控制，默认每页 20 条，上限也是 20，超出按边界值处理。返回中的 data.total 是符合条件的总条数，用来算总页数；data.page 和 data.page_size 会回显实际生效值，翻页组件应以回显值为准。

返回字段里哪些能直接展示

每条记录围绕院校和专业组展开：

• school_name：院校名称，列表主字段。
• score：录取分数，做线差计算的基础。
• rank：对应位次，部分记录为 null。
• major_group_code：专业组代码，同一院校可能有多条记录，按它区分。
• subject_req：选科要求，例如“物理+化学”“不限”，直接决定考生能不能报。
• plan_num 与 admitted_num：计划招生人数和录取人数，不少记录为空。

data.list 返回空数组属于正常结果，前端展示“暂无数据”即可，不要当成接口故障去重试。列表顺序以接口返回为准，做前端二次排序时保留一个稳定的次级排序键，避免翻页时同分记录来回跳动。

缓存怎么设

投档线在批次公布后相对稳定，但征集志愿阶段仍可能补充或修正。缓存键建议用 province + subject + batch + page，缓存时间不要跨过批次节点；返回记录里的 year 和 created_at 可以用来判断数据版本，发现同一条件两次结果不一致时，先看这两个字段而不是怀疑代码。

如果页面要展示“线差”，用用户分数减去 score，再结合年份和批次说明语境。线差比裸分稳定，但也不能跨批次直接比较，因为不同批次的竞争群体不同。

一段可直接改用的请求

curl -G "$API_BASE/v1/api/gaokao/score-list" \
  --data-urlencode "key=$API_KEY" \
  --data-urlencode "province=北京" \
  --data-urlencode "subject=综合" \
  --data-urlencode "batch=本科批" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=20"

几个容易忽略的边界

其一，省份写法要和数据集一致，“北京市”和“北京”可能只认一种，接入前先用省份候选值核对一遍。

其二，page_size 传 50 不会报错，但实际仍按 20 返回，前端如果按请求值算页码会错位。

其三，rank、plan_num、admitted_num 存在 null，排序和求和前先过滤，否则会出现 null 排在最前、统计偏小的情况。

其四，同一院校同批次可能有多条专业组记录，去重应按 school_code 与 major_group_code 组合判断，只看校名会误删。

其五，subject 不要用“理科”“文科”去猜新高考省份的取值，拿不准时先不传，让用户根据返回数据里的实际取值再选择。

列表页看似简单，真正决定体验的是筛选口径和空值处理。先把省份、科类、批次三层条件定清楚，再谈分页和缓存，返工概率会小很多。

以上参数与返回字段以数据鱼API「全国高考数据查询」接口的公开文档为准，版本更新后请以最新说明为准。