web3.js 数据校验利器 web3-validator从 Eth ABI 类型到 JSON Schema 的完整验证方案【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.jsweb3-validator 是 web3.js 4.x 生态中负责对象与数据校验的子包它将 Ethereum ABI 类型体系与 JSON-Schema-Draft07 规范融合为合约调用参数、交易字段、RPC 返回值等场景提供统一且可扩展的验证能力。读完本文你将掌握 validator 的核心用法含静默模式与错误对象、完整支持的类型清单、ETH 类型到 JSON Schema 的转换机制以及如何在uint、bytes、tuple、address等场景下写出可复用的校验 Schema。包定位与安装web3-validator是 web3.js 的官方子包之一仓库路径 packages/web3-validator当前版本 2.0.6它只负责校验对象这一件事不依赖 web3 主包即可独立使用。其描述为 JSON-Schema compatible validator for web3即一个与 JSON Schema 兼容的、面向 web3 数据形态的校验器。按 package.json 的声明它同时提供 CommonJSlib/commonjs、ESMlib/esm与类型声明lib/types三种产物Node.js 版本要求14npm 版本要求6.12.0。安装命令使用 NPMnpm install web3-validator使用 Yarnyarn add web3-validator该包自身的依赖包括zod校验引擎核心、ethereum-cryptography、web3-errors与web3-types见 package.json这些依赖会随包自动安装。快速上手validator.validate 的两种模式从入口文件 src/index.ts 可以看到包默认导出了web3_validator.js、default_validator.js、types.js、utils.js、errors.js、constants.js以及validation/index.js。其中最常用的就是默认实例validator它定义在 src/default_validator.tsexport const validator new Web3Validator();也就是说你导入的validator是一个Web3Validator实例它的validate方法定义在 src/web3_validator.ts签名如下validate( schema: ValidationSchemaInput, data: ReadonlyArrayunknown, options: Web3ValidationOptions { silent: false }, ): Web3ValidationErrorObject[] | undefined标准用法校验失败即抛错import { validator } from web3-validator; // 校验通过静默返回 undefined validator.validate([uint8, string], [2, my-string]); // 校验失败抛出 Web3ValidatorError validator.validate([uint8, string], [300, my-string]);静默模式收集错误而非抛出传入{ silent: true }后校验失败不会抛出异常而是返回Web3ValidationErrorObject[]错误数组方便上层自行处理import { validator } from web3-validator; const errors validator.validate([uint8, string], [300, my-string], { silent: true }); console.log(errors);关于silent选项的默认值可参考 src/web3_validator.ts 中的options: Web3ValidationOptions { silent: false }默认非静默、直接抛错。错误对象与异常结构非静默模式下抛出的Web3ValidatorError定义在 src/errors.ts它继承自web3-errors的BaseWeb3Error并固定使用错误码ERR_VALIDATION。其 message 形如Web3 validator found 1 error[s]: value 300 at /0 must pass uint validation而silent: true返回的错误对象是Web3ValidationErrorObject[]每个对象包含keyword、instancePath、schemaPath、params、message五个字段转换逻辑见 src/validator.ts与 JSON Schema 校验错误的表达习惯一致。支持的 Ethereum 数据类型一览README 用一张表概括了web3-validator支持校验的 ETH 类型。下表在此基础上补充了实现细节底层 format 定义见 src/formats.tsType可接受的输入形式说明uintnumber、string、HexString无符号整数支持所有 EVM 变体如uint8、uint256支持数组限定符uint[]、uint[2]intnumber、string、HexString有符号整数支持所有 EVM 变体如int8、int256支持数组限定符int[]、int[2]bytesHexString、Uint8Array原始字节支持定长字节如bytes32stringstring字符串值addressstring、HexString以太坊网络兼容地址bloomstring、HexString校验给定字符串是否为以太坊 Bloom 过滤器tuplearray可指定任意嵌套数组形式的元组如[uint, string]自定义元组或数组元组用[tuple[3], [uint, string]]语法需要说明的是上表中bytes行的 fixed length bytes asbytes[2] 属于 README 原文描述实际语义上应理解为定长字节类型bytes1~bytes32代码中 formats.ts 通过循环为bytes1到bytes32生成了对应格式并将bytes256映射回通用bytes。除此之外src/constants.ts 定义了完整的 ETH 基础类型集合export const VALID_ETH_BASE_TYPES [bool, int, uint, bytes, string, address, tuple];注意这里还包含了bool。同时src/types.ts 定义了扩展类型hex、number、blockNumber、blockNumberOrTag、filter、bloom这些类型同样可以在 schema 中使用并对应 formats.ts 中的isHexStrict、isNumber、isBlockNumber、isBlockNumberOrTag、isFilterObject、isBloom等底层校验函数。数值按数组传参的约定对于 Ethereum 兼容数据值必须以数组形式传入。例如 schema[uint, string]对应的值应为[2, my-string]。这是因为在Web3Validator.validate中schema 会被转换为一个type: array的 JSON Schemadata的每个元素按位置与 schema 的每一项对应见 src/utils.ts。类型的解析规则parseBaseType见 src/utils.ts负责把uint256、int8、bytes32[2]这类类型字符串拆解为baseType、baseTypeSize、arraySizes与isArray先用空格清洗类型字符串若包含[则提取数组下标无数字下标解析为-1即不定长数组若命中VALID_ETH_BASE_TYPES直接返回基础类型否则尝试解析int/uint/bytes前缀后的位数。convertEthTypesrc/utils.ts随后将 ETH 类型映射为{ format, required }例如uint256→format: uint256, required: true。值得注意的是它不允许在同一个 schema 项中同时出现eth关键字与type字段否则会抛出Web3ValidatorError。三种 Schema 写法短格式、完整 ABI 与 JSON Schema1. 短格式ShortValidationSchema直接用类型字符串数组描述参数列表validator.validate([uint8, string, address], [8, hello, 0x...]);嵌套元组也可用数组表示例如[[uint, string]]。2. 完整 ABI 参数格式FullValidationSchema当需要携带字段名时可直接传完整的 ABI 参数对象数组const schema [ { name: owner, type: address }, { name: amount, type: uint256 }, ]; validator.validate(schema, [0xCB00CDE33a7a0Fba30C63745534F1f7Ae607076b, 1000]);该能力基于FullValidationSchema ReadonlyArrayAbiParameter类型定义见 src/types.ts。从 test/fixtures/abi_to_json_schema.ts 的测试夹具可以看到两种写法的对应关系例如fullSchema: [{ name: a, type: uint }]与shortSchema: [uint]都会转换为包含format: uint、required: true的数组项 JSON Schema。3. 原生 JSON SchemaDraft-07 自定义eth关键字web3-validator的实现是 JSON-Schema-Draft07 的扩展增加了一个自定义关键字eth。因此你完全可以用标准的 JSON Schema 校验任意对象数据{ type: object, properties: { owner: { type: string }, amount: { type: number } }, required: [owner, amount] }底层 src/validator.ts 的convertToZod会把 JSON Schema 递归转换为 Zod schemaobjectpropertiesrequired生成z.object().partial().required(...)arrayitems生成z.array或z.tuple依据minItems/maxItems与$id判断oneOf生成z.unionformat则映射为z.any().refine(formats[schema.format])。这解释了为何 package.json 将zod列为运行时依赖。深入ETH Schema 到 JSON Schema 的转换机制当你调用validator.validate([uint8, string], data)时完整调用链是Web3Validator.validate收到 schema 后先调用ethAbiToJsonSchema(schema)src/utils.ts把 ETH 类型数组转换为 JSON SchemaabiSchemaToJsonSchemasrc/utils.ts构建一个type: array、minItems/maxItems等于参数个数的顶层 schema逐项解析 ABI 参数基础类型生成{ $id, format, required: true }带数组的类型如uint[2]生成type: array且minItems/maxItems固定为 2 的嵌套结构不定长数组下标为 -1则不设置长度约束tuple递归调用abiSchemaToJsonSchema生成嵌套数组 schema转换后的 JSON Schema 交给Validator.validate先convertToZod成 Zod schema再safeParse校验数据失败时由convertErrors把 Zod issue 翻译成 JSON Schema 风格的Web3ValidationErrorObject[]src/validator.ts。Web3Validator.validate还额外处理了一个边界当 schema 为空转换后 items 为空数组而数据非空时会抛出Web3ValidatorError错误信息为 empty schema against data can not be validated见 src/web3_validator.ts。预置校验工具与扩展类型除了validator实例包还导出了一系列可直接复用的校验函数通过 src/index.ts 的export * from ./validation/index.js源码位于 src/validation包括address.ts地址校验isAddressbloom.tsBloom 过滤器校验isBloomblock.ts区块号/区块标签校验isBlockNumber、isBlockTag、isBlockNumberOrTagboolean.ts、string.ts布尔与字符串校验bytes.ts字节数据校验isBytes支持定长与不定长numbers.ts数字校验isNumber、isInt、isUInt支持位宽约束filter.ts、topic.ts、abi.ts、eth.ts、object.ts过滤器对象、topic、ABI 参数、ETH 类型与对象结构校验这些函数同样通过validator.utils或直接导入使用例如import { isAddress, isHexStrict } from web3-validator; // 或 import { utils } from web3-validator;以isUInt/isInt为例它们支持{ bitSize }选项formats.ts 正是利用这一特性为 8 到 256 位步长 8的每个intN/uintN生成对应校验格式从而支撑uint8、uint256等全部 EVM 数值类型。进阶示例元组与数组类型校验定长数组// 期望两个 uint 组成的定长数组 validator.validate([uint[2]], [[1, 2]]); // 长度不符时报错需要 2 个元素 validator.validate([uint[2]], [[1]], { silent: true });不定长数组// 任意长度的 uint 数组 validator.validate([uint[]], [[1, 2, 3]]);元组 tuple// 元组第一个元素是 uint第二个是 string validator.validate([[uint, string]], [[1, a]]); // 自定义元组数组tuple[3] 表示三个元素每个元素都是 [uint, string] validator.validate([tuple[3], [uint, string]], [[[1, a], [2, b], [3, c]]]);元组的处理逻辑在 src/utils.tsbaseType tuple时会递归转换abiComponents数组元组还会根据首位arraySizes生成minItems/maxItems约束。更多示例abi_to_json_schema.ts测试夹具packages/web3-validator/test/fixtures/abi_to_json_schema.ts中包含了大量可参考的 schema 用例该文件共 1814 行覆盖uint、address、bytes、bool、tuple、嵌套数组、全量 ABI 参数等场景是学习 schema 写法的第一手资料。对应单元测试位于 packages/web3-validator/test/unit。工程实践与注意事项默认抛错静默收集默认silent: false会直接抛出Web3ValidatorError需要收集全部错误时使用{ silent: true }。数组传参约定ETH 类型 schema 的数据必须按位置以数组传入不能传对象。eth与type互斥同一 schema 项中不能同时使用自定义eth关键字与标准type字段见 src/utils.ts。类型覆盖全面基础类型bool/int/uint/bytes/string/address/tuple之外还支持hex、number、blockNumber、blockNumberOrTag、filter、bloom等扩展类型。定长与不定长bytes1~bytes32、int8~int256、uint8~uint256全部预置数组下标省略即不定长。相关资源包入口与导出packages/web3-validator/src/index.ts默认实例与高级封装packages/web3-validator/src/default_validator.ts、packages/web3-validator/src/web3_validator.ts核心校验引擎packages/web3-validator/src/validator.tsETH→JSON Schema 转换与工具函数packages/web3-validator/src/utils.ts格式与基础类型常量packages/web3-validator/src/formats.ts、packages/web3-validator/src/constants.ts错误类型packages/web3-validator/src/errors.ts示例与测试packages/web3-validator/test/fixtures/abi_to_json_schema.ts、packages/web3-validator/test/unit【免费下载链接】web3.jsCollection of comprehensive TypeScript libraries for Interaction with the Ethereum JSON RPC API and utility functions.项目地址: https://gitcode.com/gh_mirrors/we/web3.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考