简介一套基于Java Web3j的以太坊区块数据解析工程面向区块链开发者、数字货币研究者及需要链上数据落地的技术团队。工程支持直连自建节点或免费公共节点完成区块数据的抓取与字段解析并可将结构化结果写入MySQL适用于链上交易监控、地址行为分析等场景。压缩包共39个文件以18个jar依赖库、6个java源码、6个class编译文件及4个properties配置文件为主整体大小9.64MB目录结构清晰便于按模块对照学习。包内还提供Druid数据库连接池、Log4j日志配置以及MySQL连接驱动读者可直接参考工程骨架快速理解Web3j接入以太坊、解析区块数据并持久化存储的完整流程节省自行搭建环境的时间。同时工程对解析字段与存储结构保留调整空间便于后续按业务需求扩展。目前已有2084人学习下载适合希望通过实际代码上手区块链数据解析的开发者。1. 直连以太坊节点java web3j 为什么能干掉 RPC 封装层做过链上数据服务的同学大概率都经历过这个阶段项目一开始图省事直接用 Infura 或 Alchemy 的公共接口拉区块后来发现调用量上来之后账单涨得比币价还快限流、超时、返回不一致轮着来。这时候就会有人告诉你不如自己连一个以太坊节点把数据源攥在手里。方向是对的但真正动手才发现连节点只是开始区块数据怎么拉、怎么解析、怎么应对 reorg 和空块才是大头。这篇文章只讲一条链路用 java 与 web3j 直连以太坊节点把区块数据从 RPC 响应解析成业务能用的对象。适合已经写过后端、但没正经摸过链上数据解析的开发者。2. 直连前的三个选择节点类型、连接方式与 web3j 依赖2.1 节点选型geth、erigon 还是托管 RPC「直连」不代表你必须从零同步一个全节点。如果你的场景是解析历史区块做数据分析和索引全节点是必须的因为它保存了完整的链上历史状态。如果你的场景是监听最新区块和交易一个快照同步的归档节点或者执行节点也够用但注意「够用」和「能解析历史」是两回事。我一般把节点分成三类geth 全节点、erigon 归档节点、第三方托管 RPC。geth 是官方客户端默认配置下同步到最新高度大约需要几百 GB 磁盘胜在稳定、社区资料多适合大多数团队。erigon 在磁盘占用上优化明显同步速度快但它是 Rust 系运维习惯和 geth 不完全一样适合已经对链上数据量有明确预期的团队。第三方托管 RPC 不是直连但可以作为 web3j 开发期的联调后端因为 web3j 对 JSON-RPC 的封装是透明传输你后面把 URL 换成自己的节点地址代码零改动。直连的核心收益是可控没有速率限制、没有 key 过期、没有第三方数据的「清洗」和裁剪。代价是节点运维成本和磁盘成本。如果只是自己写工具、做小批量解析用公共节点做联调完全够如果准备长期跑服务本地节点才是正路。2.2 两个 RPC 端口怎么选HTTP 与 WebSocket以太坊节点默认同时暴露两个 RPC 端口geth 下是 8545HTTP和 8546WebSocket。web3j 同时支持两种连接方式但使用场景完全不同。HTTP 是请求-响应模式适合「主动拉取」我告诉你区块号你给我返回区块头。WebSocket 是长连接推送模式适合「被动监听」节点有新块了主动推给我不用我反复轮询。如果你做的是区块扫描器希望每 15 秒左右拿到新块HTTP 就够了省心且容易排查问题。如果你做的是 DeFi 监控或者 mempool 观察必须用 WebSocket否则轮询的延迟和压力都不可控。直连模式下还有一个细节HTTP 和 WebSocket 的 API 能力不是完全对等的。默认配置下geth 的 HTTP 端口不会暴露eth_subscribe而 WebSocket 端口默认开启。这是 geth 在config.toml里的 HTTPVirtualHosts、WSHosts 等参数控制的。第一次部署节点的人经常遇到「HTTP 能 curl 通、WebSocket 连不上」的问题八成是没开 WS 对应的 API 模块。2.3 maven 依赖与最小客户端装配web3j 的接入非常简单maven 依赖只有两个核心包core和crypto。core里是 JSON-RPC 封装、数据类型和合约交互能力crypto里是和密钥、签名相关的工具。如果只做区块数据解析core就够。dependency groupIdorg.web3j/groupId artifactIdcore/artifactId version4.9.8/version /dependency版本选 4.x 而不是 5.x 是因为 4.x 的 API 稳定网上可查的资料最多踩坑之后能搜到答案。5.x 改动较大对于「解析区块数据」这个需求没有额外收益。依赖装好之后连接节点只需要两行代码Web3j web3j Web3j.build(new HttpService(http://127.0.0.1:8545)); System.out.println(web3j.web3ClientVersion().send().getWeb3ClientVersion());这段代码做了三件事创建 HttpService 指向本地 8545 端口用这个 service 构建 Web3j 实例最后发了一个web3_clientVersion请求验证链路通不通。值得注意的是HttpService可以设置连接超时和读取超时默认是 30 秒但链上节点在同步压力大的时候响应可能很慢建议调到 60 秒以上。如果走 WebSocket 连接替换成WebSocketService即可但要注意 WebSocket 连接是异步的send()返回的CompletableFuture需要单独处理WebSocketService wss new WebSocketService(ws://127.0.0.1:8546, false); wss.connect(); Web3j web3j Web3j.build(wss);参数说明false表示不需要 WebSocket 握手后自动发送eth_subscribe请求这个开关留给后面要谈的事件监听初学阶段保持false更安全避免节点悄悄建立了一堆你没用到的订阅。3. 建连与区块数据同步用 web3j 拉取并解析区块头3.1 最小可跑代码连接并打印最新区块连接成功后的第一步永远是先取最新区块高度确认节点同步状态再看区块内容。这块代码是后面所有解析工作的地基。try { BlockNumber latestBlock web3j.ethBlockNumber().send(); BigInteger blockNum latestBlock.getBlockNumber(); System.out.println(当前最新区块高度: blockNum); EthBlock ethBlock web3j.ethGetBlockByNumber(blockNum, true).send(); Block block ethBlock.getBlock(); System.out.println(区块哈希: block.getHash()); System.out.println(交易数量: block.getTransactions().size()); } catch (Exception e) { e.printStackTrace(); }逻辑说明ethBlockNumber().send()是同步阻塞调用返回一个BlockNumber对象里面只有一个高度值。ethGetBlockByNumber(blockNum, true)的第二个参数true代表返回完整交易对象如果传false则返回的区块对象里交易位置只给哈希列表交易详情为零。新手最容易在这个参数上犯迷糊以为拿不到交易是节点问题其实是没传true。打印出区块哈希和交易数量之后先别急着写解析逻辑。先确认一件事你拿到的高度和节点日志里的高度一致吗。本地节点同步中RPC 返回的「最新区块」不是链的头部而是节点的本地头。如果节点一直没同步完这个高度会比真正的最新高度低很多。3.2 区块头字段解析number、timestamp、gasLimit 的实际含义拿到Block对象后里面的字段比你想的多。number是区块高度timestamp是出块时间hash是当前块哈希parentHash是父块哈希gasLimit是这一块的燃料上限gasUsed是实际消耗量。真正做解析时hash、parentHash、timestamp、number这四个字段是业务上最常用的。long blockTime block.getTimestamp().longValue(); String parentHash block.getParentHash(); BigInteger gasUsed block.getGasUsed(); log.info(块高: {} | 时间: {} | 父哈希: {} | gasUsed: {}, blockNum, blockTime, parentHash, gasUsed);这里有个解析上的细节web3j返回的数值字段几乎全是BigInteger不是因为代码风格而是 JSON-RPC 协议规定所有数值必须以十六进制字符串返回而BigInteger正好能无损承载这类大数。直接转Integer或者Long在数值小于 2^31 时没问题一旦遇到gasLimit、交易金额这类大数就会溢出这是解析区块头最常见的翻车点。关于timestamp它是以太坊出块时间的 Unix 秒数不是毫秒。后端开发习惯用Instant.ofEpochSecond(blockTime)转成LocalDateTime直接用*1000转毫秒虽然也能拿到时间戳但语义上不对以后做时间范围查询时容易踩坑。区块头的解析没有太多幺蛾子真正的复杂度在交易解析上。但区块头里有一个字段容易被忽略——baseFeePerGas。如果你连的是 EIP-1559 升级后的网每笔交易的 gas 费用计算要参考这个字段。web3j 的Block对象里没有直接暴露baseFeePerGas要么自己去block.getRaw()里拿原始 JSON要么升级到带 EIP-1559 支持的版本。这块内容后面讲 gas 计算时再展开。3.3 同步策略从指定区块号拉取并处理分叉同步不是说「拿到最新块就完事」。链上有重组织reorg现象临时分叉上的块可能会被主链丢弃导致你之前解析的数据是分叉数据。常见策略是延迟 N 个区块确认也就是不处理最新块而是处理最新高度减 12 或减 20 的块。BigInteger targetBlockNum latestBlockNum.subtract(BigInteger.valueOf(12L)); EthBlock ethBlock web3j.ethGetBlockByNumber(targetBlockNum, true).send();12 个确认块是多数 DeFi 项目的默认值需要 3 分钟左右。如果做的是只读解析不需要用户即时确认交易可以把确认数设成 6兼顾时效和确定性。不要设成 0否则你会不停地把临时分叉上的数据写进数据库后面还要写回滚逻辑这种「返工」纯属给自己加戏。还有一个细节是同步的并发度。区块解析是 IO 密集和 CPU 密集混合的任务IO 是因为要反复请求 RPCCPU 是因为要解析交易 input 数据和解码日志。用单线程拉取肯定浪费节点能力但并发太高又容易让节点 RPC 队列积压。我一般用 10 到 20 个线程共享同一个Web3j实例每个线程负责不同的区块区间。Web3j是线程安全的但请记住连接池的底层连接数是有限的如果并发请求超过节点的 HTTP 连接上限节点会报connection reset这不是你的代码问题是连接池参数没跟上。4. 交易与收据解析把十六进制交易输入还原成人话4.1 交易对象的结构from/to/value/input 分别怎么读从Block.getTransactions()返回的TransactionResult里拿到Transaction对象后第一个感受是字段名和 etherscan 上看到的几乎一样但有几个关键字段需要特殊处理。from是交易发送方to是接收方value是转移的 ETH 数量以 wei 为单位input是交易携带的数据。gas和gasPrice是燃料参数hash是交易哈希。这里最容易犯错的认知是input不是转账备注而是调用智能合约方法的编码参数。Transaction tx (Transaction) transactionResult.get(); String from tx.getFrom(); String to tx.getTo(); BigInteger valueWei tx.getValue(); String inputData tx.getInput();从地址到可读状态的转换需要理解「地址是哈希的一部分」。从地址字符串本身看不出任何业务含义只有结合合约地址和input里的函数签名才能恢复调用意图。所以解析交易的第一步不是解码,而是判断这笔交易是普通转账、合约创建还是合约调用。转账交易的to是非空地址input为空或者只有 0x。合约创建交易的to为空input是完整的合约字节码。合约调用交易的to是合约地址input是函数签名加参数编码。判断逻辑就三行if (to null || to.isEmpty()) { return contract creation; } else if (inputData null || 0x.equals(inputData)) { return transfer; } else { return contract call; }4.2 解析交易 input 数据方法签名哈希与参数解码交易 input 的前 4 字节是方法签名哈希后面是参数编码。所谓签名哈希就是把函数签名transfer(address,uint256)做 Keccak-256 哈希取前 4 字节。web3j 内置了从 ABI 编码解码交易 input 的完整工具但需要你提供函数定义。Function function new Function( transfer, Arrays.asList(new Address(0x...), new Uint256(BigInteger.TEN)), Collections.emptyList() ); String encoded FunctionEncoder.encode(function);这段代码是编码方向FunctionEncoder.encode把一个函数名、参数列表转成十六进制字符串。反过来是FunctionReturnDecoder但由于交易 input 只有输入参数没有返回值直接解码交易 input 的工作量比编码方向简单。解码时只要拿到Function对象也就是函数名和参数类型列表就能把 input 还原成参数数组。实际工程里这么玩效率太低。因为每个合约的函数签名不同准确做法是维护一张「函数签名 - 参数类型列表」的表按 input 的前 4 字节匹配。当你遇到没收录过的合约调用时先用最粗的方式打印原始 input再确认解析结果的正确性。参数解码步骤从 input 里截掉前 4 字节然后按类型长度切分。address是 20 字节补零成 32 字节uint256是 32 字节整型bool是 32 字节布尔值。web3j 的FunctionReturnDecoder.decode能处理静态类型但处理动态类型比如string、bytes、数组时需要先读偏移量。ListTypeReferenceType outputParameters new ArrayList(); outputParameters.add(new TypeReferenceAddress() {}); outputParameters.add(new TypeReferenceUint256() {}); ListType decoded FunctionReturnDecoder.decode( inputData.substring(10), // 去掉 0x 和 4 字节签名 outputParameters );参数说明substring(10)是因为 0x 占 2 字符签名占 8 字符剩下的才是参数编码。TypeReference必须用匿名内部类写法不能用TypeReferenceAddress直接实例化这是 Java 泛型擦除带来的限制写错会直接编译报错。对动态类型的解析要单独开一条路。比如transfer(address,uint256)这种纯静态参数可以直接切块但approve(address,uint256)也是这样。碰到functionName(string,uint256)这类带动态类型的函数切块逻辑会错必须先读前 32 字节得到偏移量再跳到偏移位置读实际内容。4.3 收据日志解析等块确认后怎么拿交易结果交易 input 只能告诉我们「用户调了哪个函数」无法告诉我们「调用结果如何」。ERC-20 Transfer 事件的金额、内部交易的成败、合约抛出的异常都在交易收据transaction receipt里。拿到收据的核心方法是eth_getTransactionReceiptOptionalTransactionReceipt receiptOpt web3j .ethGetTransactionReceipt(tx.getHash()) .send() .getTransactionReceipt(); if (receiptOpt.isPresent()) { TransactionReceipt receipt receiptOpt.get(); log.info(交易状态: {} | gasUsed: {} | logs: {}, receipt.getStatus(), receipt.getGasUsed(), receipt.getLogs().size()); }getStatus()的值是0x1成功或0x0失败注意返回格式因节点配置不同可能是十六进制字符串或十进制字符串web3j 统一封装成了String判断时要先做进制转换。getLogs()返回的日志对象是「事件解析」的原料下一章单独展开。这里要特别提醒收据不是区块打包后立即出现的。交易进入 pending 池、被打包、被确认每个阶段拿收据的结果不同。打包含未确认时收据可能不存在确认后被 reorg收据也可能消失。所以交易收据的获取必须放在「交易已确认」的前提下马虎不得。提示以太坊交易是异步最终性的。web3j 的send()拿到的发送哈希只代表交易被节点接收不代表被链确认。想拿收据请轮询「带确认数检查」的收据接口或者使用 WebSocket 订阅logs事件后再补交接收据。5. 区块数据解析避坑5 个让人翻车的边界问题5.1 最新区块高度不等于链上权威高度这是个最容易被忽视的现象。本地节点同步中eth_blockNumber返回的是「节点自己认为的最新高度」。如果节点同步到一半停在某个高度不上来你的程序会持续从那个错误高度拉数据看起来没报错数据却全是旧的。原因通常有两个节点磁盘满了导致同步卡住或者节点快照同步模式snap sync在服务端不支持时退化成了全量同步越同步越慢。解决办法是在同步开始前确认节点日志里的syncing状态并且定时检查磁盘余量。检查节点同步状态不能用eth_blockNumber要用eth_syncing。web3j 对应的解析类是它会直接告诉你「是否同步中、当前拉到哪了、最高到哪」。同步未完成时有些节点会返回对象而不是布尔值不做判空就解析字段必报错。5.2 空块与叔块「区块高度」连续是错觉有些做区块高度连续性检查的开发者会发现每隔几百个块就「缺一个」实际上链上没有缺块而是出现了空块。空块的transactions列表为空但区块头和哈希是存在的。扫描时如果直接拿「上一个块号 1」去拉下一块没问题但写数据库时如果按交易数量连续性做校验会把空块误判为链异常直接报错中断。另一个更隐蔽的是叔块uncle。以太坊 PoW 阶段允许叔块引入叔块有自己的哈希和高度但不是主链的一部分。eth_getBlockByNumber只返回主链上的块访问叔块要用eth_getUncleByBlockHashAndIndex。web3j 的EthBlock.getUncles()返回的是叔块哈希列表如果把这个列表当普通交易哈希处理会出现「有哈希但查不到交易」的数据异常。5.3 十六进制数值解析时的大数溢出web3j 的Block.getGasLimit()返回BigInteger但如果手贱调用了.intValue()在小数值时没问题一旦遇到大数就返回错误值还不出异常——Java 的BigInteger.intValue()对溢出是静默截断的。最典型的例子是baseFeePerGas这类字段。以太坊主网上的gasLimit是 3000 万左右baseFeePerGas有时候会到几百 Gwei换算到 wei 是 18 个零的级别。任何中间计算都不建议转Long统一用BigInteger做运算最后再按业务需要转Decimal输出。使用new BigDecimal(value, 18)把 wei 转 ETH 是最稳妥的方案。5.4 交易 input 不是所有都遵循 ABI 标准「input 前 4 字节是方法签名」这条规则只对普通合约调用成立。EIP-1014 的 CREATE2 创建合约、EIP-2930 的带 access list 的交易、以及 4337 的 UserOperation 结构它们的 input 都有不同的编码方式。但如果你是解析普通交易最简单的一句话是不要假设所有 input 都能解出参数解析失败时不要中断流程降级成「只存原始 input」就好。常见失败场景合约的 fallback 函数。用户向合约地址转了 ETHto是合约地址但input是空或非标准编码这时解析器报了「函数签名不匹配」的错。处理方式是把 input 为空的情况全部记为「普通转账」不要强行套函数签名解码。5.5 本地节点磁盘占用与快照同步这个不算代码问题但却是「直连」模式最常见的运营翻车点。geth 默认配置下主网全节点同步完通常占用 600 GB 到 1 TB 以上存储视快照、历史状态保留策略。很多团队把节点部署在 500 GB 的云盘上跑到一半磁盘满了同步直接中止。解决方案不是删数据而是从一开始就使用geth --syncmode snap --gcmode archive或者只保留最近 N 个状态的「prune」模式。注意gcmodearchive是保留全部历史状态适合做历史区块解析如果只是做账户余额、最新区块展示用gcmodefull就够了。磁盘告警监控也是必做项节点数据目录达到 85% 就该扩容或者清理。注意block 同步的「reorg 回滚」和「节点磁盘」问题是两个完全不同层面的问题。前者是链自身的数据重组后者是本地存储资源问题。排查问题先分清楚属于哪一类别拿日志反复翻找最后发现是磁盘满了。6. 事件日志解析用 web3j 过滤器做增量监听6.1 从区块扫描到事件监听过滤器与订阅区块扫描的模式是「主动拉取」但很多业务其实更适合「被动接收」。比如监控某个地址的 ERC-20 转入或者监控某个 DEX 的 Swap 事件用轮询每个区块然后过滤交易的方案在区块间隔时间长、目标地址多时效率很低。web3j 的过滤器分为两种EthFilter用于一次性查询历史日志FlowableLog订阅用于持续监听新日志。历史查询适合做「补数据」订阅适合做「实时监控」。EthFilter filter new EthFilter( DefaultBlockParameterName.EARLIEST, DefaultBlockParameterName.LATEST, address ).addSingleTopic(EventEncoder.encode(TRANSFER_EVENT)); EthLog logs web3j.ethGetLogs(filter).send();参数说明第一个参数是起始区块第二个是结束区块第三个是合约地址列表。addSingleTopic是按事件的签名哈希过滤TRANSFER_EVENT是你预先定义好的Event对象。要注意EARLIEST是区块 0全链扫描会非常耗时实战中先确认目标合约的创建区块再从那附近开始扫可以省掉大量无意义请求。6.2 解析合约事件 topic 与 data以太坊日志的规则日志可以带多个topictopic[0]是事件签名哈希topic[1..]是事件的索引字段非索引字段编码在data里。web3j 的EventValuesExtractor能把这个过程自动化。Event transferEvent new Event(Transfer, Arrays.asList( new TypeReferenceAddress(true) {}, new TypeReferenceAddress(true) {}, new TypeReferenceUint256(false) {} )); EventValues values EventValuesExtractor.extractEventValues(log, transferEvent); Address from (Address) values.getIndexedValues().get(0); Address to (Address) values.getIndexedValues().get(1); Uint256 value (Uint256) values.getNonIndexedValues().get(0);逻辑说明new TypeReferenceAddress(true) {}末尾的布尔值是「是否索引」索引字段要从topic里取非索引字段从data里取。一旦把索引状态配错轻则取不到数据重则解析结果张冠李戴。事件解析里还有一个细节一个合约的 Transfer 事件签名是死的但不同合约的事件参数类型可能不一样。比如有的合约发的是Transfer(address,address,uint256)有的合约定义了Transfer(bytes32,address,uint256)结构相同但类型不同。定义Event时必须以目标合约的实际 ABI 为准不能拿同一份模板到处套。6.3 验证拿一个真实交易核对解析结果写完解析代码最重要的一步不是跑通而是验证解析结果对不对。最直观的验证方式是从浏览器或自己节点的 RPC 里取一笔真实交易比对字段。curl http://127.0.0.1:8545 -X POST -H Content-Type: application/json \ --data {jsonrpc:2.0,method:eth_getTransactionReceipt,params:[0x交易哈希],id:1}把返回的logs数组和你代码解析的结果逐字段比对。重点看topics[0]是否和预置的事件哈希一致data里的转出金额和接收方地址是否正确。这一步建议做成自动化测试备几条历史交易的 fixture每次改代码后跑一遍避免「这周改坏了什么自己不知道」。到了监听阶段我更推荐先观察一天把订阅到的日志和 etherscan 对比确认事件签名和数据解析完全匹配后再开启自动入库。因为事件日志一旦写错了后面的数据仓库全链路都会带病运行回滚成本极高。从区块扫描到事件监听这条链路做完后你会发现 web3j 直连模式最大的价值不在框架本身而在于你完全掌控了数据从链到库的每一个环节。没有第三方去清洗、去判断你的延迟和准确性都只取决于自己的节点和代码。最后再提醒一句所有链上数据落地前先确认你要画的那条边界——解析到区块头就够还是要解析到事件级这个决定会影响你的存储成本和节点配置整整一年。希望帮到你。本文还有配套的精品资源点击获取