sqlContext取消超时查询

数据库查询要能被取消，关键不是给 SQL 字符串外面套一个定时器，而是从请求的 context.Context 派生带超时的上下文，再传给 QueryContext、QueryRowContext 或 ExecContext。这样查询同时受上游请求取消和本地超时约束。需要注意，取消信号能否及时传到数据库服务器，还取决于所用驱动是否正确实现 Context 接口；ctx.Err() 也不能证明事务已经自动回滚。

最小可靠写法是“父 Context + WithTimeout + defer cancel + 带 Context 的 SQL 方法 + Rows 收尾”。超时后记录可检索的分类信息，驱动不支持取消时再从连接池和数据库侧补上防护。

先把查询边界交给 Context

把查询包在 context.WithTimeout 中，可以限制单次数据库操作占用的时间。超时预算应小于接口整体超时，给序列化、日志和响应留出余量；不要在函数内部重新使用 context.Background()，否则调用方断开连接时取消链会被切断。

// QueryUser 在请求上下文的基础上增加数据库查询预算。
func QueryUser(ctx context.Context, db *sql.DB, id int64) (*User, error) {
	queryCtx, cancel := context.WithTimeout(ctx, 800*time.Millisecond)
	defer cancel() // 及时释放定时器和上下文关联资源

	var user User
	err := db.QueryRowContext(queryCtx, `
		SELECT id, name, status
		FROM users
		WHERE id = ?`, id).Scan(&user.ID, &user.Name, &user.Status)
	if err != nil {
		// QueryRowContext 的读取错误在 Scan 时返回，先保留超时原因。
		if errors.Is(queryCtx.Err(), context.DeadlineExceeded) {
			return nil, fmt.Errorf("user query timeout: %w", err)
		}
		if errors.Is(queryCtx.Err(), context.Canceled) {
			return nil, fmt.Errorf("user query canceled: %w", err)
		}
		if errors.Is(err, sql.ErrNoRows) {
			return nil, fmt.Errorf("user %d not found: %w", id, err)
		}
		return nil, fmt.Errorf("query user %d: %w", id, err)
	}
	return &user, nil
}

这里的占位参数也承担了安全边界：用户输入作为参数传入，不要用字符串拼接 SQL。QueryRowContext 的错误会延迟到 Scan，所以只检查调用返回值是不够的。

区分超时、上游取消与数据库错误

排查时先看派生 Context 的状态，再结合原始错误。DeadlineExceeded 通常说明本地预算到期，Canceled 常见于客户端断开、上游主动取消或业务提前结束；sql.ErrNoRows 是查询结果语义，不应被当成超时。

// classifyQueryError 把可观测的取消原因分成稳定类别。
func classifyQueryError(queryCtx, parent context.Context, err error) string {
	if errors.Is(queryCtx.Err(), context.DeadlineExceeded) {
		return "db_timeout"
	}
	if errors.Is(queryCtx.Err(), context.Canceled) || errors.Is(parent.Err(), context.Canceled) {
		return "request_canceled"
	}
	if errors.Is(err, sql.ErrNoRows) {
		return "not_found"
	}
	return "db_error"
}

日志建议记录分类、耗时、SQL 模板标识和连接池指标，不要把完整用户输入直接写入日志。若要进一步判断驱动是否支持取消，应阅读驱动文档或测试其 QueryContext 行为，而不是只看 Go 协程是否返回。

连接池和 Rows 收尾不能省

查询多行数据时，超时可能发生在调用阶段，也可能发生在遍历阶段。无论哪一种，都要关闭结果集并检查 rows.Err()；提前结束遍历时尤其不能只靠垃圾回收等待连接归还。

// ListActiveUsers 演示多行查询的关闭和迭代错误处理。
func ListActiveUsers(ctx context.Context, db *sql.DB) ([]User, error) {
	queryCtx, cancel := context.WithTimeout(ctx, 1200*time.Millisecond)
	defer cancel() // 无论查询成功或失败都结束本次超时预算

	rows, err := db.QueryContext(queryCtx,
		`SELECT id, name, status FROM users WHERE status = ?`, "active")
	if err != nil {
		return nil, fmt.Errorf("list active users: %w", err)
	}
	defer rows.Close() // 释放结果集并尽快归还连接

	users := make([]User, 0, 16)
	for rows.Next() {
		var user User
		if err := rows.Scan(&user.ID, &user.Name, &user.Status); 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
}

如果这是事务中的写操作，超时后要明确执行回滚并处理回滚错误；Context 取消并不等于业务层已经完成回滚。长查询还应配合数据库侧的执行超时或资源限额，形成双层保护。

生产环境的安全防护清单

• 接口超时、数据库超时和重试预算分层设置，重试前先判断原请求是否已取消。
• 优先使用参数占位符，固定 SQL 模板；对动态排序字段采用白名单映射，不让用户输入直接进入 SQL。
• 监控 WaitCount、InUse、Idle 和超时分类，连接池持续打满时先查慢查询与 Rows 泄漏。
• 把驱动是否支持 QueryerContext、ExecerContext 纳入升级测试，不能只在应用层假设取消一定会中断服务器执行。

我在工程里更愿意把“取消”当作资源回收协议，而不是错误文案：调用链传递 Context，数据库方法接收 Context，结果集主动关闭，日志保存原因，事务明确回滚。四层都做到，超时才不会只变成一条看似友好的报错。

常见问题

只调用 Query 而不调用 QueryContext 会怎样？

普通 Query 使用内部的背景上下文，无法继承请求取消。需要超时或上游取消时，应改用带 Context 的方法。

超时返回后数据库一定停止执行了吗？

不一定。应用侧已经收到取消，但实际中断能力取决于驱动和数据库实现；关键写操作仍需用数据库侧超时、限流和事务策略兜底。