用 Rust 从零实现通用连接池:状态残留比连接失效更麻烦
连接池看起来就是"建几条连接存起来,用的时候取一条"。但它有几个问题不在代码里,而在语义里。
最典型的一个:连接是有状态的。
上一任使用者可能留下了一个未提交的事务、一个未关闭的游标、一个改过的会话变量(SET timezone、SET search_path)。你拿到这条连接继续用,行为可能完全不符合预期。
这篇从零实现一个通用连接池,重点放在这些"不在直觉里"的地方。
先定义"资源"抽象
连接池不只能池化数据库连接——Redis 连接、gRPC channel、HTTP 客户端都可以。所以先抽出 trait:
pub trait Manage {
type Connection;
type Error: std::error::Error + Send + Sync + 'static;
/// 建立一条新连接
fn connect(&self) -> Result<Self::Connection, Self::Error>;
/// 取出前检查连接是否可用
fn is_valid(&self, conn: &mut Self::Connection) -> bool;
/// 归还时清理连接状态(回滚事务、重置会话变量)
fn reset(&self, conn: &mut Self::Connection) -> Result<(), Self::Error>;
/// 连接已经用了多久 / 空闲了多久
fn has_broken(&self, conn: &mut Self::Connection) -> bool {
!self.is_valid(conn)
}
}四个方法对应四个不同时机:
| 方法 | 调用时机 | 目的 |
|---|---|---|
connect |
池空时新建 | 建立连接 |
is_valid |
取出时 | 排除已被服务端关闭的连接 |
reset |
归还时 | 清理状态残留 |
has_broken |
取出/归还时 | 判断连接已经坏了 |
reset 是最容易被忽略、也最重要的一环。 后面单独讲。
池的配置
#[derive(Debug, Clone)]
pub struct PoolConfig {
/// 最大连接数
pub max_size: u32,
/// 最小空闲连接数(池会主动维持)
pub min_idle: u32,
/// 获取连接的最长等待时间
pub connection_timeout: std::time::Duration,
/// 空闲超过多久就关闭
pub idle_timeout: Option<std::time::Duration>,
/// 连接的总寿命上限(不管是否空闲)
pub max_lifetime: Option<std::time::Duration>,
/// 取出时是否检查有效性
pub test_on_checkout: bool,
}这几个参数各自解决的问题不同,缺一个都会有一类问题:
max_size:防止连接数无限增长打爆服务端min_idle:避免流量突增时大量新建连接(建连很慢)connection_timeout:池满时不能无限等idle_timeout:回收闲置连接,尤其服务端有wait_timeout时max_lifetime:防止长连接遇到内存泄漏、连接漂移(后端换主)等问题test_on_checkout:防止拿到已被服务端关闭的连接
max_lifetime 这条要展开说。 数据库连接长时间存活会积累问题:
1. 服务端内存泄漏(每个连接有自己的缓冲区)
2. 负载均衡漂移(连接建立后一直指向同一台后端,即使流量分布变了)
3. 数据库主从切换后,老连接仍指向旧主库
4. 服务端的 wait_timeout 到期,连接被静默关闭所以生产上的连接池必须有 max_lifetime,通常设 30 分钟到 1 小时。
连接池不只是"复用",还有一个同等重要的职责是"定期淘汰"。 一个只增不汰的池,最终一定会遇到上面这些问题。
池的内部结构
use std::collections::VecDeque;
use std::sync::{Condvar, Mutex};
use std::time::Instant;
pub struct Pool<M: Manage> {
manager: std::sync::Arc<M>,
config: PoolConfig,
state: Mutex<PoolState<M::Connection>>,
/// 有连接归还时唤醒等待者
available: Condvar,
/// 建连是慢操作,放在锁外做
connecting: Mutex<()>,
}
struct PoolState<C> {
/// 空闲连接
idle: VecDeque<IdleConn<C>>,
/// 当前已建连接总数(包括出借中的)
total: u32,
/// 已出借的连接数
in_use: u32,
/// 池是否已关闭
closed: bool,
}
struct IdleConn<C> {
conn: C,
/// 这条连接是什么时候建立的
created_at: Instant,
/// 上次被归还的时间
idle_since: Instant,
}注意 total 和 in_use 分开记。 只有 total < max_size 时才允许新建;只有 in_use 才能判断"池是否真的被占满"。
取出连接:完整的判断链条
pub struct PooledConnection<'a, M: Manage> {
pool: &'a Pool<M>,
conn: Option<M::Connection>,
/// 归还时如果需要,把连接丢弃
broken: bool,
}
impl<M: Manage> Pool<M> {
pub fn get(&self, timeout: std::time::Duration) -> Result<PooledConnection<'_, M>, PoolError> {
let deadline = Instant::now() + timeout;
loop {
// 1. 尝试从空闲列表拿一条
let mut state = self.state.lock().unwrap();
if state.closed {
return Err(PoolError::Closed);
}
while let Some(mut idle) = state.idle.pop_front() {
state.in_use += 1;
drop(state); // 先释放锁再检查!检查可能很慢
// 2. 检查寿命
if self.is_expired(&idle) {
self.discard(idle);
state = self.state.lock().unwrap();
continue;
}
// 3. 检查是否已被服务端关闭
if self.config.test_on_checkout && !self.manager.is_valid(&mut idle.conn) {
self.discard(idle);
state = self.state.lock().unwrap();
continue;
}
return Ok(PooledConnection {
pool: self,
conn: Some(idle.conn),
broken: false,
});
}
// 4. 空闲列表空了,看能不能新建
if state.total < self.config.max_size {
state.total += 1;
state.in_use += 1;
drop(state); // 建连是慢操作,不能持锁
match self.manager.connect() {
Ok(conn) => {
return Ok(PooledConnection {
pool: self,
conn: Some(conn),
broken: false,
});
}
Err(e) => {
// 建连失败,把计数还回去
let mut state = self.state.lock().unwrap();
state.total -= 1;
state.in_use -= 1;
self.available.notify_one();
return Err(PoolError::Connect(e.to_string()));
}
}
}
// 5. 池满了,等别人归还
let now = Instant::now();
if now >= deadline {
return Err(PoolError::Timeout);
}
let (s, _) = self
.available
.wait_timeout(state, deadline - now)
.unwrap();
drop(s);
}
}这段代码里有两处"必须先释放锁"的地方,都不是可选的:
is_valid之前要drop(state)。 有效性检查通常要发一次网络往返(比如SELECT 1),持锁做这个会让整个池卡住。connect之前要drop(state)。 建连可能要几百毫秒,持锁会让所有线程排队。
但有一个细节要注意:第 4 步里"先 total += 1 再释放锁",是必须的。否则两个线程可能同时判断 total < max_size 都成立,各自去建连,最终连接数超过上限。
// 正确:先在锁内占坑
state.total += 1;
drop(state);
// 再去建连连接池里最常见的并发 bug,就是"先判后做"没有在锁内完成。 判断和占位必须在同一个临界区,耗时的实际操作在锁外。
归还:这里才是真正的难点
impl<'a, M: Manage> Drop for PooledConnection<'a, M> {
fn drop(&mut self) {
let mut conn = match self.conn.take() {
Some(c) => c,
None => return,
};
// 1. 如果标记为坏了,直接丢弃
if self.broken {
self.pool.discard_raw(conn);
return;
}
// 2. 检查连接是否还能用(归还时再查一次)
if self.pool.manager.has_broken(&mut conn) {
self.pool.discard_raw(conn);
return;
}
// 3. 关键:清理状态残留
if let Err(_) = self.pool.manager.reset(&mut conn) {
// reset 失败说明连接状态不可信,丢弃
self.pool.discard_raw(conn);
return;
}
// 4. 检查是否超过寿命
// ...
// 5. 放回空闲列表
let mut state = self.pool.state.lock().unwrap();
state.in_use -= 1;
if state.closed {
state.total -= 1;
drop(state);
drop(conn);
return;
}
state.idle.push_back(IdleConn {
conn,
created_at: self.created_at,
idle_since: Instant::now(),
});
self.pool.available.notify_one();
}
}reset 到底要做什么
这是全文最想强调的部分。一个数据库连接的 reset 至少包括:
impl Manage for PostgresManager {
fn reset(&self, conn: &mut PgConnection) -> Result<(), Self::Error> {
// 1. 回滚任何未提交的事务
// 否则下一任使用者会"继承"一个打开的事务
conn.execute("ROLLBACK")?;
// 2. 重置会话级参数
// SET 命令的影响范围是整个会话,不会随事务回滚
conn.execute("RESET ALL")?;
// 3. 清空会话级临时表
conn.execute("DISCARD TEMP")?;
// 4. 释放咨询锁(如果有)
conn.execute("SELECT pg_advisory_unlock_all()")?;
// 5. 清空 prepared statements 缓存(可选,看场景)
// conn.execute("DEALLOCATE ALL")?;
Ok(())
}
}每一项都对应一类真实的事故:
| 未清理的状态 | 后果 |
|---|---|
| 未提交事务 | 下一任使用者的操作被卷进别人的事务里 |
| 会话变量(SET) | 时区、搜索路径、隔离级别被静默改变 |
| 临时表 | 名字冲突,或者读到上一任的脏数据 |
| 咨询锁 | 锁被永久占住,别的业务卡死 |
| 游标 | 占用服务端资源 |
其中最阴险的是"未提交事务"。 想象一下:
线程 A: BEGIN; UPDATE accounts SET balance = 0 WHERE id = 1; (忘记 COMMIT)
线程 A: 归还连接到池
线程 B: 从池取出同一连接
线程 B: SELECT balance FROM accounts WHERE id = 1; -> 读到 0
线程 B: 提交自己的事务 -> 把 A 的 UPDATE 一起提交了!这就是"连接池 + 忘记回滚"导致数据错乱的经典路径。 它不会报错,只会让数据静默地变错。
连接池必须假设"使用者可能在任意状态下归还连接",并在归还时把连接恢复到干净状态。 这不是可选的优化,是正确性要求。
为什么 reset 失败要丢弃连接
reset 里有任何一步失败,就意味着你无法确认这条连接的状态。回滚可能失败了,会话变量可能没重置干净。
这时候唯一安全的做法是关掉连接,重新建一条。 保留它只会让不确定性传播给下一任使用者。
后台维护任务
min_idle、idle_timeout、max_lifetime 这几个配置需要有人主动执行——连接池得有个后台线程定期干活:
impl<M: Manage> Pool<M> {
pub fn spawn_maintenance(self: std::sync::Arc<Self>) -> std::thread::JoinHandle<()> {
std::thread::spawn(move || {
loop {
std::thread::sleep(std::time::Duration::from_secs(30));
if self.state.lock().unwrap().closed {
break;
}
self.reap_idle(); // 回收超时空闲连接
self.reap_expired(); // 回收超寿命连接
self.fill_min_idle(); // 补足最小空闲数
}
})
}
fn reap_idle(&self) {
let Some(idle_timeout) = self.config.idle_timeout else { return };
let mut state = self.state.lock().unwrap();
let now = Instant::now();
// 从队首开始(它们是最早归还的,也最可能超时)
while let Some(front) = state.idle.front() {
if now.duration_since(front.idle_since) <= idle_timeout {
break;
}
// 注意:要保证回收后 total 不低于 min_idle
if state.total <= self.config.min_idle {
break;
}
let conn = state.idle.pop_front().unwrap();
state.total -= 1;
drop(state);
drop(conn.conn);
state = self.state.lock().unwrap();
}
}
}注意那个"保证 total 不低于 min_idle"的判断。 回收是为了省资源,但把池清空之后,下一个请求要等一次完整的建连(可能几百毫秒)。min_idle 的意义就是"随时有热的连接可用"。
还有一个小优化值得提:reap_idle 从队首开始检查。因为空闲列表是 FIFO 的,队首的连接空闲时间最长。这样可以在遇到第一个未超时的连接时立刻停止,不用遍历全部。
两个容易忽略的边界
1. 池关闭时要等待出借的连接归还。
pub fn close(&self) {
let mut state = self.state.lock().unwrap();
state.closed = true;
// 唤醒所有等待者,让它们拿到 Closed 错误
self.available.notify_all();
// 关闭所有空闲连接
for idle in state.idle.drain(..) {
drop(idle.conn);
}
}但如果还有连接在出借中(in_use > 0),它们会在归还时才真正被关闭。 这就是为什么 Drop 里要检查 state.closed——关闭是一个"渐进"的过程,不是一次性的。
进程退出时也要注意这个问题:如果主线程直接退出,出借中的连接不会被优雅关闭,服务端会看到一批"异常断开"。生产上应该在退出前等待几秒,或者显式 close。
2. PooledConnection 一定要实现 Deref 和 DerefMut。
impl<'a, M: Manage> std::ops::Deref for PooledConnection<'a, M> {
type Target = M::Connection;
fn deref(&self) -> &Self::Target {
self.conn.as_ref().expect("connection already returned")
}
}
impl<'a, M: Manage> std::ops::DerefMut for PooledConnection<'a, M> {
fn deref_mut(&mut self) -> &mut Self::Target {
self.conn.as_mut().expect("connection already returned")
}
}有了它,使用者完全感受不到"这是个池化的连接":
let mut conn = pool.get(timeout)?;
let rows = conn.query("SELECT 1")?; // 直接当普通连接用
// 出了作用域,自动归还这也是 RAII 在线程池那篇的同一个套路:把所有"容易忘的事"绑到析构函数上。
结论
一个能在生产用的连接池,要做的不只是"存取连接":
取出时检查有效性和寿命;建连必须在锁外但"占坑"必须在锁内;归还时重置会话状态(回滚、RESET、清临时表);reset 失败就丢弃;后台线程负责回收和补充;关闭是渐进的过程。
其中最重要的一条认识是:
连接池管理的是"有状态的共享资源",所以"归还时恢复干净"是正确性要求,而不是优化项。
理解了这一点,你再看 deadpool、r2d2、bb8 这些库的设计,会发现它们的 Manager trait 里那个看起来多余的 reset/recycle 方法,正是最有价值的一个。