web3.js web3-utils 实用工具包全解析:从 4.x 版本演进看以太坊开发工具链的底层能力
web3.js web3-utils 实用工具包全解析:从 4.x 版本演进看以太坊开发工具链的底层能力
web3-utils 是 web3.js 生态中面向 DApp 开发者的通用工具子包,承担着数值与单位换算、哈希计算、类型校验、JSON-RPC 载荷构造、Socket 连接管理等基础职责。本文以仓库内 packages/web3-utils/CHANGELOG.md 的版本记录为主线骨架,结合 packages/web3-utils/src 目录下的真实源码实现,系统梳理 web3-utils 从 4.0.1-alpha 到 4.3.3 的能力演进、关键函数用法与底层原理,帮助你在使用 web3.utils 或独立安装 web3-utils 时,准确理解每个工具函数的行为与边界。
一、包定位与接入方式
根据 packages/web3-utils/README.md 的定义,web3-utils 是 web3.js 的子包,包含 DApp 开发者常用的实用函数。当前仓库中该包版本为 4.3.3(见 packages/web3-utils/package.json),支持 Node.js >= 14,并采用 LGPL-3.0 协议。
两种典型接入方式:
# 方式一:随主包使用(推荐在完整 web3 场景下)
npm install web3
# 或 yarn add web3
# 方式二:独立安装,构建轻量应用(tree-shaking 友好)
npm install web3-utils
# 或 yarn add web3-utils
方式一的用法(通过 web3.utils 命名空间):
import { Web3 } from 'web3';
const web3 = new Web3();
const value = web3.utils.fromWei('1', 'ether'); // "0.000000000000000001"
方式二的用法(按需导入,更利于减小打包体积):
import { fromWei, soliditySha3Raw } from 'web3-utils';
console.log(fromWei('1', 'ether'));
console.log(soliditySha3Raw({ type: 'string', value: 'helloworld' }));
从源码看,包的导出面非常全面。packages/web3-utils/src/index.ts 统一导出了 converters(转换器)、event_emitter(事件发射器)、validation(校验)、formatter(格式化)、hash(哈希)、random(随机数)、string_manipulation(字符串操作)、objects(对象工具)、promise_helpers(Promise 工具)、json_rpc(JSON-RPC 工具)、web3_deferred_promise、chunk_response_parser、uuid、web3_eip1193_provider、socket_provider、uint8array 等多个模块,并为了兼容 1.x 额外导出了 AbiItem 类型(源自 web3-types)。
二、异步与轮询利器:promise_helpers 模块
CHANGELOG 在 4.0.1-alpha.1 中记录了最早引入的一组 Promise 工具函数:pollTillDefined、rejectIfTimeout、rejectIfConditionAtInterval,官方描述是"在处理涉及轮询、超时拒绝或按时间间隔重复检查条件是否满足的 Promise 时非常有用"。
2.1 轮询直到有结果:pollTillDefined
pollTillDefined 会按给定间隔反复调用一个异步函数,直到返回值非 undefined/null,或超时为止。其底层实现在 packages/web3-utils/src/promise_helpers.ts:
export async function pollTillDefined<T>(
func: AsyncFunction<T>,
interval: number,
): Promise<Exclude<T, undefined>> {
return pollTillDefinedAndReturnIntervalId(func, interval)[0];
}
其中 AsyncFunction<T, K = unknown> 是 (...args: K[]) => Promise<T> 的类型别名。真正完成轮询的是 pollTillDefinedAndReturnIntervalId,它返回 [Promise<Exclude<T, undefined>>, Timer] 二元组——前者是最终结果 Promise,后者是 setInterval 返回的定时器 ID。轮询循环内部每次调用都会经过 waitWithTimeout(func, interval) 包裹:当某次调用返回非空值(isNullish(res) 为假)时,立即 clearInterval 并 resolve;若调用抛出异常,则清空定时器并 reject。
两点实践建议:
- 如果不需要拿到 intervalId,直接使用
pollTillDefined即可;源码注释明确提示它"将在下一个大版本中废弃",推荐使用能同时返回 IntervalId 的pollTillDefinedAndReturnIntervalId。 - 典型场景是等待交易收据、等待 ENS 解析结果、等待节点同步到某个区块号等"轮询直到有确定答案"的需求。
2.2 超时强制拒绝:rejectIfTimeout
rejectIfTimeout(timeout, error) 返回 [Timer, Promise<never>],其中 Promise 会在 timeout 毫秒后以指定 error reject。源码实现非常直接:
export function rejectIfTimeout(timeout: number, error: Error): [Timer, Promise<never>] {
let timeoutId: Timer | undefined;
const rejectOnTimeout = new Promise<never>((_, reject) => {
timeoutId = setTimeout(() => {
reject(error);
}, timeout);
});
return [timeoutId!, rejectOnTimeout];
}
使用示例(源码 JSDoc 中的例子):
const [timerId, promise] = web3.utils.rejectIfTimeout(100, new Error('time out'));
将返回的 Promise 与其他 Promise 一起放入 Promise.race,即可实现"超时即失败"的竞速控制;拿到 timerId 后记得在分支结束时 clearTimeout,避免定时器泄漏。
2.3 条件触发拒绝:rejectIfConditionAtInterval
rejectIfConditionAtInterval(cond, interval) 会按 interval 间隔重复执行条件函数 cond,一旦 cond 返回了非空值(视为错误对象),立即清除定时器并以该值 reject。它返回 [Timer, Promise<never>]。适合实现"心跳检测失败即断开""余额低于阈值即告警"这类主动监控逻辑。
2.4 配套基础函数:waitWithTimeout 与 isPromise
waitWithTimeout(awaitable, timeout, error?):等待一个 Promise(或会被调用的异步函数),若在timeout内未完成,则抛出传入的error;未传error时返回undefined。实现上利用Promise.race,并在结束后clearTimeout。isPromise(object):4.0.1-alpha.2 新增,替代 Node 环境才有、浏览器不可用的util/types.isPromise。判定逻辑为:对象是object或function,且拥有then函数(见 packages/web3-utils/src/promise_helpers.ts)。
这些函数的正确性有单元测试保障,测试位于 packages/web3-utils/test/unit/promise_helpers.test.ts。
三、UUID 与 JSON-RPC ID:uuid 与 json_rpc 模块
4.0.1-alpha.2 引入了 uuidV4 函数,并同步修复了一个重要问题:"Responses get mixed up due to conflicting payload IDs"(响应因冲突的载荷 ID 而混淆)。这正是 JSON-RPC 请求 id 唯一性问题的根源。
3.1 uuidV4:随机版本 4 UUID
packages/web3-utils/src/uuid.ts 中 uuidV4 的实现思路:先调用 randomBytes(16)(源自 packages/web3-utils/src/random.ts,其内部委托 ethereum-cryptography 的 getRandomBytesSync),再按照 RFC 4122 设置版本位与变体位:
bytes[6] = (bytes[6] & 0x0f) | 0x40; // 版本 4
bytes[8] = (bytes[8] & 0x3f) | 0x80; // RFC 4122 变体
最终把 16 字节的十六进制串按 8-4-4-4-12 的格式用 - 拼接,形如 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed。
3.2 setRequestIdStart 与 toPayload:可控的请求 ID
packages/web3-utils/src/json_rpc.ts 中的 setRequestIdStart(start) 允许传入起始数字,让后续 JSON-RPC 请求的 id 从该数字开始递增;传入 undefined 则回退到 UUID 模式(默认行为)。toPayload 在构造请求载荷时按 request.id ?? requestIdSeed ?? uuidV4() 的优先级取值——这意味着你既可以完全自定义 ID,也可以用 setRequestIdStart 得到可预测的自增数字 ID,或者依赖默认的 UUID 保证全局唯一性。
同文件还提供了一组响应判定工具:isResponseWithResult、isResponseWithError、isResponseWithNotification、isSubscriptionResult、isValidResponse、isBatchResponse 等,用于区分 JSON-RPC 2.0 响应、通知与订阅推送消息。
四、数值与单位转换:converters 模块的核心函数
CHANGELOG 中有大量条目围绕数值转换展开,这些函数集中在 packages/web3-utils/src/converters.ts,也是开发中最高频使用的一批 API。
4.1 numberToHex 与 hexstrict 参数(4.0.1-rc.2 新增)
numberToHex(value, hexstrict?) 将数值转十六进制。当 hexstrict 为 true 时,若结果长度为奇数会在前面补 0,保证严格的字节对齐(奇数长度的 hex 串按字节读取会有歧义)。实现上复用 web3-validator 的 numberToHex,再针对正负奇数长度做 '0x0' / '-0x0' 前缀修正。4.0.3 修复了 BigInt 输入在 numberToHex 中通过校验的问题——因此现在传 BigInt 也不会被误拦截。
4.2 toNumber 与 toBigInt:大数安全(4.2.2 / 4.2.3 修复)
toNumber(value) 的返回类型是 number | bigint:
- 输入为
number时,若大于1e20会打印精度丢失警告并返回BigInt,因为 JavaScript 将大于等于 10^21 的数字转字符串时会变成科学计数法(如String(10000000000000000000000)得到'1e+22'),导致后续解析错误; - 输入为
bigint时,仅在[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]范围内转换为number,否则原样返回bigint; - 输入为 hex 字符串时走
hexToNumber。
4.2.2 的"修复 toNumber 对大数的错误解析"、4.2.3 的"修复 toHex 对 Uint8Array/Buffer 的错误十六进制化"均落在这条逻辑线上。toBigInt(value) 则统一将 number/bigint/数字字符串(含负号)转换为 bigint。
4.3 toWei / fromWei:单位换算与精度警告(4.3.0 系列)
toWei(number, unit) 与 fromWei(number, unit) 负责以太坊单位与 wei 之间的换算。单位表 ethUnitMap 定义在 converters.ts 顶部(@internal),覆盖从 noether、wei、kwei/Kwei/babbage/femtoether、mwei/Mwei/lovelace/picoether、gwei/Gwei/shannon/nanoether/nano、szabo/microether/micro、finney/milliether/milli、ether 到 kether/grand、mether、gether、tether 的全量别名,全部以 BigInt 存储倍率。
4.3.0 的重要行为变更:
- 单位参数支持整数,即把单位直接当作 10 的幂次处理(
bigintPower(BigInt(10), BigInt(unit))),例如toWei('1', 6)等价于mwei; - 当传入
number类型且数值过大(> 1e20)或过小(< 1e-15)时,会打印PrecisionLossWarning提示使用string或BigInt避免精度丢失; - 支持科学计数法输入;
- 按单位正确修剪小数尾部零。
4.3.3 修复了 fromWei 在输入为 0 时返回 "0" 而不是 "0.0" 的问题。注意 fromWei 总是返回字符串,toWei 亦然,这是为了不丢失大数精度。
4.4 字节与 hex 互转(4.0.1-rc.2 的 Buffer → Uint8Array 迁移)
4.0.1-rc.2 是一次影响面很大的破坏性变更:全包用 Uint8Array 取代 Buffer。hexToBytes、randomBytes 不再返回 Buffer 而返回 Uint8Array;sha3、keccak256Wrapper 不再接受 Buffer 输入;bytesToBuffer 被移除,统一使用 bytesToUint8Array。4.2.3 又修复了 isUint8Array 对 Buffer 返回 false 的问题,保证浏览器与 Node 环境下行为一致。
常用互转函数速览(均带示例输出,见源码 JSDoc):
| 函数 | 作用 | 示例 |
|---|---|---|
bytesToUint8Array |
任意字节表示转 Uint8Array | "0xab" → Uint8Array(1) [171] |
bytesToHex |
字节数组转 hex | Uint8Array([72, 12]) → "0x480c" |
hexToBytes |
hex 转字节数组(自动补 0x) |
'0x74657374' → Uint8Array(4) [116, 101, 115, 116] |
hexToNumber / toDecimal |
hex 转 number/bigint | '0xa' → 10 |
numberToHex / fromDecimal |
数值转 hex | 10 → "0xa" |
utf8ToHex / fromUtf8 / stringToHex |
UTF-8 字符串转 hex | 'web3.js' → "0x776562332e6a73" |
hexToUtf8 / toUtf8 / hexToString |
hex 转 UTF-8 字符串 | '0x48656c6c6f20576f726c64' → "Hello World" |
asciiToHex / fromAscii |
ASCII 转 hex | 'Hello World' → "0x48656c6c6f20576f726c64" |
hexToAscii / toAscii |
hex 转 ASCII | 同上反向 |
toHex |
智能推断类型并转 hex(可返回类型) | toHex(10) → "0xa" |
其中 toHex 是"自动转换器":对地址返回小写 0x 形式,对布尔返回 0x01/0x00,对数字/大整数走 numberToHex,对 Uint8Array 走 bytesToHex,对普通对象则先 JSON.stringify 再按 UTF-8 编码——这也是 1.x 用户最熟悉的语义。需要注意 toHex 无法处理时抛出 HexProcessingError。
五、哈希与签名数据:hash 模块
packages/web3-utils/src/hash.ts 提供以太坊生态最常用的哈希工具。
5.1 sha3 与 keccak256Wrapper
keccak256Wrapper 是 ethereum-cryptography/keccak256 的包装器,扩展了输入类型:支持 string、number、bigint、字节数组。对数字/大整数会先转成十进制字符串再 UTF-8 编码(如 keccak256Wrapper(1) 计算的是字符串 "1" 的哈希),对非严格 hex 的字符串按 UTF-8 处理,否则按字节处理。
sha3(data) 在 keccak256Wrapper 之上增加了一层 EIP-1052 语义:当哈希结果等于空数据的 Keccak-256 值 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470(即 SHA3_EMPTY_BYTES 常量)时返回 undefined。例如:
console.log(web3.utils.sha3('web3.js'));
// > 0x63667efb1961039c9bb0d6ea7a5abdd223a3aca7daa5044ad894226e1f83919a
console.log(web3.utils.sha3(''));
// > undefined
若你希望空输入也返回固定哈希值而非 undefined,应使用 sha3Raw。CHANGELOG 中 4.0.6 记录的"soliditySha3() 支持 BigInt"也位于本模块——soliditySha3 系列负责按 Solidity 类型(如 { type: 'string', value: '...' } 或 { t: 'uint256', v: 1n })编码参数后计算 Keccak-256,是构造 keccak256(abi.encodePacked(...)) 式哈希的便捷入口。
5.2 相关字符串工具:padLeft / padRight
4.3.2 修复了 padRight 在大型 uint 上的校验失败问题。这类填充函数(padLeft、padRight、toTwosComplement、fromTwosComplement)位于 packages/web3-utils/src/string_manipulation.ts,在 ABI 编码与格式化流程中被广泛依赖。
六、格式化输出:formatter 模块与 DataFormat
4.0.1-rc.1 将 FMT_NUMBER、NumberTypes、FMT_BYTES、ByteTypes、DataFormat、DEFAULT_RETURN_FORMAT、ETH_DATA_FORMAT、FormatType 等类型迁移到了 web3-types(见 packages/web3-types/src/data_format_types.ts),web3-utils 侧保留运行时的格式化能力。
4.2.3 变更:format 方法的 returnFormat 参数现在有默认值 DEFAULT_RETURN_FORMAT,即调用方可以省略该参数。
packages/web3-utils/src/formatter.ts 的核心是 convertScalarValue(value, ethType, format),它根据以太坊类型和输出格式做转换:
int/uint类型依据format.number在四种模式间切换:FMT_NUMBER.NUMBER(number)、FMT_NUMBER.HEX(hex 字符串)、FMT_NUMBER.STR(十进制字符串)、FMT_NUMBER.BIGINT(bigint);bytes类型依据format.bytes在FMT_BYTES.HEX与FMT_BYTES.UINT8ARRAY之间切换,固定长度字节还会做padLeft/uint8ArrayConcat补齐。
理解这套 DataFormat 机制,就能掌控 web3.eth.getBalance(addr) 等调用返回的是 number、bigint、hex 字符串还是 Uint8Array——这是从 1.x 迁移到 4.x 时最需要适应的行为差异之一(对应官方 Migration Guide 中 web3-utils 一节的内容)。
七、网络层能力:SocketProvider 与事件系统
7.1 SocketProvider 的队列管理(4.1.0 新增)
CHANGELOG 4.1.0 为 SocketProvider 增加了四个公开方法(实现于 packages/web3-utils/src/socket_provider.ts):
getPendingRequestQueueSize():返回等待中的请求队列大小(第 196 行);getSentRequestsQueueSize():返回已发送但未确认的请求队列大小(第 205 行);clearQueues(event?):清空两类队列;safeDisconnect(code?, data?, forceDisconnect = false, ms = 1000):仅在请求队列与已发送队列均为 0 时才安全断开;forceDisconnect为true或超过ms毫秒后仍强制断开。
这套 API 解决了 WebSocket 提供者在有未完成请求时直接断开导致响应丢失的竞态问题——safeDisconnect 的语义就是"确认没有在途请求后再断链"。
7.2 更早的基础设施变更
- 4.0.1-alpha.4:新增
SocketProvider类与Eip1193Provider抽象类; - 4.0.1-rc.0:
SocketProvider改为 resolve JSON-RPC 响应错误而非 reject,且暴露了SocketConnection的 getter; - 4.3.1:
_sendPendingRequests会捕获来自_sendToSocket的未处理错误。
7.3 EventEmitter 的演进(4.0.7 / 4.2.1)
4.0.7 实现了并导出自定义 EventEmitter 以替代 Node 的 EventEmitter(解决浏览器环境兼容);4.2.1 又将其替换为 eventemitter3,以支持 React Native 构建。当前 packages/web3-utils/package.json 的依赖中可以看到 eventemitter3: ^5.0.1。4.0.7 同时修复了 Babel/React 默认配置下的 BigInt 报错("TypeError: Cannot convert a BigInt value to a number")以及块处理逻辑(chunks processing)的 bug。
八、其他值得关注的能力
- 随机数(4.0.1-rc.2 起返回 Uint8Array):packages/web3-utils/src/random.ts 提供
randomBytes(size)与randomHex(byteSize),底层委托ethereum-cryptography的getRandomBytesSync。 - 区块标签比较(4.0.1-rc.0):
compareBlockNumbers移除了genesis标签支持,新增safe与finalized标签;4.0.1-rc.1 之后该函数仅支持"两个区块标签参数"(除earliest与数字的组合外)或"两个区块号参数"的比较。 - 兼容性导出(4.2.0):补回 1.x 中存在的
AbiItem类型导出,降低迁移成本。 - 构建产物(4.0.1-rc.1):源码文件纳入发布包,并提供 ESM 与 CJS 混合构建;
tsc编译产物从dist/移入lib/(对应lib/esm、lib/commonjs、lib/types三套产物,见 packages/web3-utils/package.json 的exports与build:cjs/build:esm/build:types脚本)。4.0.1-rc.1 还移除了对@ethereumjs/tx、@ethereumjs/common的依赖,4.3.3 将 TypeScript 从 4.x 升级到 5.x。
九、版本演进时间线速查
| 版本 | 关键变更摘要 |
|---|---|
| 4.0.1-alpha.1 | 新增 pollTillDefined、rejectIfTimeout、rejectIfConditionAtInterval |
| 4.0.1-alpha.2 | 新增 uuidV4、isPromise;JSON-RPC 响应 ID 改用 UUID 修复载荷混淆 |
| 4.0.1-rc.0 | compareBlockNumbers 支持 safe/finalized,移除 genesis;SocketProvider resolve 错误 |
| 4.0.1-rc.1 | 新增混合构建;格式化类型迁移至 web3-types |
| 4.0.1-rc.2 | numberToHex 增加 hexstrict;全包 Buffer → Uint8Array 迁移 |
| 4.0.3 | numberToHex 支持 BigInt 校验 |
| 4.0.6 | soliditySha3() 支持 BigInt |
| 4.0.7 | 自定义 EventEmitter;修复 BigInt 转 number 报错 |
| 4.1.0 | SocketProvider 队列管理 API 与 safeDisconnect;isContractInitOptions |
| 4.2.0 | 补回 AbiItem 类型导出 |
| 4.2.1 | 换用 eventemitter3 支持 React Native |
| 4.2.2 | 修复 toNumber 大数解析 |
| 4.2.3 | format 的 returnFormat 默认 DEFAULT_RETURN_FORMAT;修复 toHex/isUint8Array |
| 4.3.0 | toWei/fromWei 支持整数单位、精度警告、科学计数法 |
| 4.3.1 | _sendPendingRequests 捕获 socket 未处理错误 |
| 4.3.2 | 修复 padRight 大 uint 校验失败 |
| 4.3.3 | fromWei('0') 返回 "0";TypeScript 升级到 5.x |
十、最佳实践小结
- 大数一律用
string或bigint:toWei/fromWei在传入number且超过1e20或低于1e-15时会告警,务必用字符串承载金额,最终结果也是字符串。 - 优先使用
Uint8Array而非Buffer:4.0.1-rc.2 起所有字节 API 统一为Uint8Array,跨浏览器与 Node 行为一致。 - 请求 ID 冲突时用 UUID 或自增种子:默认
toPayload使用uuidV4()生成唯一 ID;需要可预测 ID 时调用setRequestIdStart(n)。 - 轮询/超时场景复用 promise_helpers:与其手写
setInterval+setTimeout组合,不如直接使用pollTillDefinedAndReturnIntervalId、waitWithTimeout、rejectIfTimeout等经过测试的基础件。 - 理解 DataFormat 决定返回值形态:
number、bigint、hex 字符串与 Uint8Array 的选择由FMT_NUMBER/FMT_BYTES组合决定,格式化细节见 packages/web3-utils/src/formatter.ts。 - Socket 场景善用
safeDisconnect:先确认请求队列为空再断开,避免在途请求响应丢失。
web3-utils 的价值在于"小而稳":每个函数都承担了明确的边界处理(大数精度、字节格式、类型推断、异步时序),而这些细节正是以太坊开发中最容易踩坑的地方。阅读 packages/web3-utils/CHANGELOG.md 与 packages/web3-utils/src 源码,是快速掌握这些边界条件的最佳途径。