返回文章列表

用 Rust 从零实现通用连接池:状态残留比连接失效更麻烦

551 字·5 分钟阅读
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);
        }
    }

这段代码里有两处"必须先释放锁"的地方,都不是可选的:

  1. is_valid 之前要 drop(state)。 有效性检查通常要发一次网络往返(比如 SELECT 1),持锁做这个会让整个池卡住。
  2. 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 方法,正是最有价值的一个。