golang

Go 数据库入门：用 database/sql 写清楚的查询和事务

本文讲解 Go 标准库 database/sql 的连接池、查询、Scan、Exec、事务和 context 使用，帮助初学者理解数据库访问的基本边界。

Leeting Yan 8 分钟阅读 3679 字

数据库代码要先写清楚，再谈封装

Go 做后端服务绕不开数据库。很多人会直接找 ORM，但在理解 ORM 之前，最好先用标准库 database/sql 写几次查询和事务。它能让你看清楚数据库访问的基本动作：打开连接池、执行 SQL、扫描结果、处理空值、使用 context、提交或回滚事务。

database/sql 不是具体数据库驱动，而是一套统一接口。你需要配合 MySQL、PostgreSQL、SQLite 等驱动使用。本文示例用通用 SQL 写法说明概念，不绑定某个驱动细节。真实项目里，驱动导入和占位符可能略有不同，比如 PostgreSQL 常用 $1，MySQL 和 SQLite 常用 ?。

重点不是背 API，而是建立边界：Handler 不直接拼 SQL，查询函数返回明确结构体，事务范围尽量小，外部传入 context.Context，错误要带上下文。

打开数据库连接池

典型代码：

db, err := sql.Open("mysql", dsn)
if err != nil {
	return err
}
defer db.Close()

注意 sql.Open 并不一定立刻建立连接，它主要创建连接池句柄。通常还要 PingContext 验证：

ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()

if err := db.PingContext(ctx); err != nil {
	return fmt.Errorf("ping database: %w", err)
}

配置连接池：

db.SetMaxOpenConns(20)
db.SetMaxIdleConns(10)
db.SetConnMaxLifetime(30 * time.Minute)

这些参数没有统一答案，要看数据库能力和服务负载。入门阶段先知道 *sql.DB 是连接池，不是单个连接。它应该在程序启动时创建，整个服务复用，不要每个请求都 sql.Open。

查询单行

定义用户结构体：

type User struct {
	ID    int64
	Name  string
	Email string
}

查询函数：

func FindUserByID(ctx context.Context, db *sql.DB, id int64) (User, error) {
	const query = `
SELECT id, name, email
FROM users
WHERE id = ?
`

	var user User
	err := db.QueryRowContext(ctx, query, id).Scan(&user.ID, &user.Name, &user.Email)
	if err != nil {
		if errors.Is(err, sql.ErrNoRows) {
			return User{}, fmt.Errorf("user not found")
		}
		return User{}, fmt.Errorf("query user %d: %w", id, err)
	}

	return user, nil
}

QueryRowContext 查询一行，Scan 把列扫描到变量地址。列顺序必须和 Scan 参数顺序一致。SQL 里最好显式列名，不要 SELECT *，否则表结构变化容易影响代码。

如果用户不存在，Scan 返回 sql.ErrNoRows。这是正常业务情况，应该单独处理。

查询多行

func ListUsers(ctx context.Context, db *sql.DB, limit int) ([]User, error) {
	const query = `
SELECT id, name, email
FROM users
ORDER BY id DESC
LIMIT ?
`

	rows, err := db.QueryContext(ctx, query, limit)
	if err != nil {
		return nil, fmt.Errorf("query users: %w", err)
	}
	defer rows.Close()

	users := make([]User, 0)
	for rows.Next() {
		var user User
		if err := rows.Scan(&user.ID, &user.Name, &user.Email); err != nil {
			return nil, fmt.Errorf("scan user: %w", err)
		}
		users = append(users, user)
	}

	if err := rows.Err(); err != nil {
		return nil, fmt.Errorf("iterate users: %w", err)
	}

	return users, nil
}

多行查询有三个容易忘的点：defer rows.Close()，循环里检查 Scan，循环后检查 rows.Err()。最后一步很重要，因为遍历过程中可能发生错误。

返回空列表时，建议返回空切片而不是 nil：

if users == nil {
	users = []User{}
}

这对 JSON API 更友好。

插入和更新

插入：

func CreateUser(ctx context.Context, db *sql.DB, name, email string) (int64, error) {
	const query = `
INSERT INTO users (name, email)
VALUES (?, ?)
`

	result, err := db.ExecContext(ctx, query, name, email)
	if err != nil {
		return 0, fmt.Errorf("insert user: %w", err)
	}

	id, err := result.LastInsertId()
	if err != nil {
		return 0, fmt.Errorf("get inserted id: %w", err)
	}
	return id, nil
}

更新：

func UpdateUserName(ctx context.Context, db *sql.DB, id int64, name string) error {
	const query = `UPDATE users SET name = ? WHERE id = ?`

	result, err := db.ExecContext(ctx, query, name, id)
	if err != nil {
		return fmt.Errorf("update user name: %w", err)
	}

	affected, err := result.RowsAffected()
	if err != nil {
		return fmt.Errorf("get affected rows: %w", err)
	}
	if affected == 0 {
		return fmt.Errorf("user not found")
	}

	return nil
}

永远不要用字符串拼接用户输入来构造 SQL：

query := "SELECT * FROM users WHERE email = '" + email + "'"

应该使用参数占位符，让驱动处理转义和绑定。这是防 SQL 注入的基本要求。

事务：要么一起成功，要么一起失败

假设转账：从 A 扣钱，给 B 加钱。两个更新必须在同一个事务里。

func Transfer(ctx context.Context, db *sql.DB, fromID, toID int64, cents int64) error {
	tx, err := db.BeginTx(ctx, nil)
	if err != nil {
		return fmt.Errorf("begin tx: %w", err)
	}
	defer tx.Rollback()

	if _, err := tx.ExecContext(ctx,
		`UPDATE accounts SET balance = balance - ? WHERE id = ?`,
		cents, fromID,
	); err != nil {
		return fmt.Errorf("decrease balance: %w", err)
	}

	if _, err := tx.ExecContext(ctx,
		`UPDATE accounts SET balance = balance + ? WHERE id = ?`,
		cents, toID,
	); err != nil {
		return fmt.Errorf("increase balance: %w", err)
	}

	if err := tx.Commit(); err != nil {
		return fmt.Errorf("commit tx: %w", err)
	}
	return nil
}

defer tx.Rollback() 看起来奇怪，因为成功时已经 Commit。提交后再 Rollback 会返回错误，但通常可以忽略。它的作用是保证中途任何 return 都会回滚。

事务里不要做耗时外部调用，比如 HTTP 请求或发送邮件。事务应该尽量短，只包住必须一致的数据库操作。

小结

database/sql 的核心动作不多：启动时创建 *sql.DB 连接池，使用 QueryRowContext 查单行，QueryContext 查多行，ExecContext 执行写操作，事务用 BeginTx、Commit、Rollback。所有数据库调用都应该接收 context，并为错误加上业务上下文。

数据库代码最重要的是清楚和安全。显式列名，参数化查询，关闭 rows，检查 rows.Err()，处理 sql.ErrNoRows，事务范围保持小。这些习惯比一开始就套复杂封装更重要。

等你熟悉了标准库，再去使用 ORM 或查询构建器，会更知道它们帮你省了什么，也更容易判断它们是否适合当前项目。

常见问题与解答

sql.DB 每个请求都要 Open 吗？

不要。sql.DB 是连接池，应该在程序启动时创建，整个生命周期复用。每个 handler 里使用同一个 *sql.DB。

查询时 sql.ErrNoRows 怎么处理？

sql.ErrNoRows 是正常业务情况，不要打 error 日志。通常应该返回明确的业务错误，比如 “用户不存在”。

用什么占位符？MySQL 用 ?，PostgreSQL 用 $1。

驱动不同占位符不同：MySQL、SQLite 用 ?，PostgreSQL 用 $1, $2。如果你用抽象层（如 sqlx），它会帮你转换。

连接池参数调优

db.SetMaxOpenConns(25)        // 最大打开连接数
db.SetMaxIdleConns(25)        // 最大空闲连接数
db.SetConnMaxLifetime(5 * time.Minute) // 连接最大生命周期
db.SetConnMaxIdleTime(1 * time.Minute) // 连接最大空闲时间

如果 goroutine 数很多，但 MaxOpenConns 很小，很多 goroutine 会卡在等连接上。要让并发和连接池匹配。

批量插入

func BatchInsert(ctx context.Context, db *sql.DB, users []User) error {
    const batchSize = 500
    for i := 0; i < len(users); i += batchSize {
        end := i + batchSize
        if end > len(users) {
            end = len(users)
        }
        if err := insertBatch(ctx, db, users[i:end]); err != nil {
            return err
        }
    }
    return nil
}

批量减少网络往返，但要注意数据库对单条 SQL 长度的限制。

SQL 注入防护

永远用参数化查询：

// BAD
db.Query("SELECT * FROM users WHERE name = '" + name + "'")

// GOOD
db.Query("SELECT * FROM users WHERE name = ?", name)

参数化查询能防御绝大多数 SQL 注入攻击。

实践练习

完成以下练习以巩固所学知识：

  1. 阅读 Go 官方文档相关章节
  2. 编写一个完整的示例程序
  3. 为示例程序编写单元测试
  4. 使用 go test 和 go benchmark 验证实现
  5. 尝试优化内存分配和运行时间

推荐阅读

真实项目用例

在实际团队协作中，下面是几个推荐的工作流：

代码审查清单

  • 函数是否处理了所有 error 返回值
  • 并发代码是否有明确的退出路径和 WaitGroup
  • 用户输入是否经过校验和清洗
  • 敏感配置是否通过环境变量或加密存储注入
  • 测试是否覆盖了正常路径和至少一个错误路径
  • 日志是否包含足够的上下文信息但不泄露敏感数据
  • 接口设计是否符合最小接口原则

CI/CD 集成建议

  • 每次提交前运行 go fmt ./...
  • CI 中运行 go vet ./... 和 golangci-lint run
  • 单元测试使用 go test -race ./... 检测数据竞争
  • 关键路径的 benchmark 加入回归测试
  • 使用 go mod verify 确保依赖完整性

性能调优检查点

  • 使用 pprof 分析 CPU 和内存使用
  • 关注 benchmark 的 allocs/op，减少高频路径的堆分配
  • 检查数据库查询是否使用索引
  • 确认外部 HTTP 调用有合理的超时设置
  • 缓存热点数据，但注意缓存一致性和过期策略

面试高频考点

如果你正在准备 Go 相关面试，以下概念是高频考点：

  1. goroutine 和线程的区别
  2. channel 的缓冲和非缓冲用法
  3. defer 的执行顺序和与返回值的关系
  4. map 的并发不安全性和解决方案
  5. interface 的隐式实现和类型断言
  6. slice 的底层数组和 append 机制
  7. GC 的基本原理和调优参数
  8. context 的使用场景和超时控制
  9. error 的包装和 errors.Is/errors.As
  10. sync.Mutex vs sync.RWMutex vs atomic

掌握这些概念意味着你具备了独立开发 Go 服务的基础能力。继续在实际项目中磨练，你会越来越熟悉 Go 的工程风格和最佳实践。

常见问题（FAQ）

Q: 这个特性在实际项目中真的有用吗？
A: 是的。本文介绍的技术来源于真实后端开发场景。无论是标准库工具还是工程实践，在日常服务开发中都会反复用到。

Q: Go 版本会影响示例代码吗？
A: 本文代码主要针对 Go 1.20+ 编写。较新版本（如 1.22、1.23）的语法可能有微调，但核心概念保持不变。如有版本差异，文中会特别说明。

Q: 学习 Go 应该先学标准库还是直接上框架？
A: 强烈建议先学标准库。框架是对标准库的封装和扩展。只有理解了标准库的能力边界，才能正确选择和使用框架，也才能在框架出问题时快速定位。

Q: 代码里的错误处理为什么都是显式的 if err != nil？
A: 这是 Go 的设计哲学。显式错误处理让失败路径清晰可见，不会隐藏在任何 try-catch 之后。习惯了之后，你会发现这种写法实际上降低了排查错误的难度。

Q: 并发相关代码怎么测试？
A: 使用 Go 内置的 -race 标志检测数据竞争：go test -race ./...。结合 sync.WaitGroup 和 context.WithTimeout 编写有退出路径的并发测试，避免 goroutine 泄漏。

常见坑与避坑指南

  1. 不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
  2. 资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。defer 是一个好习惯。
  3. 不要忽略错误：即使 defer file.Close() 可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。
  4. 不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用 sync.WaitGroup 和 context 管理生命周期。
  5. 不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
  6. 不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。

延伸阅读与实践建议

读完本文后，建议完成以下实践：

  1. 把文中所有示例代码在自己的机器上跑一遍
  2. 给示例代码补充错误分支的测试用例
  3. 尝试基于本文内容构建一个小型完整项目
  4. 在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
  5. 订阅 Go 官方博客，关注语言演进和最佳实践更新

参考资源

  • Go 官方网站：https://go.dev/
  • Go 标准库文档：https://pkg.go.dev/std
  • Go by Example：https://gobyexample.com/
  • Effective Go：https://go.dev/doc/effective_go
  • Go 常见问题：https://go.dev/doc/faq
  • Go 项目实战社区案例和开源项目源码

本文力求在讲解技术细节的同时兼顾工程实用性。Go 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「golang」更多文章

  1. Go 日志与可观测性：slog、结构化日志与 OpenTelemetry 集成
  2. Go 测试与基准实战：表驱动、Mock、Fuzz 与 pprof 基准分析
  3. Go 错误处理最佳实践：error 包装、errors.Is/As 与错误码体系