REST 批量查询的数字闸门：一次最多要两千个标头

比特币节点开着 -rest 之后，不用配 RPC 认证，用 curl 就能查链上数据：/rest/headers/<数量>/<区块哈希>.json 一口气取一段区块标头，/rest/blockfilterheaders/... 取一段过滤器标头。这些”给我 N 个”的批量接口有个共同上限：一次最多 2000 个。这个数字来自源码常量 MAX_REST_HEADERS_RESULTS。本文全部以 Bitcoin Core v31.0 源码为准。

一条常量管着多个批量端点

在 src/rest.cpp 里，MAX_REST_HEADERS_RESULTS 定义为 2000。它不是某个端点的个性设置，而是被批量标头类查询共用：区块标头列表、过滤器标头列表等端点解析 count 参数后，都拿同一个区间做校验——小于 1 或大于 2000 直接返回 400 错误，错误文本写明”Header count is invalid or out of acceptable range (1-2000)“。顺带一提，这个文件里还能读到各端点 count 的默认值写法：不传数量时，过滤器标头这类端点默认给 5 个。

为什么要设这个闸

REST 是免认证的：任何能连到这个端口的人都能发查询，不走 cookie 也不走 rpcauth。每个标头 80 字节，2000 个就是 160KB 量级的响应；没有上限的话，一个恶意或写错的客户端一句”给我一千万个标头”，就能让节点在单机上白白组织几兆的响应、消耗磁盘读和带宽。设闸门本质是”免认证入口的防打满措施”——和 RPC 有线程数、工作队列这些约束是同一层考虑，只是 REST 用最简单粗暴的方式：数字超限，直接拒绝，不去部分满足。

想要更多怎么办

翻页，而不是抱怨。以取一段标头为例：先要起始哈希起的 2000 个，用返回列表里最后一个标头的哈希作为下一轮的起点，再要下一批。源码里标头端点是从给定哈希向后连续取的，天然适合这种接力式翻页。写同步脚本时把”每页不超两千、记录续点”当成默认纪律，比调参数更可靠——这个 2000 是编译期常量，节点配置里没有把它调大的开关。

现场排错

最常见的撞线现场：脚本里 count 变量因为解析错误变成 0 或空（返回”低于 1”），或者有人图省事直接写 100000 想让节点”一次给全”（返回”超过 2000”）。两种都吃 400，错误文本里会带上你传入的原始值，排错时先看响应正文，它已经把非法值回显给你了。另外注意 REST 默认只绑本机回环地址，端口上跑的是节点自带的小型 HTTP 服务，不是独立进程——排查时看节点日志即可。

常见误区

一是把这个 2000 当成”REST 最多能查两千个区块的历史”：它只是单次请求的批量尺寸，翻页无限制。二是把标头数量和 getdata、inv 里那些五千、五万的条目上限混用：那些是 P2P 层的消息尺寸纪律，和 REST 分属两套体系，数字巧合不代表同一条规则。三是以为 /rest/block/ 之类单资源端点也受 2000 影响：单块、单 UTXO 查询不在该常量管辖内，它是专门给”带 count 的批量标头类端点”设的闸。

与相邻数字对个账

REST 面上其实不止这一个数，顺手对齐可以避免混用：批量标头类端点（区块标头、过滤器标头）受这个 2000 管；批量 UTXO 查询端点 getutxos 的 ?count= 有自己的一段解析；v31.0 新增的按字节取块端点 /rest/blockpart/ 则带自己的偏移与长度参数。请求分发上还有个先后次序值得知道：数据格式后缀（.json、.bin、.hex）在进端点逻辑之前就由统一函数解析，格式写错先报”不支持的格式”；进了端点之后才轮到数量校验，数量非法时响应文本会把你的原始值回显出来。把这些端点当成一个”带不同参数表的小查询语言”来记，比逐条背错误信息省心得多。

风险提示：本文为节点 REST 接口机制科普，常量与端点行为以 Bitcoin Core 当前版本源码为准，可能随版本调整；不构成查询性能承诺或投资建议。