database/sql 查询上下文取消后的 rows 状态

查询已经开始，业务也拿到了几行数据，但请求的 context 在中途被取消时，rows.Next() 只返回 false，这并不等于“数据库正常返回了最后一行”。在 database/sql 中，循环结束后的真正结论要交给 rows.Err()；资源则由 rows.Close() 收口。

先判断 rows 为什么提前结束

最容易误判的代码是：循环结束后直接返回成功。正常结束、上下文取消、网络断开和驱动读取失败，都可能让 Next 返回 false。因此，判断顺序应当是“扫描失败先返回，循环结束再检查 Err”。

官方 database/sql 文档把 Rows 描述为查询结果游标：Next 负责推进游标，Err 返回迭代过程中遇到的错误。也就是说，false 是分支信号，Err 才是循环结束后的错误结论。

用一个模板收拢资源和错误

下面的写法适合大多数多行查询。QueryContext 失败时没有可关闭的 Rows；一旦拿到结果集，就立即登记关闭动作。循环中只处理当前行，循环后统一读取错误。

ctx, cancel := context.WithTimeout(context.Background(), 800*time.Millisecond)
defer cancel()

rows, err := db.QueryContext(ctx, `SELECT id, name FROM users WHERE state = ?`, "ready")
if err != nil {
    // 查询尚未建立成功时，直接返回上下文或驱动给出的错误。
    return err
}
defer rows.Close()

for rows.Next() {
    var id int64
    var name string
    if err := rows.Scan(&id, &name); err != nil {
        // Scan 失败属于当前行处理失败，不能被循环结束后的 Err 替代。
        return err
    }
    consumeUser(id, name)
}

if err := rows.Err(); err != nil {
    // 取消、网络读取失败等迭代阶段错误在这里收口。
    return err
}
return nil

这个模板有三个关键点。第一，defer rows.Close() 防止提前返回时忘记释放结果集；第二，Scan 错误在现场处理，避免继续消费不完整数据；第三，Err 放在循环之后，覆盖“最后一行读完”和“中途被取消”两种结局。

取消发生后该看什么错误

如果取消发生在查询尚未返回 Rows 之前，QueryContext 可能直接返回错误；如果已经进入迭代，Next 可能提前返回 false，此时要读取 rows.Err()。实际错误值可能是 context.Canceled、context.DeadlineExceeded，也可能是驱动包装后的错误，因此业务层应使用 errors.Is 判断上下文错误。

if err := rows.Err(); err != nil {
    // 先识别上下文错误，再把其它驱动错误交给上层记录或重试策略。
    switch {
    case errors.Is(err, context.Canceled):
        return err
    case errors.Is(err, context.DeadlineExceeded):
        return err
    default:
        return fmt.Errorf("读取用户结果失败: %w", err)
    }
}

不要把取消统一改写成“没有数据”。取消意味着这次读取没有完成，是否重试、降级还是向调用方返回超时，应由请求语义决定。对可重试查询，还要确认查询本身没有副作用，并为下一次尝试创建新的上下文。

别忽略驱动的取消支持

database/sql 能传递上下文，但最终能否及时中断仍取决于驱动。官方 database/sql/driver 建议驱动实现 QueryerContext，并且必须遵守上下文取消；如果驱动没有实现该接口，标准库可能回退到旧的查询路径，取消就不一定能立刻终止底层操作。

排查时可以按三层复查：先确认请求确实调用了 QueryContext，再确认循环结束后读取了 Rows.Err，最后查看所用驱动的文档与版本是否支持上下文取消。不要只凭某一次快速返回就断定驱动支持，也不要用更短的超时掩盖底层查询没有响应取消的问题。

常见问题

rows.Next 返回 false 就一定是正常结束吗？

不一定。正常结束和迭代错误都会返回 false，必须在循环后检查 rows.Err()。

已经 defer rows.Close 了，还要显式调用 Close 吗？

多数读取场景由 defer 收口即可；如果需要在循环未结束时立即释放资源，或必须处理关闭阶段返回的错误，可以显式调用。Close 是幂等的。

总结

处理查询上下文取消时，记住一条边界：Next 只告诉你迭代是否还能继续，Err 才告诉你为什么结束；Close 负责资源收口，而驱动的 QueryerContext 决定取消能否抵达底层。按照“QueryContext 检查、defer Close、循环 Scan、循环后 Err”的顺序写，最容易避免把取消误判成成功。