简介面向 Java 工程师与区块链初学者的以太坊数据解析工程演示通过 web3j 直连自建或免费以太坊节点抓取区块数据并解析后写入 MySQL适合需要对接链上数据、构建数据看板或学习以太坊交互的开发者。资源共 39 个文件核心组成包括 18 个 jarweb3j、OkHttp、Druid、MySQL 驱动等第三方依赖、6 个 java 源码、6 个 class 编译产物以及 properties 等配置文件便于直接参考或二次开发。压缩包体积约 9.64MB目录结构清晰涵盖从节点连接到数据落库的完整链路配置与依赖均打包在内。目前已有 2084 人学习下载工程给出了可运行的参考实现读者可通过修改节点地址快速切换数据源同时理解 Web3j 调用、区块遍历与 MySQL 持久化的具体写法为后续扩展比特币等区块链数据解析提供基础。1. 直连以太坊节点前先搞清楚 web3j 到底替你做了什么要做链上数据索引、区块监听或者迁移历史数据第一反应往往是去调第三方区块浏览器 API然后被限速和字段裁剪折磨。其实你手头已经有一台同步好的以太坊节点时用 Java 生态里最成熟的 web3j 直连节点解析区块数据是完全能落地的一条路。web3j 把 JSON-RPC 封装成了明确定义的 Java 类型你拿到的是Block、Transaction、TransactionReceipt这种对象而不是一坨需要自己解析的嵌套 JSON。它解决的问题通俗说就是三件事帮 Java 应用跟节点建立通信、把以太坊世界状态映射成 Java 类、把合约事件解码成可读字段。这篇文章适合想绕过第三方 API、自己控制完整原始数据的后端工程师跟着做能搭起一个最小可用的直连解析链条。2. 从零搭一个直连环境节点选择、Java 依赖与连接配置2.1 节点同步模式与 RPC 端口快照同步才是解析基础直连解析之前先保证你连的那个节点数据是完整的。常见做法是跑一个 Geth 或 Erigon 节点同步模式选快照同步snap sync不要用归档模式跑全量历史状态——区块解析只需要区块头和交易数据不需要每一笔历史余额快照同步能省大量磁盘和几个小时的同步时间。启动 Geth 时我一般会加这些参数geth --http --http.addr 127.0.0.1 --http.port 8545 \ --http.api eth,net,web3 \ --syncmode snap --cache 8192--http.api必须显式列出eth否则解析区块时你会收到method not found。--syncmode snap是当前主流客户端默认行为对解析不产生额外影响。--http.addr绑定本机避免把 RPC 暴露到局域网。需要注意的是这里解析的是导入节点的区块数据不是内存中的 pending 交易。如果你需要解析账本状态还要额外打开debug或txpoolAPI但区块数据解析用不到。2.2 引入 web3j 并初始化连接HTTP、WebSocket 与 IPC 三选一Maven 项目里引入 web3j 的标准做法dependency groupIdorg.web3j/groupId artifactIdcore/artifactId version4.12.3/version /dependency在 Java 里初始化连接有三种方式按场景选// HTTP最常见适合定时扫描和同步解析 Web3j web3j Web3j.build(new HttpService(http://127.0.0.1:8545)); // WebSocket适合实时订阅避免 HTTP 轮询 WebSocketService wsService new WebSocketService(ws://127.0.0.1:8546, false); wsService.connect(); Web3j web3jWs Web3j.build(wsService); // IPC本机节点专用性能最好但要求 Java 进程和节点在同一台宿主机 Web3j web3jIpc Web3j.build(new UnixIpcService(/home/user/.ethereum/geth.ipc));HttpService每次请求都走 HTTP适合 block 同步扫描简单可靠。WebSocketService第二个参数表示是否自动重连我一般传false自己控制重连逻辑。UnixIpcService绕过了 TCP 协议栈但 Windows 下没有现成实现服务端必须开--ipcpath。直连解析的一个细节是无论哪种连接web3j的请求都会在底层自动做 JSON 序列化。如果节点返回数据量很大比如你拉一笔超过 300 万的交易日志注意设置 HTTP 超时否则默认 60 秒不够用。2.3 用最小 Java 代码验证连接读取最新区块号与区块初始化完成后先跑通最小验证再谈解析// 读取最新区块号 BigInteger latestBlockNumber web3j.ethBlockNumber().send().getBlockNumber(); System.out.println(latest block: latestBlockNumber.longValue()); // 按区块号读取整个区块返回完整区块对象 EthBlock blockResponse web3j.ethGetBlockByNumber( new DefaultBlockParameterNumber(latestBlockNumber.longValue()), true) .send(); Block block blockResponse.getBlock(); System.out.println(block hash: block.getHash()); System.out.println(tx count: block.getTransactions().size());getBlockByNumber第二个参数true表示同时返回完整交易对象false只返回交易哈希列表。解析交易时这里必须传true。区块号用DefaultBlockParameterNumber包装记得传long类型。到这里你已经拿到了第一个可用的Block对象下一步就是解析内部字段。验证失败时先看异常信息如果是EmptyResponse多半是节点同步还没到最高高度如果是连接超时检查节点是否把--http.port绑定到127.0.0.1而不是公网接口。3. 区块数据解析Block、Transaction、Receipt 三个对象的字段与解码3.1 区块头里藏着哪些低频字段baseFee、blobGasUsed、withdrawals很多人只取区块号、哈希和交易列表但区块头里几个低频字段对解析精度很重要。EIP-1559 之后baseFeePerGas几乎是每次解析都要用到的字段它决定了该区块内交易的最低 gas 价格。web3j 的Block对象里有getBaseFeePerGas()但要注意返回为null的情况——在 pre-London 区块上这个字段不存在不能直接调数值方法。另一个容易被忽略的是withdrawals字段这是上海升级后引入的。它记录了验证者质押提款它不属于交易但属于区块数据。如果你做的是全量账户余额追踪漏掉withdrawals会导致提款地址的余额少算。看一下怎么提取这些字段// 判断区块是否为 PoS 后的常规区块 if (block.getBaseFeePerGas() ! null) { System.out.println(baseFee: block.getBaseFeePerGas()); } // 解析提款列表如果有的话 ListWithdrawal withdrawals block.getWithdrawals(); if (withdrawals ! null) { for (Withdrawal w : withdrawals) { System.out.println(withdrawal index: w.getIndex() , validatorIndex: w.getValidatorIndex() , address: w.getAddress() , amountWei: w.getAmount()); } }withdrawals里amount单位是 Gwei不是 Wei。换算到 ETH 要除以 10^9。早期区块baseFeePerGas和withdrawals都是 null解析时需要做空值保护否则直接 NPE。3.2 交易解析type、链上签名与 rawTransaction 的关系交易是区块数据里最有价值的部分。web3j 把交易对象映射成Transaction类字段覆盖from、to、value、gas、gasPrice、input。但要注意几个坑from和to如果没过 EIP-55 校验web3j 返回的是小写十六进制。链上原始格式不区分大小写但做哈希或关联地址时需要统一大小写再比较。input字段是十六进制字符串合约创建交易的to为null。transaction.getRaw()可以拿到原始 RLP 编码交易哈希本质上是对这条 raw 数据的 Keccak-256 哈希。解析交易并解码 input 的常见姿势Transaction tx block.getTransactions().get(0); String from tx.getFrom(); String to tx.getTo() null ? : tx.getTo(); BigInteger value tx.getValue(); BigInteger gas tx.getGas(); byte[] inputBytes Numeric.hexStringToByteArray(tx.getInput()); // 如果 input 前四个字节是函数签名可以反查对应的方法名 String methodHex tx.getInput().substring(0, 8); System.out.println(tx hash: tx.getHash()); System.out.println(from: from); System.out.println(to: to); System.out.println(value(wei): value);Numeric.hexStringToByteArray是 web3j 提供的工具类处理带0x或不带0x的字符串。methodHex是函数选择器比如0xa9059cbb对应 ERC-20 的transfer(address,uint256)。要完整解码参数需要方法签名列表或合约 ABIweb3j 对此提供Function解析器但需要你提供 ABI JSON。对于合约内部调用的交易input里是调用数据不是交易本身的数据。这里不展开合约调用追踪解析区块层面只关心 input 原始数据。3.3 交易收据与合约日志理解 Topics 的布尔逻辑区块数据解析到交易这层还够如果要分析合约事件就必须拿到TransactionReceipt。Receipt 里有logs每个日志包含address、topics、data。topics 数组的第一个元素是事件签名哈希第二个及以后是索引参数的编码值。比如 ERC-20Transfer事件的 topics 结构是eventSignatureHash, from, to。解析日志时最容易翻车的是 topics 是动态数组不同事件长度不同。web3j 提供了Log对象编码和解码逻辑要自己按事件结构做。看这个解码示例TransactionReceipt receipt web3j .ethGetTransactionReceipt(tx.getHash()) .send() .getTransactionReceipt() .get(); for (Log log : receipt.getLogs()) { // 事件签名哈希在第一个 topic String eventSig log.getTopics().get(0); String from log.getTopics().get(1); String to log.getTopics().get(2); // data 里是 non-indexed 参数这里以 Transfer 为例 BigInteger amount new BigInteger(log.getData().substring(2), 16); if (0xddf252ad....equals(eventSig)) { System.out.println(transfer from from to to amount amount); } }getTopics()返回的字符串都带0x前缀做equals比较时必须带。data 字段如果是0x开头的十六进制通过substring(2)去掉前缀再转BigInteger。若日志包含多个 non-indexed 参数每个参数按 32 字节对齐需要手动截断没有捷径。区块数据解析到这里已经覆盖了区块头、交易、收据、日志四层。接下来要聊的是让这些解析在真实生产环境下不翻车的那些硬边界。4. 常见避坑直连节点解析时的 6 个真实翻车现场4.1 节点返回空区块导致 NPE现象解析到某个区块高度时block.getTransactions()为null直接调用getTransactions().size()就 NPE。原因web3j 对某些空区块的transactions字段反序列化成null而不是空列表尤其是使用 Geth 的eth_getBlockByNumber在参数fullTxfalse时。解决解析前统一做防御性包装ListTransaction txList block.getTransactions(); int txCount txList null ? 0 : txList.size();养成对 web3j 返回集合类型的空判断习惯比任何全局配置都有用。4.2 区块号用错数据类型导致读到负数高度现象ethGetBlockByNumber传入一个Integer而不是BigInteger在区块号超过 2^31 后会报错或返回null。原因web3j 的DefaultBlockParameterNumber有两个构造重载源码接受的long但如果你用了Number类型极端情况下会溢出。解决统一用BigInteger.valueOf(blockNumber)或DefaultBlockParameterNumber.valueOf(long)构造参数。我在项目里禁止直接传 int。4.3 baseFeePerGas 和 withdrawals 字段为 null现象对旧区块调用getBaseFeePerGas()返回null直接做数值计算把 null 传给 BigDecimal引发 NPE。原因这些字段是协议升级后才引入的旧区块上节点根本不会返回该字段。解决写一个辅助方法提取区块费用参数默认返回BigInteger.ZERO同理 withdrawals 空列表。把所有可以为null的字段都集中到一个BlockData包装类里。4.4 十六进制转 BigInteger 出现负数现象new BigInteger(logDataString, 16)得到一个大整数但转longValue()后变成负数看起来像数据错误。原因Solidity 里uint256超过Long.MAX_VALUE时web3j 的BigInteger本身没问题问题是你调用了longValue()做截断。解决别用基本类型接收金额全程保持BigInteger传递。需要展示时再转BigDecimal且按10^18进行除法保留必要精度。4.5 节点头部追赶中解析到不完整数据现象同步中的节点看到最新区块号是 100但解析这个区块时交易只有一半。原因节点还在 snap 同步中RPC 返回的区块数据是按sync到的高度提供的但有些客户端在“临时 header”阶段返回部分交易。解决启动时先调用ethSyncing接口判断节点是否同步完成EthSyncing syncing web3j.ethSyncing().send(); boolean done syncing.isSyncing() false;只有isSyncing()返回false才允许解析消费者启动否则排队等待。4.6 日志解析时 topics 长度不符合预期现象解析 ERC-721Transfer事件发现第二个 topic 不是from而是tokenId。原因ERC-721 的Transfer事件定义和 ERC-20 签名哈希相同但参数顺序不同。如果你用 ERC-20 的解码逻辑去解任何一个0xddf252ad开头的事件就会把tokenId当成to。解决除了校验 topic0 之外还要校验transactionReceipt.getLogs()对应的合约地址和日志的长度。更稳妥的做法是把事件 ABI 解析逻辑独立不要写死。5. 把解析结果落到自己的数据系统全量扫描与增量监听5.1 全量扫描分页拉取区块并断点续传解析生产环境动不动要跑百万个区块不能一个 for 循环从头拉到尾。常见的做法是拉一个区块解析完立刻持久化记录当前扫描到的区块号下次启动从lastProcessedBlock 1继续。简单版实现long startBlock loadFromDatabase(); long endBlock web3j.ethBlockNumber().send().getBlockNumber().longValue(); for (long i startBlock; i endBlock; i) { EthBlock response web3j .ethGetBlockByNumber(new DefaultBlockParameterNumber(i), true) .send(); Block block response.getBlock(); if (block null) { // 区块缺失记录下来等待处理 continue; } saveBlock(block); saveTransactions(block.getTransactions()); saveBlockProgress(i); }saveBlockProgress每次写完业务数据后调用放在同一事务里避免数据写到一半进程崩溃重启后从旧断点重跑导致重复。这里只做序号递增不做并发因为节点 RPC 的并发能力有限而且按顺序解析更利于快速定位问题。更好的做法是每个区块解析原子化但 Java 事务边界需要设计这里不展开。5.2 实时监听WebSocket 订阅区块头与日志全量扫描适合事后回溯但监听新区块必须用 WebSocket。web3j 提供了blockFlowable和logFlowable两个流式接口。logFlowable可以按地址过滤但要注意过滤器参数是以太坊地址标准格式。Disposable sub web3j.blockFlowable(false).subscribe(block - { // 这里的 block 只包含区块头 processBlockHeader(block); }); // 订阅指定合约的日志 Disposable logSub web3j.logFlowable( new EthFilter( DefaultBlockParameterName.LATEST, DefaultBlockParameterName.LATEST, Arrays.asList(contractAddress) ) ).subscribe(log - { processLog(log); });blockFlowable返回的是区块头对象不是完整区块。看完整交易还得ethGetBlockByHash成本较高。logFlowable的过滤地址列表不能为空列表否则返回所有日志压力很大。订阅是异步的记得在应用关闭时调用disposable.dispose()否则连接泄漏。5.3 数据完整性与幂等用 blockHash 做去重只要是全量扫描加重新启动就会遇到重复解析。简单做法是用blockHash作为唯一键入库然后再保存交易。数据库里给区块哈希建唯一索引重复写入直接忽略try { saveBlock(block); } catch (DuplicateKeyException e) { // 已处理过跳过 }更完整的做法是记录blockHash到processed_blocks表扫描时先判断当前区块号对应的哈希是否和已经处理的一致如果不一致说明发生了区块重组reorg需要回滚到重组织前的位置。节点直连时尤其要重视这个因为你的节点可能连接的是同步到分叉末尾的节点。真实生产中我采用“扫描表 断点续传 分叉检测”三步走扫描表存block_number作为主键block_hash作为普通索引。每次解析前查询最后一个已处理的区块号然后向后扫描。每次解析新区块时比较当前区块的parentHash是否等于已处理区块的hash。如果不相等说明发生分叉将数据库回滚到公共祖先再从新区块高度重新拉取。这套策略能兜住 95% 的回滚场景剩下的极端情况靠人工检查。6. 区块解析正确性的土办法不依赖区块浏览器的三方校验写完解析程序怎么验证结果是可信的你不能全信节点返回的字段得用几条反直觉的规则自检。第一区块哈希自校验。block.getHash()在逻辑上应该等于对区块头 RLP 编码做 Keccak-256。web3j 提供了BlockHeader相关的编码工具但实际项目中我很少自己编码因为节点返回的头字段足够完整。偷懒但可靠的做法是拿到相邻三个区块检查block.getNumber()的连续性和nextBlock.getParentHash()是否等于block.getHash()。如果不等说明中间的区块发生了重组织你解析的这条链已经不是主链。第二交易根校验。每个区块的getTransactionsRoot()是区块内全部交易的三重默克尔根。你可以将所有tx.getHash()按顺序计算默克尔根再与区块头中的txRoot比较。这是最硬的校验但实现比较复杂做一个简化版至少确认交易列表条数正确且每笔交易哈希的格式符合 64 位十六进制。第三用收据根校验。每笔交易收据的transactionHash必须等于交易哈希。直接把交易哈希和收据哈希做交集匹配如果有一笔对不上说明节点返回的收据属于别的分叉。第四保留原始 JSON。解析时把EthBlock底层的原始 JSON 字符串保存到文件或数据库出问题时可以回看节点到底返回了什么。web3j 的响应对象里没有直接暴露原始报文但我一般会在HttpService层做一次拦截把请求和响应的原始字符串写入日志。这个动作成本很低但排错价值极高。我个人的习惯是每解析完 1 万个区块做一次抽样校验抽查 10 个区块的 txRoot 和 receiptRoot。如果抽查全过才继续后面的扫描。不要把全部信任放在“节点是官方客户端所以返回正确”上节点配置错误、磁盘损坏、内存回写异常都会让链上数据在解析层变得不可信。直连节点的解析和第三方 API 最大的差别是你能拿到原始报文和完整字段但代价是你得自己处理同步、分叉和类型转换。我用这套方案已经跑过几条内部链数据的全量迁移最深的感触是别急着写解析逻辑先把节点同步状态和断点续传做好这部分比重写解析代码更难也更容易被忽视。希望帮到你。本文还有配套的精品资源点击获取