4. 水位概念定义：高水位、低水位、警戒水位、当前水位

在事务连接池的治理体系中，水位（Water Level）是描述连接池资源占用与健康状态的核心抽象。通过定义明确的数值边界，水位将连接池的连续状态离散化为可观测、可告警、可自愈的区间。本章正式定义四种水位：低水位、高水位、警戒水位和当前水位，并阐述它们与连接池健康度的映射关系。

4.1 水位定义与数值含义

连接池的总容量由 MaxOpen（最大打开连接数）决定。所有水位均基于 MaxOpen 的百分比或绝对数值进行设定。下表列出四种水位的标准定义：

4.2 水位与连接池健康度的关系

连接池的健康度并非二元状态（健康/不健康），而是一个连续光谱。水位提供了将光谱离散化的标尺。健康度从优到劣可划分为四个等级，每个等级对应一个水位区间：

• 绿色（健康）：当前水位 ≤ 低水位。连接池空闲连接充足，请求几乎无等待，系统处于最佳经济状态。
• 黄色（亚健康）：低水位 < 当前水位 ≤ 高水位。连接池处于正常负载，资源利用率合理，但需要监控增长趋势。
• 橙色（紧张）：高水位 < 当前水位 ≤ 警戒水位。连接池接近满载，新请求可能开始排队，需要介入检查。
• 红色（危险）：当前水位 > 警戒水位。连接池即将或已经枯竭，请求超时、获取连接失败的概率急剧上升。

4.3 水位区间与连接池状态机

水位不仅是静态阈值，更是连接池状态迁移的触发条件。下图展示了基于水位的连接池状态机：

4.4 水位接口契约

在 Go 事务连接池的接口设计中，水位相关的契约应包含以下核心方法：

// WatermarkConfig 定义连接池水位阈值配置
type WatermarkConfig struct {
    LowWatermark      int // 低水位，单位：连接数
    HighWatermark     int // 高水位，单位：连接数
    CriticalWatermark int // 警戒水位，单位：连接数
}

// WatermarkStats 返回当前水位快照
type WatermarkStats struct {
    CurrentWatermark int    // 当前已分配连接数（InUse）
    LowWatermark     int    // 低水位阈值
    HighWatermark    int    // 高水位阈值
    CriticalWatermark int   // 警戒水位阈值
    HealthLevel      string // "green" | "yellow" | "orange" | "red"
}

// PoolWatermarker 水位接口
type PoolWatermarker interface {
    // GetWatermarkConfig 获取当前水位配置
    GetWatermarkConfig() WatermarkConfig

    // SetWatermarkConfig 动态更新水位配置
    SetWatermarkConfig(cfg WatermarkConfig) error

    // ObserveWatermark 观测当前水位并返回健康等级
    ObserveWatermark() WatermarkStats

    // IsAboveCritical 快速判断是否超过警戒水位
    IsAboveCritical() bool
}

4.5 水位与连接池健康度的量化映射

为了在监控系统中实现自动化决策，需要将水位区间与健康度分数进行量化绑定。下表给出了推荐的映射关系：

4.6 水位观测的工程要点

• 采样粒度：建议使用 1 秒或 5 秒的固定窗口采集当前水位，避免高频采样造成性能开销。
• 抖动抑制：当前水位在短时间内可能出现毛刺（burst）。建议引入滑动平均或滞后阈值（hysteresis），防止状态在边界频繁震荡。
• 水位与连接池生命周期：连接池初始化时，当前水位为 0；随着请求涌入，水位上升；当请求处理完毕，连接归还池中，水位下降。水位的变化速率（Δ/Δt）比绝对值更能反映连接池的健康趋势。
• 多维度水位：除了全局水位，还可以按数据库分片、按业务标签定义独立的水位，实现精细化治理。