Blockscout v12 少读历史：核对分页参数、状态游标与 RPC 错误
链小知 · 进阶 · 核验 · 依官方文档整理
从既有读取记录区分漏页、版本差异、索引未完成和请求失败，不把一页清单当完整历史。
开始前准备
- 准备同链、同端点、同筛选和排序条件的已有连续页记录，以及能确认实例版本的记录；不提供真实 key。
- 没有当前返回或版本证据时只列迁移待核项，不用官方示例或本地演示证明完整历史。
1. 确认版本并拆分不变条件与游标
官方 v12 变更优先于仍含旧 items_count 游标示例的通用最佳实践页，但公告的逐步部署不证明某实例已升级。把链、端点、地址/资产范围、筛选、sort/order 和页大小记录为固定条件，下一页位置单独存储。不同网络、过滤或排序的清单不能直接接续，更不能据一页返回估算总历史。
检查结果：版本状态与分页固定条件明确，旧示例没有覆盖新版本说明。
2. 按新含义保留每一页的请求参数
v12 的 items_count 改为请求页大小，默认页长仍 50，上限配置 MAX_ITEMS_PER_PAGE 默认 100；超过上限会截到最大值，低于 1 会被拒绝。next_page_params 不再回显 items_count、key 以及部分 sort/order/state_filter。每次续页保留原排序、适用筛选和自定页大小，认证由原配置提供；不从游标寻找 key，也不从缺失的 items_count 读取累计进度。
检查结果：下一页保留原条件，实际页长用于计数，密钥未进入游标存档。
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 与被忽略参数没有被误当无历史。
4. 检查字段缺失和索引状态
NFT instances 列表移除嵌套 token，对应 token 可从请求 URL 识别；单个 instance 仍有 token。链专属计数字段在其他链可能被省略，不能补成零；过滤垃圾代币会改变所见范围。internal-transactions 新 meta.status=2 表示仍有部分内部交易待处理，应保留不完整状态，而非宣布一切已索引。重复游标、重复记录或中途读取错误也须保留为缺口。
检查结果：不存在字段、过滤范围与未完成索引分别记录，没有缺失补零或完整性误报。
5. 区分 RPC 参数、方法与服务错误
ETH RPC 的 error 从旧字符串变为包含 code/message 的对象，批量应逐项核对 ID 和可选 data。区块 100 要写数量 0x64，字符串 100 在 v12 不再被默认为十六进制。-32602 是参数问题，-32601 可能是实例禁用代理方法，不直接证明 Ethereum 不支持它。交易 summary 的 503 可由读取锁超时产生；对可重试读取做有限退避，仍不把它写成链上执行失败。
检查结果：每项请求、错误层与原响应对应，服务异常未变成交易执行结论。
6. 输出有限范围的历史清单
汇总实际连续读取的页、去重记录、时间/区块范围、查询条件、索引状态和中断位置；若下一页位置仍存在或读取失败，保留待续状态。旧 legacy GET 日志入口已列移除，替代为专用 POST 与 JSON-RPC body/envelope；POST 形式不单独决定是否读链或写链。本教程只核对既有只读记录，不调用新接口、广播交易或触发合约验证。
检查结果：可复查已读范围及未完成部分，没有把迁移说明或局部清单当完整验收。
怎样确认完成
- 形成带条件与页位置的历史覆盖记录，注明版本未知、旧游标、字段缺失和未读范围。
- 本教程只核验官方文档，未实测当前实例分页、认证接口或交易状态。
常见错误与边界
- 旧 items_count 游标计数和新页大小不同。
- 只拼 next_page_params 可能丢掉排序和页大小，导致错位。
- HTTP/代理错误、索引状态和链上执行状态需分别判断。