database/sql 是 Go 标准库里非常重要的包。它的 API 看起来不复杂，但初学者常常在几个地方踩坑：查询没有超时、忘记关闭 Rows、把 context.Background() 写在仓储层、扫描错误处理不完整。短期看只是代码能不能跑，长期看会影响连接池、请求取消和线上稳定性。
本文围绕一个“按状态查询任务列表”的接口，讲 QueryContext、RowContext、连接释放和超时传播。示例不绑定某个数据库驱动，重点是标准库用法。
从接口传下来的 context
HTTP handler 里天然有请求 context：
func (h *TaskHandler) List(w http.ResponseWriter, r *http.Request) {
status := r.URL.Query().Get("status")
tasks, err := h.store.ListByStatus(r.Context(), status)
if err != nil {
http.Error(w, "query tasks failed", http.StatusInternalServerError)
return
}
writeJSON(w, tasks)
}
仓储层不要自己创建 context.Background()：
func (s *Store) ListByStatus(ctx context.Context, status string) ([]Task, error) {
// 使用传入 ctx
}
这样客户端断开、网关取消、服务超时都能传到数据库调用。如果仓储层偷偷用 background，上层已经不需要结果了，数据库查询还会继续占着连接和资源。
使用 QueryContext
查询多行数据：
func (s *Store) ListByStatus(ctx context.Context, status string) ([]Task, error) {
rows, err := s.db.QueryContext(ctx, `
SELECT id, title, status, created_at
FROM tasks
WHERE status = ?
ORDER BY id DESC
LIMIT 100
`, status)
if err != nil {
return nil, fmt.Errorf("query tasks: %w", err)
}
defer rows.Close()
var tasks []Task
for rows.Next() {
var task Task
if err := rows.Scan(&task.ID, &task.Title, &task.Status, &task.CreatedAt); err != nil {
return nil, fmt.Errorf("scan task: %w", err)
}
tasks = append(tasks, task)
}
if err := rows.Err(); err != nil {
return nil, fmt.Errorf("iterate tasks: %w", err)
}
return tasks, nil
}
这里有三个细节。第一，QueryContext 使用传入 context。第二，defer rows.Close() 必须写，确保连接归还给连接池。第三，循环结束后要检查 rows.Err()，因为迭代过程中也可能出错。
单行查询和 ErrNoRows
查询单个任务可以用 QueryRowContext：
func (s *Store) GetTask(ctx context.Context, id int64) (Task, error) {
var task Task
err := s.db.QueryRowContext(ctx, `
SELECT id, title, status, created_at
FROM tasks
WHERE id = ?
`, id).Scan(&task.ID, &task.Title, &task.Status, &task.CreatedAt)
if err != nil {
if errors.Is(err, sql.ErrNoRows) {
return Task{}, ErrTaskNotFound
}
return Task{}, fmt.Errorf("get task: %w", err)
}
return task, nil
}
不要把 sql.ErrNoRows 直接漏到 handler。仓储层可以把它转换成业务错误，比如 ErrTaskNotFound。handler 再把业务错误映射成 404：
if errors.Is(err, ErrTaskNotFound) {
http.Error(w, "task not found", http.StatusNotFound)
return
}
这样 HTTP 层不需要知道底层用了 SQL。
给数据库调用设置局部超时
如果上层请求允许 3 秒，但某个查询最多只能跑 500 毫秒，可以在仓储层基于传入 context 派生：
func (s *Store) ListByStatus(ctx context.Context, status string) ([]Task, error) {
ctx, cancel := context.WithTimeout(ctx, 500*time.Millisecond)
defer cancel()
rows, err := s.db.QueryContext(ctx, `SELECT id, title FROM tasks WHERE status = ?`, status)
// ...
}
注意是从 ctx 派生，不是从 context.Background() 派生。这样上层取消仍然有效。局部超时不要随便写死在很多地方，最好来自配置或集中常量，否则排查慢查询时会不知道哪个层提前取消。
连接泄漏的表现
忘记 rows.Close() 时，连接可能无法及时归还连接池。线上表现可能是请求越来越慢，最后报连接池等待超时。这个问题不一定在本地复现，因为本地并发低，数据库也快。
一个常见错误是提前 return 时漏掉关闭：
rows, err := db.QueryContext(ctx, query)
if err != nil {
return err
}
for rows.Next() {
if somethingBad {
return errors.New("bad") // 如果没有 defer rows.Close，就泄漏
}
}
所以拿到 rows 后尽快 defer rows.Close() 是好习惯。即使后面扫描失败或提前返回，也能释放资源。
不要拼接用户输入
查询条件要用参数，不要字符串拼接：
// 不推荐
query := "SELECT id FROM tasks WHERE status = '" + status + "'"
使用占位符：
rows, err := db.QueryContext(ctx,
"SELECT id FROM tasks WHERE status = ?",
status,
)
不同数据库驱动占位符不同，PostgreSQL 常见 $1，MySQL 和 SQLite 常见 ?。无论占位符长什么样，原则都是一样的：用户输入作为参数传给驱动，不要直接拼进 SQL 字符串。
查询结果要有限制
入门示例常常忘记分页：
SELECT id, title FROM tasks WHERE status = ?
如果表里有几十万行，这个接口会很危险。即使只是后台页面，也应该加 LIMIT，并设计分页或游标：
SELECT id, title
FROM tasks
WHERE status = ? AND id < ?
ORDER BY id DESC
LIMIT 100
数据库上下文能取消慢查询，但更好的方式是不要发起过大的查询。超时是保护网，查询设计才是根本。
常见 Pitfall：rows.Close 的时机
defer rows.Close() 是最常用的方式，但不是唯一方式。以下两种写法都有问题：
问题一：defer 之前提前 return
func bad() {
rows, err := db.QueryContext(ctx, query)
if err != nil {
return nil, err // 此时 rows 可能为 nil，但 err != nil 时直接 return 没问题
}
// 如果这里忘记 defer rows.Close()，后面任何一个 return 都会泄漏
// ...
return result, nil
}
问题二：rows.Next() 返回 false 后没有检查 rows.Err()
for rows.Next() {
// ...
}
// 忘记检查 rows.Err()，循环中可能发生了网络中断
正确的完整模式：
rows, err := db.QueryContext(ctx, query, args...)
if err != nil {
return nil, err
}
defer rows.Close()
for rows.Next() {
if err := rows.Scan(&...); err != nil {
return nil, err
}
}
if err := rows.Err(); err != nil {
return nil, err
}
这四步缺一不可：Query、defer Close、Next + Scan、最后检查 Err。
批量插入的 context 使用
批量插入是另一个常见场景。标准库的 ExecContext 不支持一次执行多条语句（这取决于驱动），但可以用 sql.NullString 或参数化批量插入：
func (s *Store) BulkInsertTasks(ctx context.Context, tasks []Task) error {
if len(tasks) == 0 {
return nil
}
const placeholdersPerRow = 4
placeholders := make([]string, 0, len(tasks))
args := make([]any, 0, len(tasks)*placeholdersPerRow)
for i, t := range tasks {
placeholders = append(placeholders, fmt.Sprintf("($%d,$%d,$%d,$%d)",
i*placeholdersPerRow+1, i*placeholdersPerRow+2,
i*placeholdersPerRow+3, i*placeholdersPerRow+4))
args = append(args, t.ID, t.Title, t.Status, t.CreatedAt)
}
query := "INSERT INTO tasks (id, title, status, created_at) VALUES " + strings.Join(placeholders, ", ")
_, err := s.db.ExecContext(ctx, query, args...)
return err
}
PostgreSQL 批量插入常用 VALUES ($1,$2), ($3,$4) 语法，MySQL 也有类似方式。注意这里占位符数量不要超出驱动限制（如 PostgreSQL 默认 65535 个参数）。如果批量数据量非常大，应该分批次插入，每批控制在一个合理数量内（如 1000 条）。
事务的 context 传递
事务也需要传递 context，这样超时和取消才能传导到事务内的所有操作：
func (s *Store) Transfer(ctx context.Context, from, to int64, amount int64) error {
tx, err := s.db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelReadCommitted})
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 = ?", amount, from); err != nil {
return fmt.Errorf("debit: %w", err)
}
if _, err := tx.ExecContext(ctx,
"UPDATE accounts SET balance = balance + ? WHERE id = ?", amount, to); err != nil {
return fmt.Errorf("credit: %w", err)
}
return tx.Commit()
}
BeginTx 接受 context，要养成和 QueryContext/ExecContext 一样的习惯。事务内的所有操作都用同一个 tx 对象调用对应的 Context 版本方法。
Prepared Statement 的复用
Prepared Statement 能提升重复执行同一条 SQL 的性能，尤其当参数变化但语句结构不变时：
func (s *Store) ListByStatus(ctx context.Context, status string) ([]Task, error) {
const query = `SELECT id, title, status, created_at FROM tasks WHERE status = ? ORDER BY id DESC LIMIT 100`
stmt, err := s.db.PrepareContext(ctx, query)
if err != nil {
return nil, err
}
defer stmt.Close()
rows, err := stmt.QueryContext(ctx, status)
if err != nil {
return nil, err
}
defer rows.Close()
// ... 后续 Scan 逻辑
}
但要注意 Prepared Statement 不是无代价的。每次 Prepare 都要和数据库交互一次。如果把这个函数放在循环里反复调用，Prepared Statement 反而会成为性能瓶颈。更好的做法是把 Prepare 提升到更高层级，或在程序启动时预编译。
FAQ
Q: QueryRow 和 QueryRowContext 的区别是什么？
QueryRow 内部使用 context.Background()，不支持超时和取消。所有数据库操作都应该用带 Context 的版本。
Q: rows.Err() 和循环内 Scan 错误有什么不同？
Scan 错误发生在把数据库列值映射到 Go 变量时，比如类型不匹配。rows.Err() 发生在迭代过程中，比如网络中断、连接被数据库端关闭。两者都要检查。
Q: 什么时候用 db.PingContext？
sql.Open 只是初始化驱动，不会立即建立连接。如果你需要确认数据库真的可连接，调用 db.PingContext(ctx)。它在应用启动检查或健康检查里常用。
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
if err := db.PingContext(ctx); err != nil {
log.Fatal("database unreachable:", err)
}
Q: sql.TxOptions 的隔离级别应该怎么选？
| 隔离级别 | 用途 |
|---|---|
ReadUncommitted | 极少使用，除非特殊需求 |
ReadCommitted （默认） | 大多数业务场景 |
RepeatableRead | 需要防止不可重复读 |
Serializable | 强一致性要求，性能代价大 |
Q: db.SetMaxOpenConns 这些设置重要吗？
非常重要。默认值通常不够合理，生产环境应该显式设置：
db.SetMaxOpenConns(25)
db.SetMaxIdleConns(5)
db.SetConnMaxLifetime(5 * time.Minute)
MaxOpenConns：连接池最大连接数，超过后新请求会排队等待MaxIdleConns：空闲连接保留数量ConnMaxLifetime：连接最长存活时间，防止连接被数据库端过期后继续使用
小结
Go 的 database/sql 使用 context 时，核心原则是从入口传递 ctx，在查询里使用 QueryContext 或 QueryRowContext，拿到 Rows 后及时关闭，循环后检查 rows.Err()。单行不存在要转换成业务错误，不要把 SQL 细节泄漏到 HTTP 层。
数据库代码看似离用户很远，但它决定了请求取消、连接池和慢查询的行为。初学阶段把这些小习惯养成，后面写服务会稳很多。
真实项目用例
在实际团队协作中，下面是几个推荐的工作流：
代码审查清单
- 函数是否处理了所有 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 相关面试，以下概念是高频考点：
- goroutine 和线程的区别
- channel 的缓冲和非缓冲用法
- defer 的执行顺序和与返回值的关系
- map 的并发不安全性和解决方案
- interface 的隐式实现和类型断言
- slice 的底层数组和 append 机制
- GC 的基本原理和调优参数
- context 的使用场景和超时控制
- error 的包装和 errors.Is/errors.As
- 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 泄漏。
常见坑与避坑指南
- 不要信任用户输入：无论表单、JSON、Cookie 还是 HTTP Header，都当作不可信数据处理，做校验和转义。
- 资源要释放：文件、数据库连接、HTTP 响应体都要及时关闭。
defer是一个好习惯。 - 不要忽略错误：即使
defer file.Close()可能返回错误，至少记录日志。完全忽略错误是 bug 的温床。 - 不要滥用 goroutine：每个 goroutine 都要有明确的退出路径。使用
sync.WaitGroup和context管理生命周期。 - 不要硬编码配置：端口、路径、超时时间、密钥都应该从配置读取，让程序适应不同环境。
- 不要过早优化：先让代码正确和可读，再用 benchmark 和 profile 找到真正的热点。
延伸阅读与实践建议
读完本文后，建议完成以下实践：
- 把文中所有示例代码在自己的机器上跑一遍
- 给示例代码补充错误分支的测试用例
- 尝试基于本文内容构建一个小型完整项目
- 在 review 他人的 Go 代码时，检查本文提到的边界是否被覆盖
- 订阅 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 语言的设计简洁但不简单，掌握它需要持续的实践和反思。希望这篇文章能成为你学习道路上的一个可靠参考。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。