31.数据库SQL连接池

卷三第 31 篇——database/sql 是 Go 数据库访问的统一入口，但"连接池怎么管理连接"、"rows.Close() 为什么必须调用"、"事务独占连接意味着什么"——这些细节是生产事故的高发区。本篇从 sql.Open 出发，拆解 DB.freeConn 空闲连接链表的获取与归还机制、Prepare/Exec/Query 的内部流程、事务对连接的独占持有、SetMaxOpenConns/SetMaxIdleConns 的精确含义，以及连接泄漏的诊断方法。关键词：sql.DB、freeConn、SetMaxOpenConns、SetMaxIdleConns、ConnPool、事务独占、连接泄漏、sqlx、GORM。

目录介绍

• 1. 案例引入
  • 1.1 一段崩在哪
  • 1.2 顺藤摸到根因
  • 1.3 我们要回答什么
• 2. 架构概览
  • 2.1 database/sql 的分层设计
  • 2.2 为什么需要连接池
• 3. sql.Open 与连接初始化
  • 3.1 Open 不建立连接——惰性连接
  • 3.2 driver.Connector 接口
• 4. 连接池的核心参数
  • 4.1 SetMaxOpenConns：并发上限
  • 4.2 SetMaxIdleConns：空闲保留
  • 4.3 SetConnMaxLifetime：连接寿命
• 5. Prepare/Exec/Query 流程
  • 5.1 从连接池获取连接
  • 5.2 DB.conn 的获取与归还
  • 5.3 Stmt 的缓存机制
• 6. 事务与连接独占
  • 6.1 Begin 的底层加锁
  • 6.2 Commit/Rollback 后的连接释放
• 7. sqlx 增强与 GORM 原理简析
  • 7.1 sqlx 的结构体扫描
  • 7.2 GORM 的 Session 模型
• 8. 连接泄漏的根因与排查
  • 8.1 三种典型泄漏模式
  • 8.2 DB.Stats 与 pprof 诊断
• 9. 生产环境最佳实践
  • 9.1 连接池参数推荐值
  • 9.2 超时与 Context 的正确使用
• 10. 综合案例串讲
  • 10.1 案例真相揭晓
  • 10.2 一次 Query 从连接获取到归还的完整路径
  • 10.3 设计哲学回扣
  • 10.4 速查表

1. 案例引入

1.1 一段崩在哪

某订单处理服务——使用 database/sql 连接 MySQL，配置 SetMaxOpenConns(100)。服务平时 QPS 500 运行平稳，促销日 QPS 暴涨到 3000，大量请求开始返回 "driver: bad connection" 和 "connection pool exhausted" 错误。而 MySQL 服务端的 SHOW PROCESSLIST 只显示 80 个活跃连接——远未达到 max_connections=500 的限制。

// order_service.go —— 订单查询服务（含泄漏 bug）
package main

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

    _ "github.com/go-sql-driver/mysql"
)

var db *sql.DB

func initDB() {
    db, _ = sql.Open("mysql", "user:pass@tcp(localhost:3306)/orders")
    db.SetMaxOpenConns(100)   // 最多 100 个并发连接
    db.SetMaxIdleConns(20)    // 最多保留 20 个空闲连接
    db.SetConnMaxLifetime(5 * time.Minute)
}

func queryOrder(ctx context.Context, orderID string) (*Order, error) {
    rows, err := db.QueryContext(ctx,
        "SELECT id, user_id, amount, status FROM orders WHERE id = ?", orderID)
    if err != nil {
        return nil, fmt.Errorf("query: %w", err)
    }
    // ❌ 缺少 defer rows.Close()

    if !rows.Next() {
        // 无结果——直接 return，rows 没有 Close！
        return nil, sql.ErrNoRows
    }

    var o Order
    if err := rows.Scan(&o.ID, &o.UserID, &o.Amount, &o.Status); err != nil {
        return nil, fmt.Errorf("scan: %w", err)
    }
    // ❌ 正常路径也没有关闭 rows
    return &o, nil
}

现象：

• db.Stats().OpenConnections 持续增长直到 100——随后新请求被阻塞在 db.conn() 中，等待空闲连接
• db.Stats().InUse 始终为 100——所有连接都"在用"
• db.Stats().Idle 始终为 0——没有返回空闲池的连接
• MySQL SHOW PROCESSLIST 显示 100 个连接都在 Sleep 状态——没有正在执行的查询

1.2 顺藤摸到根因

追查：

• 假设 1：是不是连接池参数太小？—— SetMaxOpenConns(100)，QPS 3000，假设每个查询 50ms——理论上需要 150 个并发连接。但 MySQL 显示连接都是 Sleep 状态——说明查询早已执行完毕。

• 假设 2：是不是连接没有被归还？—— rows.Close() 的职责是释放底层连接回池。看代码：queryOrder 在所有路径（正常返回、无结果返回、scan 错误返回）都没有调用 rows.Close()。每个查询永久持有一个连接。

• 假设 3：连接到底被谁持有？—— pprof goroutine 显示 goroutine 数和连接数不对应。说明不是 goroutine 泄漏——而是 sql.DB 内部的 freeConn 链表中连接没有被放回。

• 假设 4：MySQL 端的 Sleep 状态说明什么？—— 连接已经空闲（没有活跃事务、没有未读取的 ResultSet），但 Go 侧没有调用 rows.Close()，所以 database/sql 认为这个连接还在被 rows 占用。

• 根本原因：rows.Close() 是归还连接的唯一入口。即使 rows.Next() 返回 false（无更多行），database/sql 也不会自动归还连接——因为调用方可能还想知道 rows.Err() 的结果。在调用 rows.Close() 之前，连接一直处于"被占用"状态。

这个案例藏着至少 7 个原理点：

① sql.Open 创建了什么？为什么它不立即建立连接？               → 第 3 章
② SetMaxOpenConns 和 SetMaxIdleConns 的精确含义？           → 第 4 章
③ db.Query 的内部流程——如何从池中获取连接？                  → 第 5 章
④ rows.Close() 的内部实现——连接如何归还？                    → 第 5.2
⑤ 事务 Begin 如何独占连接？Commit/Rollback 后连接去哪？      → 第 6 章
⑥ db.Stats() 能告诉我们什么信息？                            → 第 8 章
⑦ 生产环境如何配置连接池参数？                                → 第 9 章

1.3 我们要回答什么

这个订单服务案例就是本篇的主线案例。我们从 sql.Open 的惰性连接策略出发，拆解 freeConn 链表的获取与归还、Query/Exec 的完整流程、事务的独占连接机制、连接泄漏的诊断方法——最后回到订单服务，给出 defer rows.Close() + Stats 监控的根除方案。

本篇路线：

Open 启动 (第 3 章) ── 惰性连接——Open 不等于 Connect
   ↓
池参数 (第 4 章) ── MaxOpen/MaxIdle/MaxLifetime 的三维控制
   ↓
Query 流程 (第 5 章) ── conn获取→执行→rows.Close→归还
   ↓
事务 (第 6 章) ── Begin 的独占与释放
   ↓
框架简析 (第 7 章) ── sqlx/GORM 的连接池复用
   ↓
诊断 (第 8 章) ── Stats + pprof 定位泄漏
   ↓
最佳实践 (第 9 章) ── 参数推荐 + Context 超时
   ↓
综合案例 (第 10 章) ── 回到订单服务，根治连接泄漏

📌 本篇定位：database/sql 是 Go 数据库访问的"门面"。读完本篇，我们能回答："db.QueryContext(ctx, sql, args...) 调用后，连接是如何从空闲池中取出的？rows.Close() 内部做了哪些操作才让连接回到池中？"

2. 架构概览

2.1 database/sql 的分层设计

database/sql 是 Go 数据库访问的两层架构：

          ┌─────────────────────────┐
          │  database/sql (标准库)   │  ← 连接池、语句缓存、统一 API
          │  DB, Stmt, Rows, Tx     │
          └──────────┬──────────────┘
                     │  driver.Connector / driver.Conn
          ┌──────────▼──────────────┐
          │  go-sql-driver/mysql    │  ← 第三方驱动（实现 driver 接口）
          │  (或其他第三方驱动)      │
          └──────────┬──────────────┘
                     │  TCP / Unix Socket
          ┌──────────▼──────────────┐
          │  MySQL / PostgreSQL /   │  ← 数据库服务端
          │  SQLite / ...           │
          └─────────────────────────┘

database/sql 的职责：

• 连接池管理（获取/归还）
• 语句缓存（Stmt）
• 参数化查询（Query/Exec）
• 事务（Begin/Commit/Rollback）
• Null 类型处理（NullString/NullInt64）

驱动的职责：

• 建立 TCP 连接
• 发送 SQL 语句
• 返回结果集
• 实现 driver.Conn、driver.Stmt、driver.Rows 接口

2.2 为什么需要连接池

疑惑：每次查询建立一个 TCP 连接不行吗？

论证：

1. TCP 三次握手 + TLS（可选）+ MySQL 认证——每次建立新连接约 5-10ms。对于 1000 QPS 的服务，每秒仅在连接建立上就消耗 5-10s 的 CPU 时间（5ms × 1000）。

2. MySQL 的连接数限制——如果每次查询都新连接，1000 QPS × 50ms 查询 = 需要同时维持 50 个连接。但没有连接池的话，连接快速创建和销毁——TIME_WAIT 状态的连接会积压。

3. 连接复用 = 近零开销——从连接池获取一个已有连接只需 ~1μs（取链表的头节点）。对比新建连接的 5ms——快了 5000 倍。

结论：连接池不是优化——它是高并发数据库访问的基础设施。database/sql 内置连接池意味着每个 Go 开发者都在不经配置的情况下受惠于连接复用。

3. sql.Open 与连接初始化

3.1 Open 不建立连接——惰性连接

// database/sql/sql.go (简化)
func Open(driverName, dataSourceName string) (*DB, error) {
    // 1. 查找已注册的驱动
    driveri, ok := drivers[driverName]
    if !ok {
        return nil, fmt.Errorf("sql: unknown driver %q", driverName)
    }

    // 2. 创建 DB——不建立任何连接！
    db := &DB{
        driver:        driveri,
        dsn:           dataSourceName,
        openerCh:      make(chan struct{}, connectionRequestQueueSize),
        freeConn:      make([]*driverConn, 0),
        connRequests:  make(map[uint64]chan connRequest),
        maxOpen:       0,  // 默认无限制
        maxIdle:       2,  // 默认保留 2 个空闲连接
        maxLifetime:   0,  // 默认永不过期
    }

    // 3. 启动连接创建 goroutine
    go db.connectionOpener()

    return db, nil  // ← 此时还没有任何一个 MySQL 连接！
}

关键：sql.Open 不会创建任何连接——它只初始化 DB 结构体和启动一个后台 goroutine。第一个连接在第一次 db.Query/db.Exec/db.Ping 时才被惰性创建。

3.2 driver.Connector 接口

// database/sql/driver/driver.go
type Connector interface {
    Connect(context.Context) (Conn, error)  // 创建新连接
    Driver() Driver                         // 返回底层驱动
}

// 使用
connector, _ := mysql.NewConnector(&mysql.Config{...})
db := sql.OpenDB(connector)  // 替代 sql.Open——更强类型安全

4. 连接池的核心参数

4.1 SetMaxOpenConns：并发上限

// database/sql/sql.go
func (db *DB) SetMaxOpenConns(n int) {
    db.mu.Lock()
    defer db.mu.Unlock()
    db.maxOpen = n
    // 如果新限制小于当前空闲连接数——关闭多余的空闲连接
    if n < 0 { n = 0 }  // 负数→无限制
    if n < len(db.freeConn) {
        for i := n; i < len(db.freeConn); i++ {
            db.freeConn[i].Close()
        }
        db.freeConn = db.freeConn[:n]
    }
}

语义：同时最多可以有 n 个连接被使用中（InUse）。当 InUse 达到 n 时，新的 db.Query 调用会阻塞等待——直到有连接被归还。0（默认）表示无限制。

4.2 SetMaxIdleConns：空闲保留

db.SetMaxIdleConns(20)  // 空闲池中最多保留 20 个连接

语义：连接归还后，如果空闲池已有 20 个连接——多出的连接被关闭（而不是保留）。MaxIdleConns 决定了"保温"连接的数量。设置过小 → 频繁建连和拆连。设置过大 → 占用数据库 max_connections 配额。

4.3 SetConnMaxLifetime：连接寿命

db.SetConnMaxLifetime(5 * time.Minute)

语义：连接创建后最多存活 5 分钟。过期连接在归还时被关闭——即使空闲池有空位。目的：防止 MySQL 服务端的 wait_timeout 杀掉长时间空闲的连接。

5. Prepare/Exec/Query 流程

5.1 从连接池获取连接

db.QueryContext(ctx, sql, args...) 内部调用 db.conn(ctx, strategy) 获取连接：

// database/sql/sql.go (简化)
func (db *DB) conn(ctx context.Context, strategy connReuseStrategy) (*driverConn, error) {
    // 1. 先从空闲池中获取
    if db.numOpen >= db.maxOpen {
        // 已达上限——阻塞等待
        return db.connRequestWait(ctx)
    }

    // 2. 空闲池有连接？
    db.mu.Lock()
    if n := len(db.freeConn); n > 0 {
        conn := db.freeConn[0]  // 取第一个空闲连接
        db.freeConn = db.freeConn[1:]
        db.mu.Unlock()
        // 检查连接是否过期
        if conn.expired(db.maxLifetime) {
            conn.Close()
            return db.conn(ctx, strategy)  // 递归——拿下一个
        }
        return conn, nil
    }
    db.mu.Unlock()

    // 3. 空闲池为空——创建新连接（通过 openerCh goroutine）
    db.numOpen++
    return db.connector.Connect(ctx)
}

connRequestWait 阻塞等待——当 InUse 达到 MaxOpen 时，请求者进入 db.connRequests map 中排队。连接归还时优先唤醒等待者。

5.2 DB.conn 的获取与归还

归还的关键——rows.Close() 内部链路：

// 用户代码
rows, _ := db.QueryContext(ctx, "SELECT ...")
defer rows.Close()  // ← 归还连接的唯一入口！

// database/sql/sql.go (简化)
func (rs *Rows) Close() error {
    return rs.close(nil)
}

func (rs *Rows) close(err error) error {
    // 1. 释放底层驱动的 Rows（释放 MySQL ResultSet）
    rs.rowsi.Close()

    // 2. 归还连接 db.conn 到空闲池
    if rs.closeStmt != nil {
        // 如果 Query 内部 Prepare 了 Stmt——归还 Stmt 到缓存
    }

    // 3. putConn 归还连接
    db.putConn(rs.dc, err)
    return nil
}

func (db *DB) putConn(dc *driverConn, err error) {
    db.mu.Lock()

    // 如果有等待者——直接给等待者（不放入空闲池）
    if len(db.connRequests) > 0 {
        // 取出最早等待的请求，将连接通过 channel 发给它
        req := 从 connRequests 中取出
        req.ch <- dc
        db.mu.Unlock()
        return
    }

    // 空闲池未满——放入空闲链表
    if len(db.freeConn) < db.maxIdle {
        db.freeConn = append(db.freeConn, dc)
        db.mu.Unlock()
        return
    }

    // 空闲池已满——直接关闭连接
    db.mu.Unlock()
    dc.Close()
}

5.3 Stmt 的缓存机制

db.PrepareContext(ctx, sql) 创建的 Stmt 可以利用连接池 —— 但 Stmt 绑定到一个具体连接上。database/sql 通过 stmtConnGrab 机制在调用 Stmt.Query 时临时绑定一个空闲连接：

// Stmt.QueryContext 内部：
// 1. 从连接池获取连接
// 2. 在这个连接上执行 prepare（如果该连接尚未 prepare 此 SQL）
// 3. 执行 query
// 4. 归还连接
// 连接上的 Stmt 被缓存——下次同一连接执行同样 SQL 时跳过 prepare

6. 事务与连接独占

6.1 Begin 的底层加锁

// database/sql/sql.go (简化)
func (db *DB) BeginTx(ctx context.Context, opts *TxOptions) (*Tx, error) {
    // 1. 从连接池获取连接——和 Query 一样的入口
    dc, err := db.conn(ctx, cachedOrNewConn)
    if err != nil { return nil, err }

    // 2. 在连接上开始事务
    txi, err := dc.ci.BeginTx(ctx, opts)

    // 3. 创建 Tx——持有 dc（不归还！）
    tx := &Tx{
        db:  db,
        dc:  dc,          // ← 独占此连接直到 Commit/Rollback
        txi: txi,
    }

    // 连接被"钉"在事务上——不会回到空闲池
    return tx, nil
}

关键：事务持有连接（Tx.dc），这个连接在 Commit 或 Rollback 之前不会回到空闲池。如果一个事务长时间执行（比如持有行锁等待外部服务响应）——连接一直被占用，阻塞其他请求。

6.2 Commit/Rollback 后的连接释放

func (tx *Tx) Commit() error {
    // 1. 提交事务
    err := tx.txi.Commit()
    // 2. 释放连接回池
    tx.dc = nil  // ← 断开 Tx 对连接的引用
    tx.db.putConn(dc, err)
    return err
}
// Rollback 类似——调用 dc.txi.Rollback() → putConn

忘记 Commit/Rollback 的后果——Tx 对象被 GC 回收时，Tx.finalize() 会自动调用 Rollback()。但这是"保险"——不应依赖。持有连接直到 GC 是不确定的。

7. sqlx 增强与 GORM 原理简析

7.1 sqlx 的结构体扫描

sqlx 是对 database/sql 的薄封装——核心增强是结构体扫描：

// sqlx 内部通过反射将列值映射到结构体字段
type User struct {
    ID     int    `db:"id"`
    Name   string `db:"name"`
}

var users []User
// 等价于手动 rows.Scan——但自动通过 reflect + struct tag 完成
db.Select(&users, "SELECT id, name FROM users")

实现：squirrel 组合键扫描——rows.Columns() → reflect 枚举结构体字段 → rows.Scan(dest...)。

7.2 GORM 的 Session 模型

GORM 在 database/sql 之上构建了完整的 ORM 层次。它的 *gorm.DB 是一个连接会话——内部持有 *sql.DB：

// GORM 简化的内部结构
type gorm.DB struct {
    *gorm.Config
    db        *sql.DB          // ← 底层连接池
    Statement *gorm.Statement  // 当前执行的 SQL
}

// gorm.Open 不做任何连接——内部调用 sql.Open
db, _ := gorm.Open(mysql.Open(dsn), &gorm.Config{})

// db.Find(&users) 内部调用 sql.DB.QueryContext
// 连接池管理完全由 database/sql 负责——GORM 不插手

GORM 的连接池参数——直接转发给 sql.DB：

sqlDB, _ := gormDB.DB()
sqlDB.SetMaxOpenConns(100)
sqlDB.SetMaxIdleConns(20)

8. 连接泄漏的根因与排查

8.1 三种典型泄漏模式

模式 1：rows 未关闭（第 1 章根因）

// ❌ rows.Next() 返回 false 后直接 return——rows 没有 Close
rows, _ := db.Query("SELECT ...")
for rows.Next() {
    rows.Scan(&v)
}
// ← rows.Close 从未被调用 → 连接泄漏

模式 2：事务没有 Commit/Rollback

// ❌ Begin 后忘记结束——连接一直被事务持有
tx, _ := db.Begin()
tx.Exec("UPDATE users SET status = 1")
// ← 没有 tx.Commit() 也没有 tx.Rollback()

模式 3：Stmt 未关闭

// ❌ Stmt 在 db 级别 prepared——占用连接池资源
stmt, _ := db.Prepare("SELECT ...")
// ← 没有 stmt.Close()

8.2 DB.Stats 与 pprof 诊断

stats := db.Stats()
fmt.Printf("OpenConnections: %d\n", stats.OpenConnections)  // 总连接数
fmt.Printf("InUse: %d\n", stats.InUse)                      // 正在使用
fmt.Printf("Idle: %d\n", stats.Idle)                        // 空闲池中
fmt.Printf("MaxOpenConnections: %d\n", stats.MaxOpenConnections)
fmt.Printf("WaitCount: %d\n", stats.WaitCount)              // 等待获取连接的次数
fmt.Printf("WaitDuration: %v\n", stats.WaitDuration)        // 总等待时间

诊断信号：

指标	正常	异常	根因
InUse 持续等于 MaxOpen	❌	连接泄漏或并发过高	rows.Close() 缺失
WaitCount 持续增长	❌	所有请求在排队等连接	连接池太小或泄漏
Idle 等于 MaxIdle	✓	—	空闲池满了——正常
OpenConnections 远大于 InUse+Idle	❌	有连接未计入	底层驱动 bug

9. 生产环境最佳实践

9.1 连接池参数推荐值

参数	推荐设置	计算方式
MaxOpenConns	MySQL max_connections × 0.8 / 实例数	预留 20% 给 DBA 和管理连接
MaxIdleConns	MaxOpenConns × 0.5 ~ 1.0	等于 MaxOpen 也行——只是"保留上限"
MaxLifetime	wait_timeout - 60s	比 MySQL 杀死连接的时间短 1 分钟
MaxIdleTime (Go 1.15+)	5m ~ 10m	空闲连接在此时间后被关闭

9.2 超时与 Context 的正确使用

// ✅ 正确：带超时的查询
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
rows, err := db.QueryContext(ctx, "SELECT ...")
// 3 秒后 ctx.Done() 被关闭 → database/sql 取消查询 → 归还连接

// ✅ 正确：带超时的事务
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
tx, err := db.BeginTx(ctx, nil)
// 事务内操作共享此 context — 5 秒后自动 Rollback

10. 综合案例串讲

10.1 案例真相揭晓

回到第 1 章订单服务的七个疑问，逐条作答：

疑问	答案
① sql.Open 创建了什么？	第 3.1：初始化 DB 结构体 + freeConn 链表——不建立连接
② MaxOpen/MaxIdle 的含义？	第 4 章：MaxOpen=并发上限（阻塞信号）；MaxIdle=空闲池大小（关闭信号）
③ Query 的完整流程？	第 5 章：conn()获取→驱动Query→rows封装→用户Scan→rows.Close→putConn归还
④ rows.Close 内部如何归还？	第 5.2：释放驱动 Rows → putConn → 先分给等待者，否则入空闲池
⑤ 事务为何独占连接？	第 6.1：Begin 获取连接后不归还——Tx.dc 持有直到 Commit/Rollback
⑥ Stats 能告诉我们什么？	第 8.2：InUse/Idle/WaitCount/WaitDuration
⑦ 连接池参数如何配置？	第 9.1：MaxOpen = MySQL max_connections × 0.8 / 实例数

案例根因链条：

queryOrder 返回 rows 但未 Close
  → rows 持有的 driverConn 不归还
  → 每次查询泄漏一个连接（直到 MaxOpen 的 100 个）
  → InUse=100, Idle=0, WaitCount 开始增长
  → 新请求 db.Query → db.conn → 阻塞在 connRequestWait
  → 超时 → "connection pool exhausted"
  → MySQL 端显示 100 个 Sleep 连接——全部空闲但 Go 侧不归还

修复方案：

func queryOrder(ctx context.Context, orderID string) (*Order, error) {
    rows, err := db.QueryContext(ctx,
        "SELECT id, user_id, amount, status FROM orders WHERE id = ?", orderID)
    if err != nil {
        return nil, fmt.Errorf("query: %w", err)
    }
    defer rows.Close()  // ← 加这一行——根治泄漏

    if !rows.Next() {
        return nil, sql.ErrNoRows  // rows.Close 由 defer 执行
    }

    var o Order
    if err := rows.Scan(&o.ID, &o.UserID, &o.Amount, &o.Status); err != nil {
        return nil, fmt.Errorf("scan: %w", err)
    }
    return &o, nil
}

10.2 一次 Query 从连接获取到归还的完整路径

以 db.QueryContext(ctx, "SELECT ... WHERE id=?", 42) 为例：

1. db.QueryContext(ctx, sql, 42)
     → db.query(ctx, sql, args, strategyCachedOrNewConn)

2. db.conn(ctx, cachedOrNewConn):
     ├── 检查 freeConn 非空？→ 取出 conn (O(1))
     ├── 检查 conn 过期？→ 否——可用
     └── 返回 driverConn{ci: MySQL连接}

3. 在 driverConn 上执行查询:
     → dc.ci.QueryContext(ctx, "SELECT ... WHERE id=?", []driver.Value{42})
     → MySQL 驱动发送 SQL → 接收 ResultSet
     → 返回 driver.Rows

4. 封装为 sql.Rows:
     → rows := &Rows{dc: dc, rowsi: driverRows, ...}
     → 返回给调用方

5. 用户代码:
     for rows.Next() { rows.Scan(&v) }  ← 逐行读取
     rows.Close()  ← 关键！

6. rows.Close() → rows.close(err):
     ├── rs.rowsi.Close() ← 释放 MySQL ResultSet
     ├── 如果有 closeStmt → 归还 Stmt 到缓存
     └── db.putConn(rs.dc, nil):
           ├── 检查 connRequests 有等待者？→ 否
           ├── 检查 len(freeConn) < maxIdle？→ 是
           └── freeConn = append(freeConn, dc) ← 归还完成

连接回到空闲池——供下一个 Query 复用

10.3 设计哲学回扣

哲学 1：惰性连接——只为需要付费

sql.Open 不建立连接——第一个 Query 才惰性创建。这意味着配置错误的 DSN 在服务启动时不会暴露——直到第一次数据库访问。这不是 bug——是设计选择：启动速度和延迟暴露的权衡。补救措施：启动后调用 db.Ping() 强制建立第一个连接并验证。

哲学 2：连接池是不可见的基础设施

database/sql 的使用者不需要知道"连接池"的存在——只需要 db.Query → rows.Scan → rows.Close。但连接池的参数配置和泄漏防护是生产环境的必修课。Go 把连接池内置在标准库中——这个决定让千万 Go 服务免于"自己实现连接池"的地狱。

哲学 3：资源声明周期显式化——rows.Close 不可省略

Java 的 try-with-resources 让 ResultSet.close() 自动执行。Go 没有隐式资源管理——rows.Close() 必须显式调用。这不是语言缺陷——是 Go 的设计哲学：资源释放的控制流应该可见。但代价是忘记 Close 的后果（连接泄漏）完全由开发者承担。

哲学 4：接口抽象 + 驱动注册——解耦的可扩展性

database/sql 不依赖任何具体数据库——它只依赖 driver.Connector 接口。第三方驱动通过 init() 函数中的 sql.Register("mysql", &MySQLDriver{}) 注册自己。这种"抽象在前，实现在后"的设计让 Go 的数据库生态统一在单一 API 下——所有数据库使用相同的 db.Query 接口。

10.4 速查表

连接池参数：

参数	默认值	含义	设为 0 的含义
MaxOpenConns	0（无限制）	最大并发连接数	无限制
MaxIdleConns	2	空闲池最大连接数	不保留空闲连接
MaxLifetime	0（永不过期）	连接最大存活时间	永不过期
MaxIdleTime	0（永不过期）	空闲连接最大空闲时间（Go 1.15+）	永不过期

DB.Stats 诊断指标：

指标	含义	异常时指示
OpenConnections	已建立的连接数	> MaxOpen → 驱动 bug
InUse	正在使用中的连接数	持续 = MaxOpen → 泄漏或不足
Idle	空闲池中的连接数	= 0 且 InUse < MaxOpen → 连接在创建/销毁中
WaitCount	等待获取连接的次数	持续增长 → 连接池太小
WaitDuration	总等待时间	Avg > 10ms → 需要扩容

诊断命令：

# 运行时查看 Stats
curl http://localhost:6060/debug/db-stats
# 或通过 pprof 查看 database/sql 的 goroutine
curl http://localhost:6060/debug/pprof/goroutine?debug=2 | grep "database/sql"

# MySQL 端查看连接
SHOW PROCESSLIST;
SELECT COUNT(*) FROM information_schema.processlist;

# 查看 Go 服务的连接池状态——加一个 /debug/db 端点
# 代码注入：expvar.Publish("db-stats", expvar.Func(func() interface{} { return db.Stats() }))

---

下一篇：我们已经掌握了 database/sql 的连接池管理——惰性连接、空闲链表、事务独占、泄漏排查。下一步进入 32.测试与基准技巧——看看 Go 的 testing.T 和 testing.B 的底层实现、子测试的并行调度、以及 -count 基准测试的统计分析。