1. 课程导论：什么是事务连接池水位？为什么需要水位接口契约？

1.1 从一个生产事故说起

假设你负责一个日订单量千万级的 Go 微服务。某天流量突增，数据库连接池瞬间被打满，大量请求阻塞等待连接，最终触发雪崩——服务 OOM、接口超时、核心链路中断。事后排查发现：连接池最大连接数（MaxOpen）设置过高，但业务层未感知到池内连接已接近上限，仍在持续发起新事务，导致连接耗尽。

这个事故的核心问题在于：连接池内部状态对业务层完全透明。业务代码无法感知“当前池内活跃连接数是否已接近水位线”，也无法在达到阈值前主动降级或熔断。

1.2 什么是事务连接池水位？

事务连接池水位（Connection Pool Water Level）是指连接池在运行过程中，当前活跃连接数、等待连接数、空闲连接数相对于池容量上限的实时比例关系。它类似于水库的水位标尺，帮助运维和业务层判断池的健康状态。

水位通常由以下三个关键指标构成：

在 Go 标准库 database/sql 中，连接池通过 DB.Stats() 方法暴露了部分统计信息，但缺少水位百分比和动态阈值回调等高级语义。这正是本课程要解决的缺口。

1.3 为什么需要水位接口契约？

水位接口契约（Water Level Interface Contract）是一组标准化的 API 定义和行为约定，让业务代码能够：

• 查询：实时获取连接池水位百分比（0% ~ 100%）。
• 监听：注册水位变化回调，当水位超过阈值时自动触发降级逻辑。
• 控制：动态调整连接池参数（如 MaxOpen、MaxIdle）而不重启服务。
• 诊断：导出水位历史曲线，用于容量规划和根因分析。

没有契约的后果：

1. 盲人摸象：业务层只能通过超时错误间接推断池状态，无法主动预防。
2. 硬编码耦合：每个业务团队各自实现连接池监控逻辑，重复造轮子且标准不一。
3. 难以扩展：当连接池实现从 database/sql 切换到 pgxpool 或自研池时，业务代码需要大面积修改。

1.4 水位接口契约的架构位置

下图展示了水位接口契约在 Go 应用中的核心位置：

1.5 本课程的目标与受众

课程目标：

• 掌握 Go 连接池水位模型的核心原理与实现细节。
• 学会设计并实现一套生产级水位接口契约，覆盖查询、监听、控制、诊断四大能力。
• 能够将契约集成到现有 Go 项目中，并与 Prometheus、Grafana 等可观测性工具打通。
• 理解水位契约在分布式事务、读写分离、多数据源场景下的扩展方案。

目标受众：

1.6 课程内容概览

本课程共 30 章，分为四个模块：

1. 基础篇（第 1-8 章）：连接池原理、水位模型、Go 标准库源码分析。
2. 契约设计篇（第 9-16 章）：接口定义、回调机制、动态调整、线程安全。
3. 实现篇（第 17-24 章）：基于 database/sql 和 pgxpool 的完整实现。
4. 进阶篇（第 25-30 章）：分布式事务水位、多数据源协调、生产部署与监控。

每章均包含可运行的代码示例、SVG 架构图以及生产环境踩坑总结。

1.7 本章小结

• 事务连接池水位是衡量池健康状态的关键指标，包括活跃水位、等待水位、空闲水位。
• 水位接口契约解决了连接池状态对业务层透明的问题，提供查询、监听、控制、诊断四大能力。
• 本课程面向 Go 开发者、中间件工程师、SRE 和技术负责人，目标是让连接池从“黑盒”变为“可编程资源”。