golang-database

Name: golang-database
Author: samber

Go数据库最佳实践

Go的database/sql为数据库访问提供了坚实基础。在其上使用sqlx或pgx以提高易用性——绝不使用ORM。

使用sqlx或pgx时，请参考库的官方文档和代码示例以获取当前API签名。

最佳实践总结

使用sqlx或pgx，而非ORM —— ORM隐藏SQL，生成不可预测的查询，使调试更困难
查询必须使用参数化占位符——切勿将用户输入拼接到SQL字符串中
上下文必须传递给所有数据库操作——使用*Context方法变体（QueryContext、ExecContext、GetContext）
sql.ErrNoRows必须显式处理——使用errors.Is区分“未找到”和真实错误
行迭代后必须关闭——在QueryContext调用后立即使用defer rows.Close()
切勿对不返回行的语句使用db.Query——Query返回必须关闭的*Rows；如果忘记，连接会泄漏回池中。应使用db.Exec
对多语句操作使用事务 —— 将相关写入包装在BeginTxx/Commit中
在读取要修改的数据时使用SELECT ... FOR UPDATE —— 防止竞态条件
设置自定义隔离级别 —— 当默认的READ COMMITTED不足时（例如，金融操作使用可序列化）
使用指针字段（*string、*int）或sql.NullXxx类型处理可空列
必须配置连接池 —— SetMaxOpenConns、SetMaxIdleConns、SetConnMaxLifetime、SetConnMaxIdleTime
使用外部工具进行迁移 —— golang-migrate或Flyway，绝不使用手写或AI生成的迁移SQL
批量操作使用合理大小 —— 不要逐行（往返次数过多），也不要一次数百万（锁和内存问题）
绝不创建或修改数据库模式 —— 在玩具数据上看起来正确的模式可能会在生产负载下产生热点、锁争用或缺失索引。模式设计需要理解数据量、访问模式和生产约束，AI不具备这些
避免隐藏的SQL特性 —— 不要在应用程序代码中依赖触发器、视图、物化视图、存储过程或行级安全

库选择

库	最适合	结构体扫描	PostgreSQL专用
`database/sql`	可移植性，最小依赖	手动`Scan`	否
`sqlx`	多数据库项目	`StructScan`	否
`pgx`	PostgreSQL（快30-50%）	`pgx.RowToStructByName`	是（COPY、LISTEN、数组）
GORM/ent	避免	魔法	抽象化

为什么不用ORM：

不可预测的查询生成——代码中看不到的N+1问题
魔法钩子和回调（BeforeCreate、AfterUpdate）使调试更困难
模式迁移与应用程序代码耦合
学习ORM API比学习SQL更难，且抽象层会泄漏

参数化查询

// ✗ 非常糟糕——SQL注入漏洞
query := fmt.Sprintf("SELECT * FROM users WHERE email = '%s'", email)

// ✓ 好——参数化（PostgreSQL）
var user User
err := db.GetContext(ctx, &user, "SELECT id, name, email FROM users WHERE email = $1", email)

// ✓ 好——参数化（MySQL）
err := db.GetContext(ctx, &user, "SELECT id, name, email FROM users WHERE email = ?", email)

动态IN子句

query, args, err := sqlx.In("SELECT * FROM users WHERE id IN (?)", ids)
if err != nil {
    return fmt.Errorf("构建IN子句: %w", err)
}
query = db.Rebind(query) // 根据驱动调整占位符
err = db.SelectContext(ctx, &users, query, args...)

动态列名

切勿从用户输入中插值列名。使用白名单：

allowed := map[string]bool{"name": true, "email": true, "created_at": true}
if !allowed[sortCol] {
    return fmt.Errorf("无效的排序列: %s", sortCol)
}
query := fmt.Sprintf("SELECT id, name, email FROM users ORDER BY %s", sortCol)

更多注入预防模式，请参见samber/cc-skills-golang@golang-security技能。

结构体扫描和可空列

对sqlx使用db:"column_name"标签，对pgx使用pgx.CollectRows配合pgx.RowToStructByName。使用指针字段（*string、*time.Time）处理可空列——它们能干净地处理扫描和JSON序列化。参见扫描参考获取所有方法的示例。

错误处理

func GetUser(id string) (*User, error) {
    var user User

    err := db.GetContext(ctx, &user, "SELECT id, name FROM users WHERE id = $1", id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, ErrUserNotFound // 转换为领域错误
        }
        return nil, fmt.Errorf("查询用户 %s: %w", id, err)
    }

    return &user, nil
}

或者：

func GetUser(id string) (u *User, exists bool, err error) {
    var user User

    err := db.GetContext(ctx, &user, "SELECT id, name FROM users WHERE id = $1", id)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return nil, false, nil // “无用户”不是技术错误，而是领域错误
        }
        return nil, false, fmt.Errorf("查询用户 %s: %w", id, err)
    }

    return &user, true, nil
}

始终关闭行

rows, err := db.QueryContext(ctx, "SELECT id, name FROM users")
if err != nil {
    return fmt.Errorf("查询用户: %w", err)
}
defer rows.Close() // 防止连接泄漏

for rows.Next() {
    // ...
}
if err := rows.Err(); err != nil { // 迭代后始终检查
    return fmt.Errorf("迭代用户: %w", err)
}

常见数据库错误模式

错误	如何检测	操作
未找到行	`errors.Is(err, sql.ErrNoRows)`	返回领域错误
唯一约束	检查驱动特定错误码	返回冲突错误
连接被拒绝	`db.PingContext`返回`err != nil`	快速失败，记录日志，带退避重试
序列化失败	PostgreSQL错误码`40001`	重试整个事务
上下文取消	`errors.Is(err, context.Canceled)`	停止处理，传播

上下文传播

始终使用*Context方法变体来传播截止时间和取消：

// ✗ 糟糕——无上下文，即使客户端断开连接，查询也会运行完成
db.Query("SELECT ...")

// ✓ 好——尊重上下文取消和超时
db.QueryContext(ctx, "SELECT ...")

有关上下文的深入模式，请参见samber/cc-skills-golang@golang-context技能。

事务、隔离级别和锁

有关事务模式、隔离级别、SELECT FOR UPDATE和锁变体，请参见事务。

连接池

db.SetMaxOpenConns(25)              // 限制总连接数
db.SetMaxIdleConns(10)              // 保持热连接就绪
db.SetConnMaxLifetime(5 * time.Minute)  // 回收过期连接
db.SetConnMaxIdleTime(1 * time.Minute)  // 更快关闭空闲连接

有关大小调整指南和公式，请参见数据库性能。