2. 水位概念定义：低水位、高水位、紧急水位的定义与业务含义

在事务连接池的治理模型中，水位（Water Level）是描述池中活跃连接与总容量之间动态关系的核心抽象。通过将连接池的占用状态划分为三个离散区间——低水位、高水位、紧急水位，系统能够对连接压力进行分级感知，并触发差异化的治理策略。

2.1 水位划分的数学基础

设连接池总容量为 MaxConn，当前活跃连接数为 Active，则水位比率 R = Active / MaxConn。三个水位区间由两个关键阈值界定：

其中 LowWaterMark 和 HighWaterMark 为可配置的浮点数阈值，典型默认值分别为 0.6 和 0.85。

2.2 低水位：绿色区间

定义：活跃连接数远低于池容量上限，系统处于轻载或空闲状态。

业务含义：

• 资源充裕：连接获取几乎无等待，请求可立即获得连接。
• 健康信号：数据库负载低，连接周转速度快，无积压风险。
• 治理策略：不触发任何限流或降级动作；允许连接池按需创建新连接（不超过 MaxConn）。
• 典型场景：业务低峰期、请求量平稳且数据库响应迅速。

2.3 高水位：黄色区间

定义：活跃连接数已超过低水位阈值但尚未触及紧急水位，池容量进入中等占用状态。

业务含义：

• 压力预警：连接资源开始紧张，部分请求可能经历短暂排队。
• 风险积累：若持续处于高水位，数据库连接周转效率下降，可能引发连锁阻塞。
• 治理策略：启动温和限流——对非核心请求进行降级或延迟处理；禁止创建新连接（即使未达 MaxConn），优先复用已有连接。
• 典型场景：业务高峰期、突发流量冲击、慢查询导致连接长时间占用。

2.4 紧急水位：红色区间

定义：活跃连接数达到或超过紧急水位阈值，池容量接近饱和或已饱和。

业务含义：

• 临界状态：连接池几乎无可用连接，新请求大概率被阻塞或超时。
• 系统风险：数据库连接耗尽将导致服务大面积不可用，甚至引发雪崩效应。
• 治理策略：触发强制熔断——直接拒绝非关键请求（返回 429 Too Many Requests 或自定义错误）；对已持有的连接执行快速回收（如强制关闭空闲超过阈值的连接）；向监控系统发送紧急告警。
• 典型场景：数据库故障导致连接无法释放、上游服务疯狂重试、DDoS 攻击。

2.5 水位状态转换与业务响应

下图展示了连接池水位之间的转换路径以及每个转换点对应的治理动作：

2.6 水位阈值配置与业务适配

不同业务场景对水位阈值的敏感度差异显著。下表给出了典型场景下的推荐配置：

2.7 水位在 Go 接口契约中的映射

在后续章节的 Go 接口设计中，水位状态将作为连接池治理决策的输入信号。以下伪代码展示了水位判断的核心逻辑：

// WaterLevel 表示连接池当前水位等级
type WaterLevel int

const (
    WaterLevelLow    WaterLevel = iota // 低水位
    WaterLevelHigh                     // 高水位
    WaterLevelCritical                 // 紧急水位
)

// GetWaterLevel 根据当前活跃连接数和总容量计算水位
func GetWaterLevel(active, maxConn int, lowMark, highMark float64) WaterLevel {
    if maxConn <= 0 {
        return WaterLevelCritical // 防御性处理
    }
    ratio := float64(active) / float64(maxConn)
    switch {
    case ratio >= highMark:
        return WaterLevelCritical
    case ratio >= lowMark:
        return WaterLevelHigh
    default:
        return WaterLevelLow
    }
}

该接口将水位计算与治理策略解耦，使得上层调用方（如限流器、熔断器）只需关注 WaterLevel 枚举值，无需关心阈值计算细节。