3. 连接池水位定义：水位概念、低水位、高水位、警戒水位、溢出水位

在 Go 报表回放系统中，连接池水位是对数据库连接资源使用程度的量化描述。与水库水位类似，连接池水位标识当前已分配连接数相对于总容量的比例，是判断连接池健康状态的核心指标。本章明确定义五种水位状态，并给出对应的监控阈值与调优策略。

3.1 水位概念与度量模型

连接池水位 = 当前活跃连接数 / 最大连接数（MaxOpen）。水位值范围 0.0 ~ 1.0（或 0% ~ 100%）。水位越高，表示连接资源越紧张，系统面临的风险越大。

3.2 低水位（Low Watermark）

低水位表示连接池处于空闲或轻度使用状态。此时连接利用率低于 30%，系统有充足的连接余量应对突发流量。

• 特征： 活跃连接数远小于 MaxOpen，等待队列长度接近 0，连接获取延迟 < 1ms。
• 风险： 无直接风险，但长期低水位可能意味着 MaxOpen 设置过大，浪费数据库资源。
• 调优建议： 可适当降低 MaxOpen 或减少 IdleTimeout，释放空闲连接。

3.3 高水位（High Watermark）

高水位是连接池的正常工作区间，水位在 30% ~ 70% 之间。系统处于稳定负载状态，连接复用率高，资源分配合理。

• 特征： 活跃连接数波动平稳，连接获取延迟 < 5ms，无排队或少量排队。
• 风险： 若水位持续上升至 70% 边界，需提前准备扩容或限流预案。
• 调优建议： 保持当前配置，监控水位变化速率，设置趋势告警。

3.4 警戒水位（Warning Watermark）

警戒水位是连接池进入紧张状态的标志，水位在 70% ~ 90% 之间。此时系统面临资源竞争，连接获取延迟明显增加。

• 特征： 活跃连接数接近 MaxOpen 的 80%，等待队列开始堆积，连接获取延迟 > 10ms。
• 风险： 若回放流量继续增长，可能快速突破溢出水位，导致连接超时或请求失败。
• 调优建议： 立即检查慢查询、长事务；考虑临时提升 MaxOpen 或限流回放速率。

3.5 溢出水位（Overflow Watermark）

溢出水位表示连接池已接近或达到最大容量，水位 ≥ 90%。此时系统处于高负载临界状态，任何额外请求都可能触发连接超时或熔断。

• 特征： 活跃连接数达到 MaxOpen 的 90% 以上，等待队列满，连接获取延迟 > 50ms 或超时。
• 风险： 数据库连接耗尽，新请求被拒绝；回放任务中断，数据一致性受损。
• 调优建议： 立即执行熔断或降级策略；扩容数据库连接上限；优化回放脚本减少连接占用时间。

3.6 水位状态转换与监控 SVG 图

下图展示连接池水位从低到溢出的完整状态转换路径，以及各水位对应的监控指标与动作。

3.7 水位监控代码示例

以下 Go 代码展示如何从 sql.DB.Stats() 中提取水位指标，并判断当前水位等级。

package monitor

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

// WaterLevel 水位等级
type WaterLevel int

const (
    Low       WaterLevel = iota // 低水位
    High                        // 高水位
    Warning                     // 警戒水位
    Overflow                    // 溢出水位
)

func (w WaterLevel) String() string {
    switch w {
    case Low:
        return "低水位"
    case High:
        return "高水位"
    case Warning:
        return "警戒水位"
    case Overflow:
        return "溢出水位"
    default:
        return "未知"
    }
}

// PoolWatermark 计算连接池水位
func PoolWatermark(db *sql.DB) (WaterLevel, float64, error) {
    stats := db.Stats()
    if stats.MaxOpenConnections == 0 {
        return Low, 0, fmt.Errorf("MaxOpenConnections 未设置")
    }

    // 水位 = 活跃连接数 / 最大连接数
    active := stats.InUse + stats.WaitCount
    ratio := float64(active) / float64(stats.MaxOpenConnections)

    var level WaterLevel
    switch {
    case ratio < 0.3:
        level = Low
    case ratio < 0.7:
        level = High
    case ratio < 0.9:
        level = Warning
    default:
        level = Overflow
    }

    return level, ratio, nil
}

// 使用示例
func Example() {
    db, _ := sql.Open("postgres", "dsn")
    defer db.Close()

    ticker := time.NewTicker(5 * time.Second)
    for range ticker.C {
        level, ratio, err := PoolWatermark(db)
        if err != nil {
            fmt.Printf("水位计算错误: %v\n", err)
            continue
        }
        fmt.Printf("[%s] 水位等级: %s, 水位值: %.2f%%\n",
            time.Now().Format("15:04:05"), level, ratio*100)

        if level >= Warning {
            fmt.Println("⚠️ 连接池进入警戒状态，请检查系统负载！")
        }
    }
}

3.8 水位定义对比总结