简介一套基于 Java 开发的 TRC20 收款系统完整源码包面向需要接入 USDT-TRC20 收款能力的个人开发者或小微企业解决数字货币收款、订单状态监听、回调通知与资金对账等实际场景。压缩包共 377 个文件约 6.15MB其中包含 32 个 Java 后端源码、166 个前端 JS 脚本、35 个样式表、22 个 JSON 配置以及 SQL 初始化脚本涵盖接口层、业务层与前端管理界面目录结构清晰便于按模块阅读和二次开发。当前已有 274 人学习下载属于轻量但完整的收款系统示例。资料不仅覆盖收款地址生成、交易记录查询、回调验签等核心逻辑还包含管理后台页面与部署相关文件可直接基于常见 Java 技术栈运行改造适合具备一定 Java 基础、希望快速搭建 TRC20 收款服务的开发者参考。1. 基于 Java 的 TRC20 收款系统它解决的其实不是“查账”问题接手过几个支付项目之后我越来越觉得所谓 TRC20 收款系统核心不是把链上交易查出来而是把一笔用户转账变成业务库里一条不会多、不会少、不会重复的充值记录。用户把钱转过来只是第一步系统还要去发现这笔交易、等它确认、把金额和收款地址解析准确、再通知业务方发货。不管是自建钱包地址收款还是给电商、财务、充值平台做结算这套链路少一环都会翻车。市面上有托管支付服务但很多团队希望收款逻辑掌握在自己手里于是“基于 Java 开发 TRC20 收款系统”就成了常见做法用 Spring Boot 部署一个独立服务连 TronGrid 或本地节点轮询扫块解析 USDT-TRC20 转账确认后入账并回调。下面按这条链路拆开讲包含代码、参数和那些容易踩的坑。2. 先看懂一笔 USDT-TRC20 转账事件日志才是真相2.1 TRC20 转账和 TRX 转账在链上不是一回事第一次做 TRC20 收款的人十有八九会去找 Tron 的转账接口想直接按交易里的to字段判断收款方。结果发现钱包明明收到了 USDT交易里的to却不是自己的地址而是一个合约地址。原因是 TRC20 代币转账本质是一次合约调用不是原生 TRX 转账。用户调用的是 USDT 合约的transfer(address,uint256)方法真正发生变化的是合约内部账本上的归属关系最终体现为这笔合约交易产生的 Event Log 事件日志。所以“收款”真正要读的数据是交易收据里的日志不是外层交易的简单字段。这个点理解不了后面所有解析逻辑都建立在错误基础上。TRC20 的转账事件日志有三个关键要素日志所属合约地址也就是代币合约地址。USDT-TRC20 主网合约地址是TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t解析时必须先过滤这个地址否则其他合约产生的相同事件也会混进来。事件的 topic 数组。第一个 topic 是事件签名哈希TRC20 的Transfer事件签名哈希是固定的ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef第二个 topic 是转出方地址第三个是收款方地址。日志的data字段是一个 32 字节的uint256大整数代表转账金额单位是代币最小精度。USDT-TRC20 的精度是 6 位也就是说链上金额的最小单位是 1e-6 USDT。链上转账 50 USDT日志里的金额是50000000。后端处理时如果直接用这个整数入库不做精度换算账面会差十万八千里反过来如果用浮点数在 Java 里做除法再落库金额除以 1e6 以后很容易出现精度尾巴。常见做法是多存一份整数原始金额展示金额什么时候需要再算。2.2 Java 拉取链上交易的两条路径区块扫描和账户查询有了事件日志结构之后要考虑交易从哪来。在 Java 项目里通常有两条路用的 API 完全不同定位也不一样。第一条路是区块扫描也叫“扫块”。即定时调用 Tron 节点的/wallet/getnowblock获取当前最新块高度再调用/wallet/gettransactioninfobyblocknum按块号拿区块内的交易及日志。这种方式的优点是覆盖全只要在区块高度区间内发生的转账不管收款地址在不在系统里都能扫到天然适合多地址收款也方便对账。缺点是每个块都要请求一次对节点 API 的压力大区块多了要考虑批量取。第二条路是账户交易查询即 TronGrid v1 提供的/v1/accounts/{address}/transactions/trc20。直接传入收款地址和代币合约地址返回该地址的 TRC20 转账列表。优点是一行请求就把转账过滤好了不用去解析原始日志数组缺点是只能覆盖你传入的地址如果收款地址是后加的还得回扫历史区间而且 TronGrid 免费层限流比较明显。我一般的做法是主链路用区块扫描因为要保证不漏账户查询接口用来做补单和对账因为它在指定的时间窗口内筛交易非常方便。下面这个 Java 方法是主链路里最基础的节点客户端代码用 Spring 的 RestTemplate 调用节点接口。Component public class TronBlockClient { private final RestTemplate restTemplate new RestTemplate(); Value(${tron.api.base-url}) private String baseUrl; // 获取当前最新块高度 public long getNowBlockNumber() { String url baseUrl /wallet/getnowblock; ResponseEntityJsonNode resp restTemplate.postForEntity(url, {}, JsonNode.class); return resp.getBody() .get(block_header).get(raw_data).get(number) .asLong(); } // 获取指定块高的所有交易及收据日志 public JsonNode getTransactionsByBlock(long blockNumber) { String url baseUrl /wallet/gettransactioninfobyblocknum; MapString, Object body new HashMap(); body.put(num, blockNumber); ResponseEntityJsonNode resp restTemplate.postForEntity(url, body, JsonNode.class); return resp.getBody(); } }注意 Tron 的这几个接口都是 POST 请求即使getnowblock不需要参数也要传一个空 JSON 体。很多第一次接的人习惯性用 GET直接返回 404。gettransactioninfobyblocknum的请求体里只有一个字段num就是块号返回的 JSON 里有区块头、交易 ID 列表以及包含receipt和log的交易明细。这里的交易明细才是我们解析事件日志的数据源。另外节点地址配置上主网可以用 TronGrid 的公共地址https://api.trongrid.io但生产环境建议申请一个 API Key 放到请求头里否则限流会很厉害。也可以部署本地 java-tron 节点自己维护一个全节点或只同步相关区块的轻节点请求延迟和稳定性都会好很多代价是磁盘和运维成本上来了。2.3 从日志里解析转账金额和收款方手写解析器拿到gettransactioninfobyblocknum返回的 JSON 后就要遍历交易遍历每个交易的log数组过滤出 TRC20 的Transfer事件。下面这一段是解析器的核心逻辑我一般会把解析结果封装成一个Trc20Transfer对象包含交易哈希、块号、事件索引、转出方、收款方、金额这些字段。private static final String USDT_CONTRACT TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t; private static final String TRANSFER_TOPIC ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef; private static final BigDecimal USDT_SCALE BigDecimal.valueOf(1_000_000L); public ListTrc20Transfer parseBlockTransactions(JsonNode blockData) { ListTrc20Transfer list new ArrayList(); JsonNode txs blockData.get(transactions); if (txs null || !txs.isArray()) { return list; } for (JsonNode tx : txs) { String txId tx.get(id).asText(); long blockNumber tx.get(blockNumber).asLong(); JsonNode logs tx.get(log); if (logs null) continue; for (int i 0; i logs.size(); i) { JsonNode log logs.get(i); if (!USDT_CONTRACT.equals(log.get(address).asText())) { continue; // 不是 USDT 合约产生的日志跳过 } JsonNode topics log.get(topics); if (topics.size() 3 || !TRANSFER_TOPIC.equals(topics.get(0).asText())) { continue; // 不是 Transfer 事件跳过 } String fromHex topics.get(1).asText().substring(24); String toHex topics.get(2).asText().substring(24); String data log.get(data).asText(); BigInteger rawAmount new BigInteger(1, hexDecode(data)); String from toTronBase58(fromHex); String to toTronBase58(toHex); BigDecimal amount new BigDecimal(rawAmount).divide(USDT_SCALE); // 事件索引 i 很重要同一个 tx 里可能有多笔转账 list.add(new Trc20Transfer(txId, blockNumber, i, from, to, amount, rawAmount)); } } return list; }这里有两个细节需要解释。第一个是地址的 topic 表示。日志里 indexed 的地址参数是 32 字节前 12 字节是补零真正的 20 字节地址在末尾 40 个十六进制字符里。所以我用substring(24)截取后 40 位再转换成 Tron 的 Base58 地址格式。需要注意的是Tron 地址原始十六进制以41开头不同节点返回的日志 topic 可能带也可能不带这个前缀转换时加一个判断和处理会更稳。实际项目里我封装了一个TronAddressUtil工具类统一处理带前缀和不带前缀两种情况。第二个是金额精度。USDT 在 Tron 上精度为 6rawAmount是整数最小单位计算展示金额时用 BigDecimal 除以 1e6。这里必须用 BigDecimal不能用 double否则大金额转账在浮点运算中会丢精度。数据库层面我建议同时存两个字段amount_raw存整数原始值amount_decimal存 BigDecimal 换算后的值。入账、对账、生成报表都以amount_raw为准避免不同节点返回的数据精度不一致导致对不上账。3. 从扫块到入账确认、幂等、回调三步缺一不可3.1 区块确认数为什么到了链上还不能立刻入账有些做传统支付的人第一次看到 Tron 上的转账会觉得交易已经打包出块了就可以直接入账。但 Tron 用的是委托权益证明机制虽然确认速度和吞吐量比 PoW 链高但链上仍存在短时间内的重组、回滚可能性也就是说刚出块的那一瞬间交易还不能被认为是绝对不可逆的。成熟收款系统的做法是引入“确认块数”概念。扫块时不能拿最新块直接入账而是只处理“稳定高度”以下的交易。稳定高度等于当前最新块高减去确认块数。当前链高 100确认块数设为 19那么只有块高小于等于 81 的交易才允许入账。这样即使链发生了短时间回滚已经入账的交易也大概率是安全的。确认块数怎么设取决于业务对资金安全的要求。下面这个表是实践中常用的参考值因为 Tron 平均出块时间约 3 秒换算成等待时间可以帮助产品侧直观评估。业务场景确认块数预估等待时间小额活动充币追求体验6约 18 秒普通充值入账12约 36 秒大额转账、财务结算19约 57 秒确认块数不是越大越好。设得太大用户充值后迟迟不入账客诉和客服成本会上升设得太小遇到链上回滚就有可能被冲正造成账面虚增。我见过不少项目用 12 这个中间值也有项目把不同金额段配置不同确认数比如单笔超过 1 万 USDT 需要 19 个确认小额只需 6 个确认。这个策略可以做成配置项动态下发。在 Java 里实现确认判断比较简单核心就是把扫块游标压在“稳定高度”以内不要急着往最新块去扫。可以这样理解扫描器每次轮询时算出safeBlock latestBlock - confirmBlocks然后只扫当前游标到safeBlock之间的区间。最新块永远留给下一个轮询周期去处理。// 扫描主循环节选 Scheduled(fixedDelayString ${tron.scan.interval-ms:2000}) public void scanBlockRange() { long latestBlock tronBlockClient.getNowBlockNumber(); long safeBlock latestBlock - confirmBlocks; // 只处理已确认块 long lastCursor blockCursorService.getCursor(); if (lastCursor 0) { lastCursor safeBlock - 1; // 首次启动从当前安全块开始 } if (lastCursor safeBlock) { return; // 没有新确认块本轮跳过 } long batchEnd Math.min(lastCursor batchSize, safeBlock); for (long block lastCursor 1; block batchEnd; block) { JsonNode blockData tronBlockClient.getTransactionsByBlock(block); ListTrc20Transfer transfers parseBlockTransactions(blockData); paymentService.handleTransfers(transfers); } blockCursorService.saveCursor(batchEnd); }这段代码里有两个参数需要重点理解。第一个是batchSize表示单轮最多扫多少个块。节点接口处理能力有限一次扫几百个块很容易触发超时或限流我一般先设 50 到 100 个块一批压测后再调。第二个是游标也就是blockCursorService里存的上次处理到的块号。游标必须持久化服务重启后才能从上次位置继续而不是从头扫或在内存里丢掉。3.2 幂等入账同一笔交易只能入一次账扫块逻辑做好之后下一个问题是扫描器可能会把同一笔交易扫描多次。原因是多方面的比如服务重启、游标回退、链上数据重组后重扫。如果入账逻辑不拦截用户充 100 USDT库里出现两条 100 USDT 的充值记录后果就严重了。解决重复入账的办法不是靠代码判断“我有没有见过这个 txId”而是靠数据库的唯一索引和状态机双保险。第一条保险是唯一索引。入账表加上tx_id和event_index的联合唯一约束。为什么不是只用tx_id因为一条链上交易里可能包含多个 Transfer 事件比如某笔合约调用内部发生了多次代币转账只用交易哈希作唯一索引会把同一个 tx 里的第二笔转账挡在门外。加上event_index就能同时容纳一个 tx 里的多笔转账事件又不会重复入账。CREATE TABLE payment_record ( id BIGINT PRIMARY KEY AUTO_INCREMENT, tx_id VARCHAR(64) NOT NULL COMMENT 链上交易哈希, event_index INT NOT NULL COMMENT 同一交易内的事件序号, from_address VARCHAR(64) NOT NULL COMMENT 转出方地址, to_address VARCHAR(64) NOT NULL COMMENT 收款方地址, amount_raw BIGINT NOT NULL COMMENT 链上原始金额, amount_decimal DECIMAL(30,6) NOT NULL COMMENT USDT展示金额, block_number BIGINT NOT NULL COMMENT 所在区块高度, status VARCHAR(16) NOT NULL DEFAULT PENDING COMMENT PENDING/CONFIRMED, notify_status VARCHAR(16) NOT NULL DEFAULT NOTIFY_PENDING, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_tx_event (tx_id, event_index) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENTTRC20充值记录表;第二条保险是状态机。扫描到新交易时先插入一条PENDING状态的记录表示“已发现但还没最终确认”。当确认条件满足后再把状态更新为CONFIRMED。入账逻辑只在状态为CONFIRMED且notify_status为未通知时才回调业务方并更新回调状态。这样即使同一笔交易被扫描到 10 次数据库里的唯一约束会挡住重复插入状态机保证入账和回调只走一次。这样做还有个额外好处用户的充值记录里可以清晰区分“已到账待确认”和“已确认已完成”前端展示和客服查单都方便。用户看到“确认中”而不是直接消失客服工单也能少一些。3.3 回调通知上游业务怎么安全收到账入账成功后要通知上游业务系统比如电商订单状态改成“已支付”。回调这一步如果处理不好要么业务方永远不知道用户充了值要么业务方被重复通知。回调机制我一般拆成两个部分状态表和重试任务。payment_record表里的notify_status字段记录回调状态初始为NOTIFY_PENDING。回调成功后更新为NOTIFY_SUCCESS失败则更新为NOTIFY_FAIL并记录失败次数。后台有一个定时任务专门扫描回调失败或未回调的记录按指数退避策略重试。public void notifyBusiness(PaymentRecord record) { String callbackUrl bizCallbackConfig.getUrl(record.getBizOrderType()); int maxRetry 5; for (int attempt 1; attempt maxRetry; attempt) { try { MapString, Object body new HashMap(); body.put(txId, record.getTxId()); body.put(orderId, record.getBizOrderId()); body.put(amount, record.getAmountDecimal().toPlainString()); body.put(from, record.getFromAddress()); body.put(blockNumber, record.getBlockNumber()); restTemplate.postForEntity(callbackUrl, body, String.class); paymentRecordMapper.updateNotifyStatus(record.getId(), NOTIFY_SUCCESS); return; } catch (Exception e) { long waitMs Math.min(60_000L, 1000L * (long) Math.pow(10, attempt)); Thread.sleep(waitMs); // 1s, 10s, 100s, 然后封顶 60s } } // 超过重试次数进入人工补偿队列 compensationService.add(record.getId()); }回调请求本身要保证幂等。上游业务方收到回调后内部也需要用自己的orderId去查是否已经处理过这笔订单的支付通知处理过就直接返回成功避免因为网络超时导致同一笔回调发送两次而重复发货。这里的兜底原则是下游尽可能幂等上游也必须用自己的业务键做去重两边都做才能在极端情况下不产生资损。有人会问为什么不直接把回调放到消息队列里做异步通知。可以做但消息队列只是传输通道不能解决“回调成功”的语义问题。我见过不少团队把 TronGrid 的查询结果直接发到 MQ消费者消费失败就丢消息最后靠手工补单。真正常见的做法是先把业务状态落库再用状态字段驱动重试MQ 只是个加速通道不是唯一的可靠保障。4. TRC20 收款避坑5 个真实翻车现场与修法4.1 金额对不上用户转了 50 USDT库里成了 50现象用户在钱包里转了 50 USDT系统入账后金额显示 0.00005或者反过来入账 5000 万。原因USDT-TRC20 精度是 6 位链上日志里的金额是整数最小单位。50 USDT 在链上是50000000不是50。如果直接把原始整数当余额用或者用double去除以 1e6很容易出现精度丢失和数量级错误。解决入账和展示分离。数据库存amount_raw用BIGINT类型存链上原始整数展示时用BigDecimaldivide(USDT_SCALE)得到 USDT 金额。所有链上数据在 Java 里一律走 BigInteger 或 BigDecimal禁止用double和float参与金额运算。这个坑是所有 TRC20 收款系统里出现频率最高的没有之一。4.2 钱到了却不入账只扫了原生转账没扫事件日志现象用户转账记录在区块链浏览器里看得清清楚楚但系统里完全查不到这笔充值。原因扫块时只看了交易所层面的字段比如交易类型、转账金额、接收地址没有去解析合约调用里的log。TRC20 转账是合约事件原生字段里根本没有收款地址和代币金额的明确标记不解析日志就等同于无视链上实际发生的代币转移。解决官方交易接口返回的 JSON 里必须遍历每笔交易的log数组按 2.3 节的方法过滤合约地址和Transfer事件再解析topics和data。同时要注意扫描时连log为空的交易也要跳过不要因为某笔交易没有日志就直接报错中断一个块里如果有大量非合约交易解析异常会拖垮整个扫块流程。4.3 回调重复入账没丢业务方却收到两次通知现象用户充值一次业务系统收到两笔支付成功回调发货两次。原因扫码时该块被回扫。常见于扫块任务超时后游标没推进下一次轮询又从旧块重扫解析出来的同一笔交易再次走回调逻辑。如果回调接口本身没有去重重复发货就发生了。解决唯一索引只是挡了入账的重复回调的重复要单独处理。回调状态机里必须保证NOTIFY_SUCCESS只更新一次重试任务只扫notify_status NOTIFY_FAIL或超时未通知的记录。最稳妥的是回调请求体里带上txId、eventIndex、orderId和amount下游用自己的订单 ID 做幂等判断。如果业务方忽略幂等发送方再怎么重试都会出问题这个要在联调时明确要求对方支持。4.4 一个块都扫不到TronGrid 限流和连接超时现象本地测试一切正常部署上线后定时任务频繁报错要么是 HTTP 429要么是连接超时扫块进度完全停滞。原因TronGrid 免费层有比较严格的速率限制多个任务实例同时轮询的时候更容易踩到限流。错误发生后的重试策略如果不合理还会加剧限流形成雪崩。解决生产环境优先使用本地全节点或者至少给 TronGrid 申请正式 API Key 并配置到请求头。扫描参数上要把batchSize调小比如一个批次扫 20 到 50 个块每扫完一批休息 1 到 2 秒。请求失败时采用指数退避不要立刻疯狂重试。还有一个容易被忽略的点节点接口响应时间超过readTimeout时RestTemplate 会抛异常扫块循环里一定要捕获单块异常并记录块号跳过故障块继续扫后面等下一轮再回来补扫而不是整个链路卡死。4.5 确认了 19 个区块还是丢单对账才是最后的后悔药现象确认块数设在 19线上运行一段时间后对账单发现仍有几笔交易漏了既没入账也没报警。原因扫块游标跑得太快或者节点的某个块返回数据不完整但没报错导致交易被跳过。游标只进不退的设计在链上出现小范围重组时会让原本已扫描的区块数据发生变化而被忽略。解决不能只依赖扫块这一条链路要配一个每日对账任务。对账的逻辑是通过账户 TRC20 接口拉取某个收款地址当天所有 USDT 转账和数据库里的payment_record做差集发现缺失就补入账。对账任务弥补的是主扫链路的偶发遗漏它不需要每秒运行每天凌晨跑一次即可。下面第 5.2 节会把对账任务的具体实现展开。5. 部署后怎么验证模拟付款、每日对账、扫描参数调优5.1 上线前在 Shasta 测试网完整演练一遍接手一个新的 TRC20 收款服务我习惯先把环境切到 Tron 的 Shasta 测试网跑一遍完整流程而不是直接拿主网真实资金试。Shasta 测试网提供免费的测试 TRX可以从水龙头申请TronLink 钱包切到测试环境后也能直接使用。测试时重点关注三个场景小额转账比如 0.01 USDT验证精度换算是否正确。同金额重复转账比如连续两笔 10 USDT验证唯一索引和事件序号不会互相挡。确认块更新把confirm-blocks临时设为 1确认入账是否在下一个轮询周期内完成。测试网上 USDT 合约地址和主网不同配置时不要写死主网合约地址。最稳的做法是把tron.usdt-contract做成配置项不同环境用不同值。每次换环境部署第一件事就是检查配置里的合约地址否则所有日志过滤都会失效。Shasta 测试网的问题在于它毕竟不是主网区块稳定性和数据完整度都比主网差偶尔会遇到测试网络节点无响应。测试网用来验证业务逻辑就够了节点性能和限流表现必须在主网环境单独做压测不要拿测试网的延迟数据去评估生产容量。5.2 每日对账任务补掉扫块漏掉的那几笔对账任务的设计原则是“从另一条路把交易拿回来对比”所以我用 TronGrid v1 的账户 TRC20 查询接口来拉取指定收款地址在时间窗口内的转账记录然后和数据库比对。public ListJsonNode fetchTrc20Transactions(String address, Instant start, Instant end) { String url tronApiBase /v1/accounts/ address /transactions/trc20 ?contract_address usdtContract min_timestamp start.toEpochMilli() max_timestamp end.toEpochMilli() limit200; ListJsonNode result new ArrayList(); String nextUrl url; while (nextUrl ! null) { ResponseEntityJsonNode resp restTemplate.getForEntity(nextUrl, JsonNode.class); JsonNode data resp.getBody(); JsonNode items data.get(data); if (items ! null items.isArray()) { items.forEach(result::add); } JsonNode meta data.get(meta); // TronGrid 分页用 fingerprint 作为游标 if (meta ! null meta.has(fingerprint)) { nextUrl url fingerprint meta.get(fingerprint).asText(); } else { nextUrl null; } } return result; }这段代码里有 TronGrid 分页的一个关键参数fingerprint。这个接口一次最多返回 200 条记录超出时会在meta里返回一个fingerprint把它拼接回原 URL 的查询参数里就能拿下一页。很多人在这个接口上只拉了第一页数据量大时对账永远对不齐。拿到交易列表之后对账逻辑就比较简单了遍历接口返回的每条记录在payment_record里按tx_id和event_index查是否存在不存在的补插入账。补入账时状态直接设为CONFIRMED因为查询接口拉到的基本都是历史稳定交易不走确认等待逻辑。对账任务跑完要输出一份缺失清单方便排查是节点问题还是解析问题。5.3 扫描参数调优批次、轮询间隔、线程池扫块链路里最影响吞吐和稳定性的三个参数分别是batchSize、轮询间隔和线程池配置。它们的合理范围没有固定值和节点性能、网络环境强相关但可以给出一个经验性的起始配置。参数建议起始值调优方向tron.scan.batch-size50 个块节点延迟高就调小处理速度快就调大tron.scan.interval-ms2000ms确认块内没新块时适当增大tron.confirm-blocks12 或 19按业务资金风险等级配置扫块线程池核心数2大部分时候 1 个线程扫块足够要注意扫块线程和入账处理线程不要混在同一个线程池里。扫块线程只负责拉数据、解析、推入内存队列入账线程池负责消费队列执行数据库插入、状态更新、回调通知。这样即使回调接口响应慢也不会阻塞扫块进度扫块游标始终能往前推进。轮询间隔的处理也有技巧。很多项目用固定 2 秒的Scheduled任务是可行的但如果是大额收款场景更合适的是每次扫完一个批次后计算“下一个稳定块什么时候产生”然后动态休眠到那个时间点。这样既不会频繁空轮询也能在出块后第一时间扫到。6. 把收款地址做成动态配置加地址不用改代码重扫也能安全兜底很多收款系统的地址一开始是写在配置文件里的加一个收款地址就要重启服务。业务量上来之后这种做法的维护成本会越来越高。我自己习惯把收款地址挪到数据库里做成一张receive_address表扫块解析出的to_address只要在这张表里存在就进入入账流程不在表里的地址直接忽略。动态地址表的收益有两个。第一个是加地址零重启运营在后台录入一个新地址下一个扫描周期就自动生效。第二个是“生效区块号”这个概念变得自然每个地址创建时记一个effective_block扫描器只需要处理区块高度大于等于该地址effective_block的交易这样从历史某个时间点开始收款的需求也能支持不需要全量扫历史。重扫要特别小心。我见过有人直接改数据库把漏扫的交易status从PENDING改成CONFIRMED结果导致回调重复、账单重复。重扫一定要走独立的补偿通道把校核出的记录写入临时表确认无误后批量提交到payment_record。提交时唯一索引自然会挡住已存在的记录新记录再走一遍标准的回调流程。这样重扫一个时间窗口不会动到原有入账数据。这里还有一个多年养成的习惯不管是扫块游标还是重扫批次都必须落库记录操作人和操作时间线上出了问题能回溯。每次重构收款逻辑我都要求团队先写对账脚本再改代码改完代码跑一次对账两边一致才敢发布。这套流程听起来慢实际是给后续的每一天买的“后悔药”。希望帮到你。本文还有配套的精品资源点击获取
基于Java的TRC20收款系统：USDT链上转账解析与入账实战
简介一套基于 Java 开发的 TRC20 收款系统完整源码包面向需要接入 USDT-TRC20 收款能力的个人开发者或小微企业解决数字货币收款、订单状态监听、回调通知与资金对账等实际场景。压缩包共 377 个文件约 6.15MB其中包含 32 个 Java 后端源码、166 个前端 JS 脚本、35 个样式表、22 个 JSON 配置以及 SQL 初始化脚本涵盖接口层、业务层与前端管理界面目录结构清晰便于按模块阅读和二次开发。当前已有 274 人学习下载属于轻量但完整的收款系统示例。资料不仅覆盖收款地址生成、交易记录查询、回调验签等核心逻辑还包含管理后台页面与部署相关文件可直接基于常见 Java 技术栈运行改造适合具备一定 Java 基础、希望快速搭建 TRC20 收款服务的开发者参考。1. 基于 Java 的 TRC20 收款系统它解决的其实不是“查账”问题接手过几个支付项目之后我越来越觉得所谓 TRC20 收款系统核心不是把链上交易查出来而是把一笔用户转账变成业务库里一条不会多、不会少、不会重复的充值记录。用户把钱转过来只是第一步系统还要去发现这笔交易、等它确认、把金额和收款地址解析准确、再通知业务方发货。不管是自建钱包地址收款还是给电商、财务、充值平台做结算这套链路少一环都会翻车。市面上有托管支付服务但很多团队希望收款逻辑掌握在自己手里于是“基于 Java 开发 TRC20 收款系统”就成了常见做法用 Spring Boot 部署一个独立服务连 TronGrid 或本地节点轮询扫块解析 USDT-TRC20 转账确认后入账并回调。下面按这条链路拆开讲包含代码、参数和那些容易踩的坑。2. 先看懂一笔 USDT-TRC20 转账事件日志才是真相2.1 TRC20 转账和 TRX 转账在链上不是一回事第一次做 TRC20 收款的人十有八九会去找 Tron 的转账接口想直接按交易里的to字段判断收款方。结果发现钱包明明收到了 USDT交易里的to却不是自己的地址而是一个合约地址。原因是 TRC20 代币转账本质是一次合约调用不是原生 TRX 转账。用户调用的是 USDT 合约的transfer(address,uint256)方法真正发生变化的是合约内部账本上的归属关系最终体现为这笔合约交易产生的 Event Log 事件日志。所以“收款”真正要读的数据是交易收据里的日志不是外层交易的简单字段。这个点理解不了后面所有解析逻辑都建立在错误基础上。TRC20 的转账事件日志有三个关键要素日志所属合约地址也就是代币合约地址。USDT-TRC20 主网合约地址是TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t解析时必须先过滤这个地址否则其他合约产生的相同事件也会混进来。事件的 topic 数组。第一个 topic 是事件签名哈希TRC20 的Transfer事件签名哈希是固定的ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef第二个 topic 是转出方地址第三个是收款方地址。日志的data字段是一个 32 字节的uint256大整数代表转账金额单位是代币最小精度。USDT-TRC20 的精度是 6 位也就是说链上金额的最小单位是 1e-6 USDT。链上转账 50 USDT日志里的金额是50000000。后端处理时如果直接用这个整数入库不做精度换算账面会差十万八千里反过来如果用浮点数在 Java 里做除法再落库金额除以 1e6 以后很容易出现精度尾巴。常见做法是多存一份整数原始金额展示金额什么时候需要再算。2.2 Java 拉取链上交易的两条路径区块扫描和账户查询有了事件日志结构之后要考虑交易从哪来。在 Java 项目里通常有两条路用的 API 完全不同定位也不一样。第一条路是区块扫描也叫“扫块”。即定时调用 Tron 节点的/wallet/getnowblock获取当前最新块高度再调用/wallet/gettransactioninfobyblocknum按块号拿区块内的交易及日志。这种方式的优点是覆盖全只要在区块高度区间内发生的转账不管收款地址在不在系统里都能扫到天然适合多地址收款也方便对账。缺点是每个块都要请求一次对节点 API 的压力大区块多了要考虑批量取。第二条路是账户交易查询即 TronGrid v1 提供的/v1/accounts/{address}/transactions/trc20。直接传入收款地址和代币合约地址返回该地址的 TRC20 转账列表。优点是一行请求就把转账过滤好了不用去解析原始日志数组缺点是只能覆盖你传入的地址如果收款地址是后加的还得回扫历史区间而且 TronGrid 免费层限流比较明显。我一般的做法是主链路用区块扫描因为要保证不漏账户查询接口用来做补单和对账因为它在指定的时间窗口内筛交易非常方便。下面这个 Java 方法是主链路里最基础的节点客户端代码用 Spring 的 RestTemplate 调用节点接口。Component public class TronBlockClient { private final RestTemplate restTemplate new RestTemplate(); Value(${tron.api.base-url}) private String baseUrl; // 获取当前最新块高度 public long getNowBlockNumber() { String url baseUrl /wallet/getnowblock; ResponseEntityJsonNode resp restTemplate.postForEntity(url, {}, JsonNode.class); return resp.getBody() .get(block_header).get(raw_data).get(number) .asLong(); } // 获取指定块高的所有交易及收据日志 public JsonNode getTransactionsByBlock(long blockNumber) { String url baseUrl /wallet/gettransactioninfobyblocknum; MapString, Object body new HashMap(); body.put(num, blockNumber); ResponseEntityJsonNode resp restTemplate.postForEntity(url, body, JsonNode.class); return resp.getBody(); } }注意 Tron 的这几个接口都是 POST 请求即使getnowblock不需要参数也要传一个空 JSON 体。很多第一次接的人习惯性用 GET直接返回 404。gettransactioninfobyblocknum的请求体里只有一个字段num就是块号返回的 JSON 里有区块头、交易 ID 列表以及包含receipt和log的交易明细。这里的交易明细才是我们解析事件日志的数据源。另外节点地址配置上主网可以用 TronGrid 的公共地址https://api.trongrid.io但生产环境建议申请一个 API Key 放到请求头里否则限流会很厉害。也可以部署本地 java-tron 节点自己维护一个全节点或只同步相关区块的轻节点请求延迟和稳定性都会好很多代价是磁盘和运维成本上来了。2.3 从日志里解析转账金额和收款方手写解析器拿到gettransactioninfobyblocknum返回的 JSON 后就要遍历交易遍历每个交易的log数组过滤出 TRC20 的Transfer事件。下面这一段是解析器的核心逻辑我一般会把解析结果封装成一个Trc20Transfer对象包含交易哈希、块号、事件索引、转出方、收款方、金额这些字段。private static final String USDT_CONTRACT TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t; private static final String TRANSFER_TOPIC ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef; private static final BigDecimal USDT_SCALE BigDecimal.valueOf(1_000_000L); public ListTrc20Transfer parseBlockTransactions(JsonNode blockData) { ListTrc20Transfer list new ArrayList(); JsonNode txs blockData.get(transactions); if (txs null || !txs.isArray()) { return list; } for (JsonNode tx : txs) { String txId tx.get(id).asText(); long blockNumber tx.get(blockNumber).asLong(); JsonNode logs tx.get(log); if (logs null) continue; for (int i 0; i logs.size(); i) { JsonNode log logs.get(i); if (!USDT_CONTRACT.equals(log.get(address).asText())) { continue; // 不是 USDT 合约产生的日志跳过 } JsonNode topics log.get(topics); if (topics.size() 3 || !TRANSFER_TOPIC.equals(topics.get(0).asText())) { continue; // 不是 Transfer 事件跳过 } String fromHex topics.get(1).asText().substring(24); String toHex topics.get(2).asText().substring(24); String data log.get(data).asText(); BigInteger rawAmount new BigInteger(1, hexDecode(data)); String from toTronBase58(fromHex); String to toTronBase58(toHex); BigDecimal amount new BigDecimal(rawAmount).divide(USDT_SCALE); // 事件索引 i 很重要同一个 tx 里可能有多笔转账 list.add(new Trc20Transfer(txId, blockNumber, i, from, to, amount, rawAmount)); } } return list; }这里有两个细节需要解释。第一个是地址的 topic 表示。日志里 indexed 的地址参数是 32 字节前 12 字节是补零真正的 20 字节地址在末尾 40 个十六进制字符里。所以我用substring(24)截取后 40 位再转换成 Tron 的 Base58 地址格式。需要注意的是Tron 地址原始十六进制以41开头不同节点返回的日志 topic 可能带也可能不带这个前缀转换时加一个判断和处理会更稳。实际项目里我封装了一个TronAddressUtil工具类统一处理带前缀和不带前缀两种情况。第二个是金额精度。USDT 在 Tron 上精度为 6rawAmount是整数最小单位计算展示金额时用 BigDecimal 除以 1e6。这里必须用 BigDecimal不能用 double否则大金额转账在浮点运算中会丢精度。数据库层面我建议同时存两个字段amount_raw存整数原始值amount_decimal存 BigDecimal 换算后的值。入账、对账、生成报表都以amount_raw为准避免不同节点返回的数据精度不一致导致对不上账。3. 从扫块到入账确认、幂等、回调三步缺一不可3.1 区块确认数为什么到了链上还不能立刻入账有些做传统支付的人第一次看到 Tron 上的转账会觉得交易已经打包出块了就可以直接入账。但 Tron 用的是委托权益证明机制虽然确认速度和吞吐量比 PoW 链高但链上仍存在短时间内的重组、回滚可能性也就是说刚出块的那一瞬间交易还不能被认为是绝对不可逆的。成熟收款系统的做法是引入“确认块数”概念。扫块时不能拿最新块直接入账而是只处理“稳定高度”以下的交易。稳定高度等于当前最新块高减去确认块数。当前链高 100确认块数设为 19那么只有块高小于等于 81 的交易才允许入账。这样即使链发生了短时间回滚已经入账的交易也大概率是安全的。确认块数怎么设取决于业务对资金安全的要求。下面这个表是实践中常用的参考值因为 Tron 平均出块时间约 3 秒换算成等待时间可以帮助产品侧直观评估。业务场景确认块数预估等待时间小额活动充币追求体验6约 18 秒普通充值入账12约 36 秒大额转账、财务结算19约 57 秒确认块数不是越大越好。设得太大用户充值后迟迟不入账客诉和客服成本会上升设得太小遇到链上回滚就有可能被冲正造成账面虚增。我见过不少项目用 12 这个中间值也有项目把不同金额段配置不同确认数比如单笔超过 1 万 USDT 需要 19 个确认小额只需 6 个确认。这个策略可以做成配置项动态下发。在 Java 里实现确认判断比较简单核心就是把扫块游标压在“稳定高度”以内不要急着往最新块去扫。可以这样理解扫描器每次轮询时算出safeBlock latestBlock - confirmBlocks然后只扫当前游标到safeBlock之间的区间。最新块永远留给下一个轮询周期去处理。// 扫描主循环节选 Scheduled(fixedDelayString ${tron.scan.interval-ms:2000}) public void scanBlockRange() { long latestBlock tronBlockClient.getNowBlockNumber(); long safeBlock latestBlock - confirmBlocks; // 只处理已确认块 long lastCursor blockCursorService.getCursor(); if (lastCursor 0) { lastCursor safeBlock - 1; // 首次启动从当前安全块开始 } if (lastCursor safeBlock) { return; // 没有新确认块本轮跳过 } long batchEnd Math.min(lastCursor batchSize, safeBlock); for (long block lastCursor 1; block batchEnd; block) { JsonNode blockData tronBlockClient.getTransactionsByBlock(block); ListTrc20Transfer transfers parseBlockTransactions(blockData); paymentService.handleTransfers(transfers); } blockCursorService.saveCursor(batchEnd); }这段代码里有两个参数需要重点理解。第一个是batchSize表示单轮最多扫多少个块。节点接口处理能力有限一次扫几百个块很容易触发超时或限流我一般先设 50 到 100 个块一批压测后再调。第二个是游标也就是blockCursorService里存的上次处理到的块号。游标必须持久化服务重启后才能从上次位置继续而不是从头扫或在内存里丢掉。3.2 幂等入账同一笔交易只能入一次账扫块逻辑做好之后下一个问题是扫描器可能会把同一笔交易扫描多次。原因是多方面的比如服务重启、游标回退、链上数据重组后重扫。如果入账逻辑不拦截用户充 100 USDT库里出现两条 100 USDT 的充值记录后果就严重了。解决重复入账的办法不是靠代码判断“我有没有见过这个 txId”而是靠数据库的唯一索引和状态机双保险。第一条保险是唯一索引。入账表加上tx_id和event_index的联合唯一约束。为什么不是只用tx_id因为一条链上交易里可能包含多个 Transfer 事件比如某笔合约调用内部发生了多次代币转账只用交易哈希作唯一索引会把同一个 tx 里的第二笔转账挡在门外。加上event_index就能同时容纳一个 tx 里的多笔转账事件又不会重复入账。CREATE TABLE payment_record ( id BIGINT PRIMARY KEY AUTO_INCREMENT, tx_id VARCHAR(64) NOT NULL COMMENT 链上交易哈希, event_index INT NOT NULL COMMENT 同一交易内的事件序号, from_address VARCHAR(64) NOT NULL COMMENT 转出方地址, to_address VARCHAR(64) NOT NULL COMMENT 收款方地址, amount_raw BIGINT NOT NULL COMMENT 链上原始金额, amount_decimal DECIMAL(30,6) NOT NULL COMMENT USDT展示金额, block_number BIGINT NOT NULL COMMENT 所在区块高度, status VARCHAR(16) NOT NULL DEFAULT PENDING COMMENT PENDING/CONFIRMED, notify_status VARCHAR(16) NOT NULL DEFAULT NOTIFY_PENDING, created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_tx_event (tx_id, event_index) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENTTRC20充值记录表;第二条保险是状态机。扫描到新交易时先插入一条PENDING状态的记录表示“已发现但还没最终确认”。当确认条件满足后再把状态更新为CONFIRMED。入账逻辑只在状态为CONFIRMED且notify_status为未通知时才回调业务方并更新回调状态。这样即使同一笔交易被扫描到 10 次数据库里的唯一约束会挡住重复插入状态机保证入账和回调只走一次。这样做还有个额外好处用户的充值记录里可以清晰区分“已到账待确认”和“已确认已完成”前端展示和客服查单都方便。用户看到“确认中”而不是直接消失客服工单也能少一些。3.3 回调通知上游业务怎么安全收到账入账成功后要通知上游业务系统比如电商订单状态改成“已支付”。回调这一步如果处理不好要么业务方永远不知道用户充了值要么业务方被重复通知。回调机制我一般拆成两个部分状态表和重试任务。payment_record表里的notify_status字段记录回调状态初始为NOTIFY_PENDING。回调成功后更新为NOTIFY_SUCCESS失败则更新为NOTIFY_FAIL并记录失败次数。后台有一个定时任务专门扫描回调失败或未回调的记录按指数退避策略重试。public void notifyBusiness(PaymentRecord record) { String callbackUrl bizCallbackConfig.getUrl(record.getBizOrderType()); int maxRetry 5; for (int attempt 1; attempt maxRetry; attempt) { try { MapString, Object body new HashMap(); body.put(txId, record.getTxId()); body.put(orderId, record.getBizOrderId()); body.put(amount, record.getAmountDecimal().toPlainString()); body.put(from, record.getFromAddress()); body.put(blockNumber, record.getBlockNumber()); restTemplate.postForEntity(callbackUrl, body, String.class); paymentRecordMapper.updateNotifyStatus(record.getId(), NOTIFY_SUCCESS); return; } catch (Exception e) { long waitMs Math.min(60_000L, 1000L * (long) Math.pow(10, attempt)); Thread.sleep(waitMs); // 1s, 10s, 100s, 然后封顶 60s } } // 超过重试次数进入人工补偿队列 compensationService.add(record.getId()); }回调请求本身要保证幂等。上游业务方收到回调后内部也需要用自己的orderId去查是否已经处理过这笔订单的支付通知处理过就直接返回成功避免因为网络超时导致同一笔回调发送两次而重复发货。这里的兜底原则是下游尽可能幂等上游也必须用自己的业务键做去重两边都做才能在极端情况下不产生资损。有人会问为什么不直接把回调放到消息队列里做异步通知。可以做但消息队列只是传输通道不能解决“回调成功”的语义问题。我见过不少团队把 TronGrid 的查询结果直接发到 MQ消费者消费失败就丢消息最后靠手工补单。真正常见的做法是先把业务状态落库再用状态字段驱动重试MQ 只是个加速通道不是唯一的可靠保障。4. TRC20 收款避坑5 个真实翻车现场与修法4.1 金额对不上用户转了 50 USDT库里成了 50现象用户在钱包里转了 50 USDT系统入账后金额显示 0.00005或者反过来入账 5000 万。原因USDT-TRC20 精度是 6 位链上日志里的金额是整数最小单位。50 USDT 在链上是50000000不是50。如果直接把原始整数当余额用或者用double去除以 1e6很容易出现精度丢失和数量级错误。解决入账和展示分离。数据库存amount_raw用BIGINT类型存链上原始整数展示时用BigDecimaldivide(USDT_SCALE)得到 USDT 金额。所有链上数据在 Java 里一律走 BigInteger 或 BigDecimal禁止用double和float参与金额运算。这个坑是所有 TRC20 收款系统里出现频率最高的没有之一。4.2 钱到了却不入账只扫了原生转账没扫事件日志现象用户转账记录在区块链浏览器里看得清清楚楚但系统里完全查不到这笔充值。原因扫块时只看了交易所层面的字段比如交易类型、转账金额、接收地址没有去解析合约调用里的log。TRC20 转账是合约事件原生字段里根本没有收款地址和代币金额的明确标记不解析日志就等同于无视链上实际发生的代币转移。解决官方交易接口返回的 JSON 里必须遍历每笔交易的log数组按 2.3 节的方法过滤合约地址和Transfer事件再解析topics和data。同时要注意扫描时连log为空的交易也要跳过不要因为某笔交易没有日志就直接报错中断一个块里如果有大量非合约交易解析异常会拖垮整个扫块流程。4.3 回调重复入账没丢业务方却收到两次通知现象用户充值一次业务系统收到两笔支付成功回调发货两次。原因扫码时该块被回扫。常见于扫块任务超时后游标没推进下一次轮询又从旧块重扫解析出来的同一笔交易再次走回调逻辑。如果回调接口本身没有去重重复发货就发生了。解决唯一索引只是挡了入账的重复回调的重复要单独处理。回调状态机里必须保证NOTIFY_SUCCESS只更新一次重试任务只扫notify_status NOTIFY_FAIL或超时未通知的记录。最稳妥的是回调请求体里带上txId、eventIndex、orderId和amount下游用自己的订单 ID 做幂等判断。如果业务方忽略幂等发送方再怎么重试都会出问题这个要在联调时明确要求对方支持。4.4 一个块都扫不到TronGrid 限流和连接超时现象本地测试一切正常部署上线后定时任务频繁报错要么是 HTTP 429要么是连接超时扫块进度完全停滞。原因TronGrid 免费层有比较严格的速率限制多个任务实例同时轮询的时候更容易踩到限流。错误发生后的重试策略如果不合理还会加剧限流形成雪崩。解决生产环境优先使用本地全节点或者至少给 TronGrid 申请正式 API Key 并配置到请求头。扫描参数上要把batchSize调小比如一个批次扫 20 到 50 个块每扫完一批休息 1 到 2 秒。请求失败时采用指数退避不要立刻疯狂重试。还有一个容易被忽略的点节点接口响应时间超过readTimeout时RestTemplate 会抛异常扫块循环里一定要捕获单块异常并记录块号跳过故障块继续扫后面等下一轮再回来补扫而不是整个链路卡死。4.5 确认了 19 个区块还是丢单对账才是最后的后悔药现象确认块数设在 19线上运行一段时间后对账单发现仍有几笔交易漏了既没入账也没报警。原因扫块游标跑得太快或者节点的某个块返回数据不完整但没报错导致交易被跳过。游标只进不退的设计在链上出现小范围重组时会让原本已扫描的区块数据发生变化而被忽略。解决不能只依赖扫块这一条链路要配一个每日对账任务。对账的逻辑是通过账户 TRC20 接口拉取某个收款地址当天所有 USDT 转账和数据库里的payment_record做差集发现缺失就补入账。对账任务弥补的是主扫链路的偶发遗漏它不需要每秒运行每天凌晨跑一次即可。下面第 5.2 节会把对账任务的具体实现展开。5. 部署后怎么验证模拟付款、每日对账、扫描参数调优5.1 上线前在 Shasta 测试网完整演练一遍接手一个新的 TRC20 收款服务我习惯先把环境切到 Tron 的 Shasta 测试网跑一遍完整流程而不是直接拿主网真实资金试。Shasta 测试网提供免费的测试 TRX可以从水龙头申请TronLink 钱包切到测试环境后也能直接使用。测试时重点关注三个场景小额转账比如 0.01 USDT验证精度换算是否正确。同金额重复转账比如连续两笔 10 USDT验证唯一索引和事件序号不会互相挡。确认块更新把confirm-blocks临时设为 1确认入账是否在下一个轮询周期内完成。测试网上 USDT 合约地址和主网不同配置时不要写死主网合约地址。最稳的做法是把tron.usdt-contract做成配置项不同环境用不同值。每次换环境部署第一件事就是检查配置里的合约地址否则所有日志过滤都会失效。Shasta 测试网的问题在于它毕竟不是主网区块稳定性和数据完整度都比主网差偶尔会遇到测试网络节点无响应。测试网用来验证业务逻辑就够了节点性能和限流表现必须在主网环境单独做压测不要拿测试网的延迟数据去评估生产容量。5.2 每日对账任务补掉扫块漏掉的那几笔对账任务的设计原则是“从另一条路把交易拿回来对比”所以我用 TronGrid v1 的账户 TRC20 查询接口来拉取指定收款地址在时间窗口内的转账记录然后和数据库比对。public ListJsonNode fetchTrc20Transactions(String address, Instant start, Instant end) { String url tronApiBase /v1/accounts/ address /transactions/trc20 ?contract_address usdtContract min_timestamp start.toEpochMilli() max_timestamp end.toEpochMilli() limit200; ListJsonNode result new ArrayList(); String nextUrl url; while (nextUrl ! null) { ResponseEntityJsonNode resp restTemplate.getForEntity(nextUrl, JsonNode.class); JsonNode data resp.getBody(); JsonNode items data.get(data); if (items ! null items.isArray()) { items.forEach(result::add); } JsonNode meta data.get(meta); // TronGrid 分页用 fingerprint 作为游标 if (meta ! null meta.has(fingerprint)) { nextUrl url fingerprint meta.get(fingerprint).asText(); } else { nextUrl null; } } return result; }这段代码里有 TronGrid 分页的一个关键参数fingerprint。这个接口一次最多返回 200 条记录超出时会在meta里返回一个fingerprint把它拼接回原 URL 的查询参数里就能拿下一页。很多人在这个接口上只拉了第一页数据量大时对账永远对不齐。拿到交易列表之后对账逻辑就比较简单了遍历接口返回的每条记录在payment_record里按tx_id和event_index查是否存在不存在的补插入账。补入账时状态直接设为CONFIRMED因为查询接口拉到的基本都是历史稳定交易不走确认等待逻辑。对账任务跑完要输出一份缺失清单方便排查是节点问题还是解析问题。5.3 扫描参数调优批次、轮询间隔、线程池扫块链路里最影响吞吐和稳定性的三个参数分别是batchSize、轮询间隔和线程池配置。它们的合理范围没有固定值和节点性能、网络环境强相关但可以给出一个经验性的起始配置。参数建议起始值调优方向tron.scan.batch-size50 个块节点延迟高就调小处理速度快就调大tron.scan.interval-ms2000ms确认块内没新块时适当增大tron.confirm-blocks12 或 19按业务资金风险等级配置扫块线程池核心数2大部分时候 1 个线程扫块足够要注意扫块线程和入账处理线程不要混在同一个线程池里。扫块线程只负责拉数据、解析、推入内存队列入账线程池负责消费队列执行数据库插入、状态更新、回调通知。这样即使回调接口响应慢也不会阻塞扫块进度扫块游标始终能往前推进。轮询间隔的处理也有技巧。很多项目用固定 2 秒的Scheduled任务是可行的但如果是大额收款场景更合适的是每次扫完一个批次后计算“下一个稳定块什么时候产生”然后动态休眠到那个时间点。这样既不会频繁空轮询也能在出块后第一时间扫到。6. 把收款地址做成动态配置加地址不用改代码重扫也能安全兜底很多收款系统的地址一开始是写在配置文件里的加一个收款地址就要重启服务。业务量上来之后这种做法的维护成本会越来越高。我自己习惯把收款地址挪到数据库里做成一张receive_address表扫块解析出的to_address只要在这张表里存在就进入入账流程不在表里的地址直接忽略。动态地址表的收益有两个。第一个是加地址零重启运营在后台录入一个新地址下一个扫描周期就自动生效。第二个是“生效区块号”这个概念变得自然每个地址创建时记一个effective_block扫描器只需要处理区块高度大于等于该地址effective_block的交易这样从历史某个时间点开始收款的需求也能支持不需要全量扫历史。重扫要特别小心。我见过有人直接改数据库把漏扫的交易status从PENDING改成CONFIRMED结果导致回调重复、账单重复。重扫一定要走独立的补偿通道把校核出的记录写入临时表确认无误后批量提交到payment_record。提交时唯一索引自然会挡住已存在的记录新记录再走一遍标准的回调流程。这样重扫一个时间窗口不会动到原有入账数据。这里还有一个多年养成的习惯不管是扫块游标还是重扫批次都必须落库记录操作人和操作时间线上出了问题能回溯。每次重构收款逻辑我都要求团队先写对账脚本再改代码改完代码跑一次对账两边一致才敢发布。这套流程听起来慢实际是给后续的每一天买的“后悔药”。希望帮到你。本文还有配套的精品资源点击获取
