区块链Web3【免费下载链接】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点击查看免费下载web3-providers-ws是 web3.js 4.x 仓库中专用于 WebSocket 协议的 provider 子包为通过ws:///wss://与 Ethereum 节点通信提供了基于 EIP-1193 规范、内置 JSON-RPC 请求队列与自动重连能力的连接层。本文将以该包的 README 为主线结合 源码 与测试用例完整讲解安装配置、WebSocketProvider构造函数参数、连接状态管理、鉴权方式、重连策略与订阅支持帮助你在实时场景事件订阅、推送通知中正确选用和调优该 provider。包定位web3.js 的 WebSocket 连接层web3-providers-ws是 web3.js 4.x 体系中的一个独立子包与web3-providers-http、web3-providers-ipc并列专门负责 WebSocket 协议的 provider 实现见 package.json 的描述 Websocket provider for Web3 4.x.x。它本身不直接依赖整个 web3.js 主包而是基于web3-types、web3-utils、web3-errors等底层库构建因此既可以作为 web3.js 内部的默认 WebSocket provider 使用也可以脱离主包独立安装、单独作为 EIP-1193 provider 接入。从依赖关系看package.json该包的核心运行时依赖包括ws^8.17.1与isomorphic-ws^5.0.0跨 Node.js / 浏览器环境的 WebSocket 实现isomorphic-ws在不同环境自动选择底层适配web3-types^1.7.0提供EthExecutionAPI、Web3APIPayload等类型定义web3-utils^4.3.1提供SocketProvider抽象基类、ReconnectOptions、isNullish等工具web3-errors^1.2.0提供ConnectionNotOpenError、InvalidClientError等错误类型。该包版本号当前为4.0.8要求 Node.js14、npm6.12.0并面向 ES2020 编译见 package.json。安装与运行环境使用 NPM 安装npm install web3-providers-ws使用 Yarn 安装yarn add web3-providers-ws两种安装方式等价。由于它是 web3.js monorepo 的子包如果是在整个仓库中开发调试也可以借助仓库根目录的 Lerna/Yarn Workspaces 机制在本地构建在包目录执行yarn build会同时构建 CJSlib/commonjs、ESMlib/esm与类型声明lib/types三套产物见 package.json。环境要求Node.js官方要求 LTS 版本README 标注为 Fermium即 Node 14.x 系列实际engines字段为14包管理器Yarn 或 npm6.12.0monorepo 场景下也可使用 Lerna目标协议连接地址必须是ws://或wss://开头的 URL。快速开始创建 WebSocketProvider最小示例import WebSocketProvider from web3-providers-ws; const provider new WebSocketProvider(ws://localhost:8545);WebSocketProvider的构造函数签名如下见 src/index.tsnew WebSocketProvider( socketPath: string, socketOptions?: ClientOptions | ClientRequestArgs, reconnectOptions?: PartialReconnectOptions, )socketPathWebSocket 地址必须是ws://或wss://前缀的合法 URLsocketOptions可选透传给底层ws客户端的选项如headers、handshakeTimeout等reconnectOptions可选重连策略配置autoReconnect、delay、maxAttempts。后两个参数都可省略。例如只传空对象或undefinedconst provider new WebSocketProvider(ws://localhost:8545, {}, { delay: 500, autoReconnect: true, maxAttempts: 10, });URL 校验构造函数会对socketPath做严格校验只有以ws://或wss://大小写不敏感开头的字符串才会被接受否则抛出InvalidClientError。该校验逻辑位于 src/index.tsprotected _validateProviderPath(providerUrl: string): boolean { return typeof providerUrl string ? /^ws(s)?:\/\//i.test(providerUrl) : false; }单元测试 test/unit/web_socket_provider.test.ts 与测试数据 test/fixtures/test_data.ts 验证了这一点合法示例ws://localhost:8545、ws://localhost、wss://foo.com、ws://foo.com:8545等非法示例htt://localhost:8545、http//localhost:8545、ipc://localhost:8545、空字符串、null、undefined、数字42等均会抛出Client URL ... is invalid.错误。注意ipc://前缀不属于本包职责IPC 连接应使用web3-providers-ipc。核心 API 与连接生命周期WebSocketProvider继承自web3-utils中的抽象基类SocketProvider见 web3-utils/src/socket_provider.ts后者又继承自 EIP-1193 provider。因此该 provider 天然具备以下能力单元测试 test/unit/web_socket_provider.test.ts 逐一验证了这些方法的存在API说明request(payload)发起 JSON-RPC 请求返回 PromisegetStatus()返回connecting/connected/disconnectedconnect()/disconnect(code?, data?)手动建立 / 关闭连接safeDisconnect(code?, data?, forceDisconnect?, ms?)等待请求队列清空后再断开forceDisconnecttrue时最多等待 5 次重试后强制清空reset()清空 pending / sent 请求队列并重置监听器supportsSubscriptions()恒返回true表示支持订阅on / once / removeListener / removeAllListeners事件监听connect、disconnect、message、error等getPendingRequestQueueSize()/getSentRequestsQueueSize()查看请求队列大小SocketConnection暴露底层 WebSocket 实例连接状态机getStatus()的实现直接映射底层 WebSocket 的readyState见 src/index.tsCONNECTING→ 返回connectingOPEN→ 返回connected其他如CLOSING、CLOSED→ 返回disconnected。集成测试 test/integration/web_socket_provider_integration.test.ts 完整覆盖了三种状态的流转新建即connecting连接建立后connected调用disconnect()后disconnected。请求与响应处理request()是核心调用入口其逻辑位于基类 socket_provider.ts若连接已断开自动重新connect()若请求 ID 缺失抛出Web3WSProviderError(Request Id not defined)若同一 ID 已存在于_sentRequestsQueue抛出RequestAlreadySentError为每个请求创建Web3DeferredPromise并封装为SocketRequestItem连接尚未建立connecting时请求进入_pendingRequestsQueue待open事件触发后由_sendPendingRequests()统一补发见 socket_provider.ts连接就绪时直接通过_sendToSocket发送——底层实现为this._socketConnection?.send(JSON.stringify(payload))见 src/index.ts并在此前检查连接状态断开时抛出ConnectionNotOpenError。收到消息时_parseResponses会借助ChunkResponseParser解析可能被分块chunked返回的响应并按请求 ID 从_sentRequestsQueue中匹配、resolve 对应的 deferred promise若响应是*_subscription类型的通知则作为message事件向外抛出见 socket_provider.ts。集成测试 test/integration/web_socket_provider_integration.test.ts 验证了在同一连接上并发发送多个请求eth_getBalance、eth_mining、eth_hashrate并正确按 ID 取回响应。socketOptions连接选项与鉴权第二个构造参数socketOptions会被原样透传给isomorphic-ws的 WebSocket 客户端见 src/index.tsprotected _openSocketConnection() { this._socketConnection new WebSocket( this._socketPath, undefined, this._socketOptions Object.keys(this._socketOptions).length 0 ? undefined : this._socketOptions, ); }注意当传入的是空对象时会转为undefined再透传避免干扰底层客户端默认行为。常见选项示例const provider new WebSocketProvider(wss://node.example.com, { headers: { // 若节点要求 API Key 放在请求头中例如 x-api-key: Api key, }, handshakeTimeout: 1500, // 握手超时毫秒 followRedirects: true, // 跟随重定向 maxRedirects: 3, // 最大重定向次数 perMessageDeflate: true, // 启用消息压缩 });测试数据 test/fixtures/test_data.ts 中的wsProviderOptions给出了followRedirects、handshakeTimeout、maxRedirects、perMessageDeflate等可配置项单元测试 test/unit/web_socket_provider.test.ts 验证了携带这些选项实例化不会抛错。通过 headers 实现鉴权最常见的鉴权场景是把凭证放进headers。以 Basic Auth 为例集成测试 test/integration/basic_auth.test.ts 展示了一个校验流程服务端检查Authorization头是否包含Basic前缀否则销毁连接。与之对应的客户端侧配置即const credentials Buffer.from(username:password).toString(base64); const provider new WebSocketProvider(ws://localhost:3000, { headers: { Authorization: Basic ${credentials}, }, });同理对于使用 API Key 的商业节点如 QuickNode、Infura 等可将密钥放入headers中的自定义字段如x-api-key与源码注释中的示例一致见 src/index.ts。reconnectOptions自动重连策略第三个构造参数控制断线重连行为。ReconnectOptions类型与默认值定义在 web3-utils/src/socket_provider.tsexport type ReconnectOptions { autoReconnect: boolean; delay: number; maxAttempts: number; }; const DEFAULT_RECONNECTION_OPTIONS { autoReconnect: true, delay: 5000, maxAttempts: 5, };参数默认值说明autoReconnecttrue是否在异常断开后自动重连delay5000每次重连尝试前的等待时间毫秒maxAttempts5最大重连尝试次数构造函数会通过展开运算符将用户配置合并到默认值之上见 socket_provider.ts因此可只传部分字段。集成测试 test/integration/reconnection.test.ts 验证了默认值确实为{ autoReconnect: true, delay: 5000, maxAttempts: 5 }。重连触发条件重连逻辑在_onCloseEvent中判断见 src/index.tsif ( this._reconnectOptions.autoReconnect (![1000, 1001].includes(event.code) || !event.wasClean) ) { this._reconnect(); return; }即当自动重连开启且关闭码不是正常的 1000正常关闭或 1001服务端下线或关闭并非干净wasClean为 false时触发重连。正常关闭如调用disconnect()则走清理队列、移除监听器、派发disconnect事件的流程。_reconnect()的实现见 socket_provider.ts会拒绝所有_sentRequestsQueue中的请求并抛出PendingRequestsOnReconnectingError在delay毫秒后重新connect()若重连次数达到maxAttempts上限则清空队列并抛出MaxAttemptsReachedOnReconnectingError。重连配置示例const provider new WebSocketProvider( ws://localhost:8545, {}, { delay: 500, // 每 500ms 尝试一次 autoReconnect: true, maxAttempts: 10, // 最多尝试 10 次 }, );需要快速失败例如测试或容错场景时可显式关闭重连如集成测试中常用的{ delay: 1, autoReconnect: false, maxAttempts: 1 }见 test/integration/web_socket_provider_integration.test.ts与此相对test/integration/reconnection.test.ts 使用{ delay: 500, autoReconnect: true, maxAttempts: 100 }验证长时间重连场景。事件订阅实时推送的基础由于 WebSocket 是双向通道该 provider 支持 JSON-RPC 订阅eth_subscribe/eth_unsubscribe。supportsSubscriptions()恒返回true见 socket_provider.ts单元测试也对此做了断言见 test/unit/web_socket_provider.test.ts。订阅推送的消息会以*_subscription结尾的方法名被识别为通知通过message事件向外派发。监听方式provider.on(message, (result) { console.log(收到订阅推送:, result); });其他可用事件包括connect连接建立成功对应open事件见 socket_provider.tsdisconnect连接关闭回调参数为ProviderRpcError含code与reasonerror底层 WebSocket 出错或请求失败时派发见 socket_provider.ts。集成测试 test/integration/web_socket_provider_integration.test.ts 完整覆盖了message、error、connect、disconnect四个事件的订阅并验证了连接未建立时调用request()会抛出Connection not open错误。与 web3.js 主包集成web3-providers-ws不仅可独立使用也是 web3.js 4.x 主包中eth模块默认使用的 WebSocket provider。你可以直接在Web3实例上指定import Web3 from web3; import WebSocketProvider from web3-providers-ws; const provider new WebSocketProvider(wss://node.example.com, { headers: { x-api-key: Api key }, }); const web3 new Web3(provider); // 之后即可使用 web3.eth.getBlockNumber()、web3.eth.subscribe(...) 等 API这样既能复用 provider 的自动重连与请求队列又能借助主包获得合约、交易、订阅等完整 API。包内常用脚本开发本包时可使用 package.json 中定义的脚本Script说明clean使用rimraf删除dist/与lib/build使用tsc构建本包及其依赖包CJS/ESM/类型三套产物lint使用eslint检查代码lint:fix使用eslint检查并自动修复format使用prettier格式化代码test运行单元测试jest配置见test/unit/jest.config.jstest:integration运行test/integration下的集成测试需连接真实节点测试中通过getSystemTestProviderUrl()获取test:unit仅运行单元测试单元测试在test/unit下mock 了isomorphic-ws集成测试在test/integration下依赖真实 WebSocket 节点并通过describeIf(isWs)条件执行源码入口为 src/index.ts默认导出WebSocketProvider。小结web3-providers-ws为 web3.js 4.x 提供了开箱即用的 WebSocket 连接能力通过new WebSocketProvider(url, socketOptions?, reconnectOptions?)三参数构造即可完成连接、鉴权与重连策略配置其基于 EIP-1193 的SocketProvider基类封装了请求队列、分块响应解析、自动重连与订阅分发适合事件监听、实时推送等场景。在使用时请重点根据节点要求配置headers鉴权、按网络稳定性调优reconnectOptions重连间隔与次数上限并善用connect/disconnect/message/error事件掌握连接生命周期。赞分享区块链Web3【免费下载链接】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点击查看免费下载相关推荐终极web3.py Provider配置指南HTTP、IPC和WebSocket连接详解终极web3.py Provider配置指南HTTP、IPC和WebSocket连接详解 web3.py是Python开发者与以太坊区块链交互的首选工具而PWeb3区块链Web3.js Provider 事件监听指南EIP-1193 事件模型与 WebSocket/IPC 底层连接实战Web3.js Provider 事件监听指南EIP 1193 事件模型与 WebSocket/IPC 底层连接实战 部分 Provider如 WebSoc区块链Web3Web3.js Providers 完全指南HTTP、WebSocket、IPC 与 EIP-1193 注入式 Provider 的初始化与配置Web3.js Providers 完全指南HTTP、WebSocket、IPC 与 EIP 1193 注入式 Provider 的初始化与配置 导读 在 w区块链Web3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考