在 Ruby 生态中，Faraday 是发起 HTTP 请求的流行中间件，它通过适配器模式可以切换不同的底层 HTTP 客户端。net-http-persistent 是一个基于标准库 Net::HTTP 的持久连接管理器，它会维护一个全局连接池，将已建立的 TCP 连接复用给同一主机的后续请求。然而，连接不会永远活跃，当应用进入低流量时段，池中就会出现大量空闲连接，这些连接不仅浪费本地端口和内存，还可能因为服务端主动关闭而导致下次请求时遇到 Broken pipe 错误。为此，net-http-persistent 提供了空闲超时修剪机制，允许开发者设定一个时间阈值，自动清理长时间未活动的连接。
net-http-persistent 连接池与修剪机制的原理
net-http-persistent 的连接池以主机（host:port）为键存储一组与远端服务器的复用连接。当发起请求时，它会从对应主机的连接队列中取出一个可用的连接，请求结束后再将其归还。每个连接对象都有一个 last_used 时间戳，记录最近一次完成读写操作的时间点。修剪操作的核心逻辑位于 Net::HTTP::Persistent#reconnect 或内部清理方法中，通过遍历所有主机下的连接，比较 last_used 与当前时间的差值，如果超过设定的空闲超时，就调用 finish 方法关闭连接并从池中移除。
这个修剪过程不是由一个独立的后台线程自动触发的。net-http-persistent 采用的是延迟修剪策略，即在每次建立新连接或归还连接时才会检查是否需要修剪。具体来说，当池中的连接总数超过 pool_size 限制，或者显式调用 reconnect 方法时，才会触发一次清理。因此，即使设置了 idle_timeout，如果应用持续有请求且连接数未超限，那些真正空闲的连接可能仍然占着位置，直到连接数触及池大小的天花板。
从源码角度看，idle_timeout 参数会最终赋值给 @idle_timeout 实例变量，并在 connection_for 或 reconnect 中参与修剪逻辑。当发现某个连接的空闲时长超过阈值时，连接对象会被标记为需要关闭，并被移出可用队列。使用这种方式，应用无需额外关心连接的生命周期，只要合理配置参数，就能在长连接复用和资源释放之间取得自动化的平衡。
在 Faraday 中配置 net-http-persistent 的空闲超时
Faraday 通过适配器将配置项透传给底层的连接管理器。对于 :net_http_persistent 适配器，可以在初始化连接时传入 :idle_timeout 以及连接池大小 :pool_size 等参数。这些参数会被直接用来构造 Net::HTTP::Persistent 实例，从而实现细粒度的连接管理。下面是一个典型的配置示例：
require 'faraday' require 'faraday/net_http_persistent' conn = Faraday.new(url: 'https://api.ipipp.com') do |f| f.adapter :net_http_persistent, pool_size: 10, idle_timeout: 30 end
上面的代码创建了一个最大容纳 10 个连接的连接池，并将空闲超时设为 30 秒。这意味着当一个连接在 30 秒内没有任何读写活动时，在下一次池清理周期中它就会被销毁。需要注意的是，idle_timeout 的单位是秒，也可以接受浮点数以支持更精细的控制。如果未设置该参数，net-http-persistent 默认不进行空闲超时修剪，连接会一直保留直到连接数达到 pool_size 上限并采用 LRU 策略淘汰旧连接。
在多线程环境下，Net::HTTP::Persistent 内部使用了互斥锁来保证连接池操作的线程安全性。因此，idle 超时修剪同样是在锁内完成的，不会出现并发检查与关闭导致的状态不一致。不过，如果你在 Sidekiq 或 Puma 等多进程模型中运行，每个进程都有自己的连接池，它们各自独立进行修剪。这时需要根据每个进程的实际并发量分别调整 pool_size 和 idle_timeout，避免出现某个进程的池过大或修剪过于频繁。
空闲超时对应用性能的影响与调优
合理设置空闲超时可以在资源占用和请求延迟之间找到一个平衡点。如果将 idle_timeout 设置得过短，比如 5 秒，那么在一次请求结束后，短暂的空闲就可能导致连接被关闭，下次请求又不得不重新建立 TCP 连接和 TLS 握手，这会显著增加延迟，完全抵消了持久连接带来的性能收益。相反，如果设置得过长，在流量低谷时池中会积累大量无用的连接，尤其是当应用需要与大量不同的外部服务通信时，可能耗尽本地端口资源。
实际调优时，可以先观察应用对外部服务的请求模式。对于频繁调用的关键 API，建议将空闲超时设置在 30～120 秒之间，这个范围能容忍短暂的请求间隔波动，又能及时释放长期不用的连接。同时，结合 pool_size 参数限制最大连接数量，形成双重保障。例如，将 pool_size 设置为 worker 线程数的 1.5 倍，空闲超时设为 60 秒，可以在高并发场景下既保证连接的复用率，又不会让池膨胀失控。
另一个容易被忽视的点是服务端的 Keep-Alive 超时策略。许多 Web 服务器（如 Nginx）都会主动关闭长时间空闲的 TCP 连接，默认值往往在 60～75 秒左右。如果客户端的空闲超时大于服务端的超时设置，那么连接可能会被服务端单方面断开，而客户端仍认为该连接可用。下次请求时就会遭遇 Errno::ECONNRESET 异常，需要额外进行重试。因此，建议将客户端的 idle_timeout 设置得比服务端略小，让客户端先主动关闭连接，避免被动错误。
除了闲置超时，net-http-persistent 还提供了 keep_alive 参数控制是否发送 HTTP Keep-Alive 头部，以及 max_requests 限制单个连接的请求次数。结合这些选项，可以实现更精细的连接生命周期管理。在高性能场景下，还可以通过监控连接池状态（如 conn.adapter.connection.connections 等内部方法）来动态调整参数，但需要谨慎操作以免破坏线程安全。总之，空闲超时修剪是管理持久连接资源的重要工具，理解其工作机制与限制，才能在生产环境中真正发挥长连接的优势。