# Blockscout v12 少读历史：核对分页参数、状态游标与 RPC 错误

整理：链小知（AI 辅助）
资料核对日期：2026-10-12
引用地址：https://lianxiaozhi.com/tools/guides/blockscout-v12-pagination-and-error-check
难度：进阶
核验方式：官方文档整理，未执行真实账户操作

从既有读取记录区分漏页、版本差异、索引未完成和请求失败，不把一页清单当完整历史。

## 使用工具
- [Blockscout](https://lianxiaozhi.com/tools/blockscout) · [官方入口](https://www.blockscout.com/)

## 前置条件
- 准备同链、同端点、同筛选和排序条件的已有连续页记录，以及能确认实例版本的记录；不提供真实 key。
- 没有当前返回或版本证据时只列迁移待核项，不用官方示例或本地演示证明完整历史。

## 1. 确认版本并拆分不变条件与游标

官方 v12 变更优先于仍含旧 items_count 游标示例的通用最佳实践页，但公告的逐步部署不证明某实例已升级。把链、端点、地址/资产范围、筛选、sort/order 和页大小记录为固定条件，下一页位置单独存储。不同网络、过滤或排序的清单不能直接接续，更不能据一页返回估算总历史。

核对结果：版本状态与分页固定条件明确，旧示例没有覆盖新版本说明。
依据：[Blockscout：v12 分页和 RPC 变更](https://docs.blockscout.com/blockscout-v12-0-0-api-updates-and-breaking-changes)
依据：[Blockscout：通用分页示例与 credits](https://docs.blockscout.com/best-practices)
依据：[Blockscout：认证、路由、响应头与 credits](https://docs.blockscout.com/devs/pro-api-responses-and-routes)

## 2. 按新含义保留每一页的请求参数

v12 的 items_count 改为请求页大小，默认页长仍 50，上限配置 MAX_ITEMS_PER_PAGE 默认 100；超过上限会截到最大值，低于 1 会被拒绝。next_page_params 不再回显 items_count、key 以及部分 sort/order/state_filter。每次续页保留原排序、适用筛选和自定页大小，认证由原配置提供；不从游标寻找 key，也不从缺失的 items_count 读取累计进度。

核对结果：下一页保留原条件，实际页长用于计数，密钥未进入游标存档。
依据：[Blockscout：v12 分页和 RPC 变更](https://docs.blockscout.com/blockscout-v12-0-0-api-updates-and-breaking-changes)

## 3. 单独迁移 state-changes 和 limit

交易 state-changes 的新游标为 state_changes_count；旧 state_changes 加 items_count 可能返回 422。全局 internal-transactions 与 token-transfers 的 limit 在 v12 返回 422，tokens 的 limit 则被接受但忽略，使用当前文档要求的 items_count。按端点逐项核对，不把这几条规则套到所有钱包或 API；旧游标失效需重新取得该查询的新位置。

核对结果：游标与页大小按端点匹配，422 与被忽略参数没有被误当无历史。
依据：[Blockscout：v12 分页和 RPC 变更](https://docs.blockscout.com/blockscout-v12-0-0-api-updates-and-breaking-changes)

## 4. 检查字段缺失和索引状态

NFT instances 列表移除嵌套 token，对应 token 可从请求 URL 识别；单个 instance 仍有 token。链专属计数字段在其他链可能被省略，不能补成零；过滤垃圾代币会改变所见范围。internal-transactions 新 meta.status=2 表示仍有部分内部交易待处理，应保留不完整状态，而非宣布一切已索引。重复游标、重复记录或中途读取错误也须保留为缺口。

核对结果：不存在字段、过滤范围与未完成索引分别记录，没有缺失补零或完整性误报。
依据：[Blockscout：v12 分页和 RPC 变更](https://docs.blockscout.com/blockscout-v12-0-0-api-updates-and-breaking-changes)
依据：[Blockscout：通用分页示例与 credits](https://docs.blockscout.com/best-practices)

## 5. 区分 RPC 参数、方法与服务错误

ETH RPC 的 error 从旧字符串变为包含 code/message 的对象，批量应逐项核对 ID 和可选 data。区块 100 要写数量 0x64，字符串 100 在 v12 不再被默认为十六进制。-32602 是参数问题，-32601 可能是实例禁用代理方法，不直接证明 Ethereum 不支持它。交易 summary 的 503 可由读取锁超时产生；对可重试读取做有限退避，仍不把它写成链上执行失败。

核对结果：每项请求、错误层与原响应对应，服务异常未变成交易执行结论。
依据：[Blockscout：v12 分页和 RPC 变更](https://docs.blockscout.com/blockscout-v12-0-0-api-updates-and-breaking-changes)
依据：[Blockscout：代理错误与上游响应](https://docs.blockscout.com/devs/error-responses)

## 6. 输出有限范围的历史清单

汇总实际连续读取的页、去重记录、时间/区块范围、查询条件、索引状态和中断位置；若下一页位置仍存在或读取失败，保留待续状态。旧 legacy GET 日志入口已列移除，替代为专用 POST 与 JSON-RPC body/envelope；POST 形式不单独决定是否读链或写链。本教程只核对既有只读记录，不调用新接口、广播交易或触发合约验证。

核对结果：可复查已读范围及未完成部分，没有把迁移说明或局部清单当完整验收。
依据：[Blockscout：v12 分页和 RPC 变更](https://docs.blockscout.com/blockscout-v12-0-0-api-updates-and-breaking-changes)
依据：[Blockscout：认证、路由、响应头与 credits](https://docs.blockscout.com/devs/pro-api-responses-and-routes)

## 常见错误
- 旧 items_count 游标计数和新页大小不同。
- 只拼 next_page_params 可能丢掉排序和页大小，导致错位。
- HTTP/代理错误、索引状态和链上执行状态需分别判断。

## 完成检查
- 形成带条件与页位置的历史覆盖记录，注明版本未知、旧游标、字段缺失和未读范围。
- 本教程只核验官方文档，未实测当前实例分页、认证接口或交易状态。

## 相关知识
- [区块确认与最终性是什么？交易成功和充值到账为何不同步](https://lianxiaozhi.com/learn/confirmations-and-finality)

## 官方依据
- [Blockscout：现行 API 与实例弃用说明](https://docs.blockscout.com/devs/apis)
- [Blockscout：PRO API 与套餐单位](https://docs.blockscout.com/devs/pro-api)
- [Blockscout：认证、路由、响应头与 credits](https://docs.blockscout.com/devs/pro-api-responses-and-routes)
- [Blockscout：代理错误与上游响应](https://docs.blockscout.com/devs/error-responses)
- [Blockscout：v12 分页和 RPC 变更](https://docs.blockscout.com/blockscout-v12-0-0-api-updates-and-breaking-changes)
- [Blockscout：通用分页示例与 credits](https://docs.blockscout.com/best-practices)