4、核心接口定义：PoolWatermarker 接口的 Go 代码定义、方法签名说明

在事务连接池水位治理体系中，PoolWatermarker 是连接池与水位监控器之间的核心契约接口。它定义了连接池必须暴露给水位管理模块的一组观测与控制方法，使水位管理器能够在不侵入连接池内部实现的前提下，完成水位采集、阈值判定、动态伸缩与安全回退。

4.1 接口定义

// PoolWatermarker 定义连接池水位观测与控制契约。
// 实现方必须保证所有方法在并发环境下安全调用。
type PoolWatermarker interface {
    // ---- 水位观测 ----

    // CurrentWatermark 返回当前连接池的瞬时水位指标。
    // 返回值包括：活跃连接数、空闲连接数、等待队列深度、总连接数上限。
    CurrentWatermark(ctx context.Context) (*Watermark, error)

    // PeakWatermark 返回自上次重置以来的历史峰值水位。
    // 用于评估连接池的峰值压力与扩容需求。
    PeakWatermark(ctx context.Context) (*Watermark, error)

    // ---- 水位控制 ----

    // ResizePool 动态调整连接池的总连接数上限。
    // newSize 为目标总连接数，必须大于等于 MinIdle 且小于等于 MaxCapacity。
    // 返回调整后的实际总连接数上限。
    ResizePool(ctx context.Context, newSize int) (int, error)

    // DrainIdleConnections 回收所有空闲连接，直到空闲连接数降至 targetIdle 以下。
    // 用于水位过高时的快速降水位操作。
    DrainIdleConnections(ctx context.Context, targetIdle int) (int, error)

    // ---- 安全回退 ----

    // CircuitBreakerState 返回当前连接池的熔断器状态。
    // 返回值：Closed（正常）、Open（熔断开启）、HalfOpen（半开探测）。
    CircuitBreakerState(ctx context.Context) (CircuitState, error)

    // SetCircuitBreaker 手动设置熔断器状态。
    // 水位管理器在检测到持续高水位或异常抖动时，可主动触发熔断。
    SetCircuitBreaker(ctx context.Context, state CircuitState) error
}

4.2 方法签名说明

方法 分类 输入 输出 核心语义
CurrentWatermark 观测 ctx context.Context (*Watermark, error) 返回当前瞬时水位，包含活跃、空闲、等待、上限四个维度
PeakWatermark 观测 ctx context.Context (*Watermark, error) 返回自上次重置以来的历史峰值水位，用于扩容决策
ResizePool 控制 ctx context.Context, newSize int (int, error) 动态调整总连接数上限，返回实际生效值
DrainIdleConnections 控制 ctx context.Context, targetIdle int (int, error) 回收空闲连接至目标值以下，返回实际回收数量
CircuitBreakerState 安全 ctx context.Context (CircuitState, error) 查询当前熔断器状态
SetCircuitBreaker 安全 ctx context.Context, state CircuitState error 手动设置熔断器状态，水位管理器可主动触发熔断

4.3 辅助类型定义

// Watermark 表示连接池的瞬时水位快照。
type Watermark struct {
    ActiveConnections  int     // 当前正在被使用的连接数
    IdleConnections    int     // 当前空闲连接数
    WaitingRequests    int     // 当前等待获取连接的请求数
    MaxConnections     int     // 连接池总连接数上限
    UtilizationPercent float64 // 连接利用率 = ActiveConnections / MaxConnections * 100
}

// CircuitState 表示熔断器状态。
type CircuitState int

const (
    CircuitClosed   CircuitState = iota // 正常状态，请求正常通过
    CircuitOpen                         // 熔断开启，请求直接失败
    CircuitHalfOpen                     // 半开状态，允许少量探测请求
)
设计要点：
  • CurrentWatermark 与 PeakWatermark 分离，避免峰值统计干扰瞬时读数。
  • ResizePool 返回实际值而非入参值，因为连接池实现可能受 MaxCapacity 硬限制而截断。
  • DrainIdleConnections 的 targetIdle 是目标上限，而非回收数量，语义更清晰。
  • 熔断器状态由水位管理器统一管控，连接池仅暴露状态查询与设置接口。

4.4 接口调用流程

水位管理器通过 PoolWatermarker 接口与连接池交互的典型流程如下：

  1. 水位采集：定时调用 CurrentWatermark 获取瞬时水位。
  2. 阈值判定：将水位与预设的高水位线、低水位线比较。
  3. 扩容决策：若水位持续高于高水位线，调用 ResizePool 增加总连接数上限。
  4. 缩容决策：若水位低于低水位线且空闲连接过多，调用 DrainIdleConnections 回收空闲连接。
  5. 熔断保护：若水位异常飙升或抖动剧烈，调用 SetCircuitBreaker 开启熔断。
  6. 峰值记录：定期读取 PeakWatermark 用于容量规划与扩缩容阈值调优。
PoolWatermarker 接口调用流程 1. 水位采集 2. 阈值判定 3. 扩容决策 4. 缩容决策 5. 熔断保护 6. 峰值记录
关键设计原则：
  • 最小知识原则：水位管理器只通过 PoolWatermarker 接口与连接池交互，不依赖任何连接池内部实现细节。
  • 幂等性：所有控制方法（ResizePool、DrainIdleConnections、SetCircuitBreaker）应设计为幂等操作，允许重复调用。
  • 上下文传播：所有方法均接收 context.Context，支持超时、取消与链路追踪。
  • 错误可观测：所有方法返回 error，水位管理器应记录并告警，而非静默忽略。

4.5 接口实现契约

方法 并发安全要求 阻塞行为 错误场景
CurrentWatermark 必须 非阻塞，快速返回 连接池已关闭、上下文超时
PeakWatermark 必须 非阻塞，快速返回 连接池已关闭、上下文超时
ResizePool 必须 可能阻塞（等待连接释放） newSize 超出 [MinIdle, MaxCapacity]、连接池已关闭
DrainIdleConnections 必须 非阻塞，仅回收当前空闲连接 连接池已关闭、上下文超时
CircuitBreakerState 必须 非阻塞，快速返回 连接池已关闭
SetCircuitBreaker 必须 非阻塞 状态转换非法（如 Closed→HalfOpen）、连接池已关闭
实现注意事项：
  • ResizePool 的 newSize 必须大于等于 MinIdle，否则实现应返回错误而非静默截断。
  • DrainIdleConnections 只回收当前空闲连接，不等待正在使用的连接归还，避免阻塞水位管理器。
  • 熔断器状态转换必须遵循 Closed → Open → HalfOpen → Closed 的有限状态机规则，非法转换应返回错误。
  • 所有方法在连接池已关闭时应返回明确的 ErrPoolClosed 错误，便于水位管理器做降级处理。
← 上一章 📖 返回目录 下一章 →