4. 连接池状态监控：使用 DB.Stats() 获取连接池运行指标

连接池是数据库访问的“交通枢纽”，其健康状态直接决定应用吞吐量和响应延迟。Go 标准库 database/sql 提供了 DB.Stats() 方法，返回一个 sql.DBStats 结构体，包含连接池运行时的全部关键指标。本节将深入解读这些指标的含义、正常范围以及异常信号。

4.1 sql.DBStats 结构体字段速览

DB.Stats() 返回的 sql.DBStats 结构体定义如下：

type DBStats struct {
    MaxOpenConnections int           // 最大打开连接数（配置值）
    OpenConnections    int           // 当前已打开（空闲+使用中）的连接数
    InUse              int           // 当前正在使用的连接数
    Idle               int           // 当前空闲的连接数
    WaitCount          int64         // 等待获取连接的总次数（累计值）
    WaitDuration       time.Duration // 等待获取连接的总耗时（累计值）
    MaxIdleClosed      int64         // 因超过 MaxIdleConns 而关闭的连接数
    MaxIdleTimeClosed  int64         // 因超过 ConnMaxIdleTime 而关闭的连接数
    MaxLifetimeClosed  int64         // 因超过 ConnMaxLifetime 而关闭的连接数
}

其中，WaitCount、WaitDuration、OpenConnections 是诊断连接池瓶颈的“三驾马车”。

4.2 核心指标深度解读

4.3 连接池状态流转与瓶颈定位

下面的 SVG 图展示了连接池内部的状态流转，以及各指标对应的瓶颈位置：

4.4 实战：采集与监控代码

以下代码展示了如何定期采集 DB.Stats() 指标，并输出到日志或监控系统：

package main

import (
    "database/sql"
    "fmt"
    "log"
    "time"
)

func monitorPool(db *sql.DB, interval time.Duration) {
    ticker := time.NewTicker(interval)
    defer ticker.Stop()

    var prevWaitCount int64
    var prevWaitDuration time.Duration

    for range ticker.C {
        stats := db.Stats()

        // 计算周期内的增量
        deltaWaitCount := stats.WaitCount - prevWaitCount
        deltaWaitDuration := stats.WaitDuration - prevWaitDuration

        avgWaitMs := float64(0)
        if deltaWaitCount > 0 {
            avgWaitMs = float64(deltaWaitDuration.Microseconds()) / float64(deltaWaitCount) / 1000.0
        }

        log.Printf("[连接池状态] Open=%d | InUse=%d | Idle=%d | "+
            "WaitCount(增量)=%d | AvgWait(ms)=%.2f | "+
            "MaxIdleClosed=%d | MaxLifetimeClosed=%d",
            stats.OpenConnections,
            stats.InUse,
            stats.Idle,
            deltaWaitCount,
            avgWaitMs,
            stats.MaxIdleClosed,
            stats.MaxLifetimeClosed,
        )

        // 告警检查
        if stats.OpenConnections >= stats.MaxOpenConnections && stats.Idle == 0 {
            log.Println("[告警] 连接池已满，所有连接都在使用中！")
        }
        if deltaWaitCount > 100 && avgWaitMs > 10 {
            log.Println("[告警] 大量请求等待连接，平均等待时间超过 10ms！")
        }

        prevWaitCount = stats.WaitCount
        prevWaitDuration = stats.WaitDuration
    }
}

func main() {
    // 假设 db 已初始化
    // monitorPool(db, 5*time.Second)
    fmt.Println("连接池监控已启动，每 5 秒采集一次")
}

4.5 指标异常排查清单

当监控发现异常指标时，可按以下清单快速定位根因：

• WaitCount 持续增长 + WaitDuration 上升
  • 检查 MaxOpenConns 是否设置过小
  • 检查是否存在慢查询导致连接长时间被占用
  • 检查应用是否存在连接泄漏（未调用 rows.Close()）
• OpenConnections 长期等于 MaxOpenConns
  • 确认并发请求量是否超过连接池上限
  • 评估是否需要增加 MaxOpenConns 或优化查询
• Idle 持续为 0
  • 检查 MaxIdleConns 是否设置过低
  • 检查 ConnMaxLifetime 是否过短导致连接频繁重建
• MaxLifetimeClosed 短时间内激增
  • 检查 ConnMaxLifetime 是否设置过短（如 < 5 分钟）
  • 检查数据库端是否有连接超时策略（如 MySQL 的 wait_timeout）

4.6 连接池健康度评分模型

基于上述指标，可以构建一个简单的连接池健康度评分，用于自动化决策：

type PoolHealth struct {
    Score          int    // 0-100，越高越健康
    Level          string // "健康" / "亚健康" / "告警" / "危险"
    Recommendations []string
}

func EvaluatePoolHealth(stats sql.DBStats) PoolHealth {
    score := 100
    var recs []string

    // 1. 连接使用率
    usageRate := float64(stats.InUse) / float64(stats.MaxOpenConnections)
    if usageRate > 0.9 {
        score -= 30
        recs = append(recs, "连接使用率超过 90%，建议增加 MaxOpenConns 或优化查询")
    } else if usageRate > 0.7 {
        score -= 10
        recs = append(recs, "连接使用率超过 70%，建议关注")
    }

    // 2. 等待情况
    if stats.WaitCount > 1000 {
        score -= 20
        recs = append(recs, "等待次数过多，可能存在连接竞争")
    }

    // 3. 空闲连接
    if stats.Idle == 0 && stats.InUse > 0 {
        score -= 15
        recs = append(recs, "无空闲连接，连接池压力较大")
    }

    // 4. 异常关闭
    if stats.MaxLifetimeClosed > 100 {
        score -= 10
        recs = append(recs, "连接频繁因生命周期关闭，检查 ConnMaxLifetime 设置")
    }

    level := "健康"
    if score < 60 {
        level = "危险"
    } else if score < 75 {
        level = "告警"
    } else if score < 90 {
        level = "亚健康"
    }

    return PoolHealth{
        Score:          score,
        Level:          level,
        Recommendations: recs,
    }
}

通过持续监控 WaitCount、WaitDuration、OpenConnections 等核心指标，可以精准掌握连接池的运行状态，为后续的慢查询分析和扩容策略提供数据支撑。