undici PoolStats 指南：深入理解连接池与请求计数器快照

后端网络通信【免费下载链接】undiciAn HTTP/1.1 client, written from scratch for Node.js项目地址https://gitcode.com/gh_mirrors/un/undici点击查看免费下载PoolStats是 undici 提供的只读快照对象用于在任意时刻查看Pool或BalancedPool的聚合连接数与请求计数器。本文以 PoolStats.md 文档为主体结合仓库源码讲解其快照语义、六个核心属性的真实含义、底层聚合实现以及用 TypeScript 类型与测试用例验证各属性的实际行为帮助你掌握连接池的运行时观测与调优能力。概述PoolStats是什么PoolStats暴露了某个Pool或BalancedPool的聚合连接与请求计数器的一个只读快照。它自 v4.15.0 引入类型为 module状态标记为Stability: 2 - Stable稳定。文档明确强调了两点关键语义惰性创建实例在每次访问pool.statsgetter 时被惰性创建因此其中保存的值反映的是访问那一刻连接池的状态快照特性实例是一次性快照不会随连接池后续变化而更新想要观察后续变化需要再次读取pool.stats。在正常使用中你不需要直接构造PoolStats而是通过 pool 的stats属性获取实例import { Pool } from undici const pool new Pool(http://localhost:3000) const { stats } pool console.log(stats.connected, stats.running, stats.size)类PoolStats每个属性都是一个普通的 number在实例创建时根据连接池内部状态计算得出。由于实例是快照若需持续观测应周期性重新读取pool.stats。new PoolStats(pool)pool{Pool|BalancedPool}要读取计数器的池对象。该构造函数从pool的当前状态创建新的PoolStats实例。不过文档建议优先使用pool.statsgetter——它在每次访问时都会返回一个全新的PoolStats。在源码 lib/util/stats.js 中可以看到PoolStats的实际实现它读取的是 pool 内部通过符号键symbol key暴露的状态class PoolStats { constructor (pool) { this.connected pool[kConnected] this.free pool[kFree] this.pending pool[kPending] this.queued pool[kQueued] this.running pool[kRunning] this.size pool[kSize] } }对应地PoolBase在 lib/dispatcher/pool-base.js 中通过 getter 返回新实例get stats () { return new PoolStats(this) }poolStats.connected类型{number}该池中打开的 socket 连接数。注意在 lib/dispatcher/pool-base.js 中它是遍历池内所有 client 的kConnected求和得到的聚合值get [kConnected] () { let ret 0 for (const { [kConnected]: connected } of this[kClients]) { ret connected } return ret }而单个 client 的kConnected定义在 lib/dispatcher/client.js只有当 HTTP 上下文存在、未处于连接中且未被销毁时才为真值。poolStats.free类型{number}该池中打开但当前没有活动请求的 socket 连接数。源码实现lib/dispatcher/pool-base.js中free统计的是「已连接且不需要排空not needDrain」的连接数get [kFree] () { let ret 0 for (const { [kConnected]: connected, [kNeedDrain]: needDrain } of this[kClients]) { ret connected !needDrain } return ret }poolStats.pending类型{number}该池中所有 client 的待处理请求数。这里的pending是「已进入池内队列但尚未被实际执行」的请求。从 lib/dispatcher/pool-base.js 的实现可以看出它等于池内队列长度kQueued加上所有 client 的kPending之和get [kPending] () { let ret this[kQueued] for (const { [kPending]: pending } of this[kClients]) { ret pending } return ret }poolStats.queued类型{number}该池中所有 client 的排队请求数。它对应 PoolBase 内部的kQueued计数器lib/dispatcher/pool-base.js当所有 dispatcher 都处于忙状态kNeedDrain时新请求会被压入FixedQueue并递增kQueued等待某个 client 排空后从队列中取出见 kDispatch 实现 与 kOnDrain。poolStats.running类型{number}该池中所有 client 的当前活动请求数。同样是遍历聚合的结果lib/dispatcher/pool-base.js每个 client 的kRunning为其「已派发但尚未完成的请求」数量。poolStats.size类型{number}该池中所有 client 的活动、待处理或排队请求总数。从 lib/dispatcher/pool-base.js 看它等于kQueued加上所有 client 的kSize之和是反映池中「在途请求总量」的综合指标get [kSize] () { let ret this[kQueued] for (const { [kSize]: size } of this[kClients]) { ret size } return ret }与 ClientStats 的区别free 与 queued 是池级指标undici 的Client也有自己的statsgetter但返回的是ClientStats而非PoolStats。两者在 lib/util/stats.js 中并列实现class ClientStats { constructor (client) { this.connected client[kConnected] this.pending client[kPending] this.running client[kRunning] this.size client[kSize] } }对比可见ClientStats只有connected、pending、running、size四个属性free空闲连接与queued池级排队请求是Pool/BalancedPool 专属指标因为队列和空闲判定是连接池层级的调度行为单个 client 无法独立表达。通过Agent获取聚合统计v7.9.0 起对应 PR 4157Pool 和 Client 的统计信息通过Agent暴露。在 lib/dispatcher/agent.js 中Agent的statsgetter 会遍历其管理的所有 dispatcher并按 origin 组织成一个普通对象get stats () { const allClientStats {} for (const dispatcher of this[kClients].values()) { if (dispatcher.stats) { allClientStats[dispatcher[kUrl].origin] dispatcher.stats } } return allClientStats }因此使用Agent时agent.stats的形态是Recordstring, ClientStats | PoolStats见 types/agent.d.ts每个 key 是 dispatcher 的 originvalue 是PoolStats或ClientStats实例便于按域名维度观测流量分布。TypeScript 类型定义undici 为PoolStats提供了完整的类型声明types/pool-stats.d.ts六个属性均为numberdeclare class PoolStats { constructor (pool: Pool) connected: number free: number pending: number queued: number running: number size: number }Pool、RoundRobinPool与Agent的.d.ts中分别以TPoolStats引用了该类型见 types/pool.d.ts、types/round-robin-pool.d.ts确保 TypeScript 用户在访问pool.stats时获得类型安全提示。测试用例验证各属性在真实请求中的行为仓库测试用例test/pool.js用真实请求验证了各计数器的取值逻辑。当一个请求正被处理连接已建立、请求在途时断言如下t.strictEqual(client.stats.connected, 1) t.strictEqual(client.stats.free, 0) t.strictEqual(client.stats.pending, 0) t.strictEqual(client.stats.queued, 0) t.strictEqual(client.stats.running, 1) t.strictEqual(client.stats.size, 1)对应关系一目了然连接建立 →connected 1请求在途 →running 1free 0没有空闲连接请求既不在池队列也不在 client 队列 →pending 0、queued 0在途请求总数 →size 1。另有并发场景的断言test/pool.js展示了排队时的状态当请求数超过连接数时queued max(n - connections, 0)pending nsize n而 test/pool.js 中pool.stats.queued 1验证了「第二个连接正在建立时请求停留在池队列中」的行为。test/round-robin-pool.js 则用pool.stats.connected 2验证了轮询池连接数的上限。实战用 PoolStats 观测连接池健康度综合文档与源码PoolStats最典型的应用场景是周期采样连接池状态从而判断是否需要扩容连接、限流或排查连接泄漏import { Pool } from undici const pool new Pool(http://localhost:3000, { connections: 10 }) setInterval(() { const s pool.stats console.log({ connected: s.connected, // 已打开 socket 数 free: s.free, // 空闲 socket 数接近 0 说明连接吃紧 pending: s.pending, // 待处理请求数 queued: s.queued, // 池队列中排队的请求数 running: s.running, // 活动请求数 size: s.size // 在途请求总量 }) }, 1000)解读要点size connections且queued持续增长连接池已满请求开始排队可考虑提高connections或增加实例free长期为 0 而running居高不下连接利用率接近饱和connected明显低于预期但pending很大可能处于连接建立阶段或存在连接建立瓶颈所有计数器在空闲时应回归 0或仅有 keep-alive 连接使connected 0、free connected否则可能存在请求未释放的问题。由于pool.stats每次访问都会创建新快照务必在同一时刻一次性读取各属性如上面的示例避免在多次访问之间状态变化导致读数不一致。赞分享后端网络通信【免费下载链接】undiciAn HTTP/1.1 client, written from scratch for Node.js项目地址https://gitcode.com/gh_mirrors/un/undici点击查看免费下载相关推荐深入理解aiohttp客户端异步请求处理与连接池优化指南深入理解aiohttp客户端异步请求处理与连接池优化指南 aiohttp是一个强大的异步HTTP客户端/服务器框架专为Python asyncio设计。作为后端Web框架WebSocket3个实用技巧快速上手LibreSprite像素艺术创作3个实用技巧快速上手LibreSprite像素艺术创作 还在为像素动画的复杂流程头疼吗别担心今天我要分享的LibreSprite能让你轻松开启像素艺术创作桌面应用游戏开发图形学Undici连接池智能扩缩容基于请求队列的终极性能优化指南Undici连接池智能扩缩容基于请求队列的终极性能优化指南 Undici作为Node.js生态中从零构建的HTTP/1.1客户端其连接池机制是实现高性能网络后端网络通信上一篇PortMaster进阶技巧手动安装游戏移植包与版本更新完全指南下一篇通道剪枝优化Demucs从原理到实现的完整实验指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考