Yii 2 数据提供者(Data Provider)完全指南:ActiveDataProvider / SqlDataProvider / ArrayDataProvider 的分页、排序与自定义实现

原创2026-09-21 14:05:021,619 阅读
文章标签:后端Web框架

Yii 2 数据提供者(Data Provider)完全指南:ActiveDataProvider / SqlDataProvider / ArrayDataProvider 的分页、排序与自定义实现

本篇指南围绕 Yii 2 框架的 yii\data 组件展开,系统讲解数据提供者(Data Provider)这一将分页与排序封装为一套统一接口的核心机制。你将掌握 Yii 2 内置的 ActiveDataProvider、SqlDataProvider、ArrayDataProvider 三种数据源接入方式,理解 getModels()、getKeys()、getTotalCount() 等关键方法背后的实现原理,并能基于 BaseDataProvider 自行编写高效的自定义数据提供者(如 CSV 读取器),最终将这些能力与 GridView 等数据组件无缝衔接。

数据提供者是什么:统一封装分页与排序

在 分页 与 排序 两篇指南中,我们已经介绍了如何让终端用户选择要展示的数据页,并按照某些列对数据进行排序。由于分页与排序是极其常见的任务,Yii 2 提供了一套 数据提供者(Data Provider) 类来封装这一过程。

数据提供者是一个实现了 yii\data\DataProviderInterface 接口的类,核心职责是取出已分页且已排序的数据。它通常与 数据组件(Data Widgets) 配合使用,让终端用户能够以交互方式分页与排序数据。

Yii 2 正式版本中内置了以下三类数据提供者:

类 数据来源 返回数据形式
yii\data\ActiveDataProvider yii\db\Query 或 yii\db\ActiveQuery 数组或 Active Record 实例
yii\data\SqlDataProvider 原生 SQL 语句 数据行数组
yii\data\ArrayDataProvider 一个大型 PHP 数组 数组切片

所有数据提供者的使用方式都遵循同一个通用模式:

// 通过配置其分页与排序属性来创建数据提供者
$provider = new XyzDataProvider([
    'pagination' => [...],
    'sort' => [...],
]);

// 获取已分页且已排序的数据
$models = $provider->getModels();

// 获取当前页的数据项数量
$count = $provider->getCount();

// 获取所有页的数据项总数
$totalCount = $provider->getTotalCount();

你通过配置数据提供者的 pagination 与 sort 两个属性来指定其分页与排序行为,它们分别对应 yii\data\Pagination 与 yii\data\Sort 的配置。也可以将它们设置为 false 来禁用分页和/或排序功能。

从源码看,BaseDataProvider 内部对这两个属性做了灵活处理(framework/data/BaseDataProvider.php):

  • 传入配置数组时,默认以 yii\data\Pagination / yii\data\Sort 为 class 创建对象;
  • 传入 Pagination / Sort 实例时直接使用;
  • 传入 false 时表示禁用对应功能;
  • 传入其他值则抛出 InvalidArgumentException。

值得一提的细节是:BaseDataProvider 会根据自身 id 自动为分页与排序参数加上前缀(如 dp-1-page、dp-1-per-page、dp-1-sort),这正是同一个页面上存在多个数据提供者时彼此参数互不干扰的实现基础——第一个提供者 id 为空,之后的依次为 dp-1、dp-2 等。

与数据组件的协作

数据组件(如 yii\grid\GridView)拥有一个名为 dataProvider 的属性,可以接收数据提供者实例并展示其提供的数据。例如:

echo yii\grid\GridView::widget([
    'dataProvider' => $dataProvider,
]);

这三类数据提供者主要区别在于数据源的指定方式。接下来我们逐一详解各自的用法。

ActiveDataProvider:基于查询构建器的数据提供者

要使用 yii\data\ActiveDataProvider,你需要配置其 query 属性。它可以接受一个 yii\db\Query 或 yii\db\ActiveQuery 对象:

  • 传入 Query 时,返回的是原始数组;
  • 传入 ActiveQuery 时,返回的既可以是数组,也可以是 Active Record 实例。

例如:

use yii\data\ActiveDataProvider;

$query = Post::find()->where(['status' => 1]);

$provider = new ActiveDataProvider([
    'query' => $query,
    'pagination' => [
        'pageSize' => 10,
    ],
    'sort' => [
        'defaultOrder' => [
            'created_at' => SORT_DESC,
            'title' => SORT_ASC,
        ]
    ],
]);

// 返回一个由 Post 对象组成的数组
$posts = $provider->getModels();

如果上面示例中的 $query 使用如下代码创建,则数据提供者返回的是原始数组:

use yii\db\Query;

$query = (new Query())->from('post')->where(['status' => 1]);

底层实现:查询如何被改写

从 ActiveDataProvider::prepareModels() 的源码可以看到实际执行逻辑:

  1. 克隆查询对象(clone $this->query),保证数据提供者不会破坏调用方原始查询;
  2. 若分页开启,先取得总数,若总数为 0 则直接返回空数组,否则调用 $query->limit($pagination->getLimit())->offset($pagination->getOffset()) 应用分页;
  3. 若排序开启,调用 $query->addOrderBy($sort->getOrders()) 追加排序条件;
  4. 最后通过 $query->all($this->db) 执行查询。

注意:如果查询本身已经指定了 orderBy 子句,终端用户给出的新排序指令(通过 sort 配置)会被追加到已有的 orderBy 子句之后(addOrderBy 语义);而已有的 limit 与 offset 子句则会被分页请求(通过 pagination 配置)覆盖。

在计算总数时,prepareTotalCount() 会再次克隆查询并调用 $query->limit(-1)->offset(-1)->orderBy([])->count('*', $this->db)——即去除排序与分页条件后执行 COUNT(*) 查询。这也是为什么每次分页都伴随着一次额外的计数查询。

使用不同的数据库连接

默认情况下,yii\data\ActiveDataProvider 使用应用组件 db 作为数据库连接。你可以通过配置 db 属性来使用其他连接(支持连接对象、应用组件 ID 或配置数组,见 init() 中的 Instance::ensure 处理):

$provider = new ActiveDataProvider([
    'query' => Post::find(),
    'db' => 'db2', // 使用名为 db2 的应用组件
]);

排序属性的自动推导

另一个值得注意的源码行为(setSort()):当 query 是 ActiveQuery 且 sort->attributes 为空时,框架会自动遍历模型类的全部属性($model->attributes()),为每个属性生成 asc / desc 排序定义,并自动设置 sort->modelClass。这意味着在多数 Active Record 场景下你甚至无需手动声明可排序列。

SqlDataProvider:基于原生 SQL 的数据提供者

yii\data\SqlDataProvider 使用原生 SQL 语句获取数据。根据 sort 与 pagination 的配置,提供者会相应地调整 SQL 语句的 ORDER BY 与 LIMIT 子句,只获取当前请求页的数据,并按期望的顺序返回。

使用 yii\data\SqlDataProvider 时,你需要指定 sql 属性,以及 totalCount 属性。例如:

use yii\data\SqlDataProvider;

$count = Yii::$app->db->createCommand('
    SELECT COUNT(*) FROM post WHERE status=:status
', [':status' => 1])->queryScalar();

$provider = new SqlDataProvider([
    'sql' => 'SELECT * FROM post WHERE status=:status',
    'params' => [':status' => 1],
    'totalCount' => $count,
    'pagination' => [
        'pageSize' => 10,
    ],
    'sort' => [
        'attributes' => [
            'title',
            'view_count',
            'created_at',
        ],
    ],
]);

// 返回一个数据行数组
$models = $provider->getModels();

说明:totalCount 属性仅在需要分页时才必须提供。这是因为通过 sql 指定的 SQL 语句会被提供者改写为只返回当前请求页的数据,提供者必须知道数据项总数才能正确计算可用页数。

底层实现:SQL 如何被改写

SqlDataProvider::prepareModels() 的实现揭示了两个关键细节:

  1. 排序:$sort->getOrders() 得到排序条件;若原始 SQL 末尾已包含 order by 子句(通过正则 /\s+order\s+by\s+([\w\s,\."[]]+)$/i匹配),会用Expression保留原有排序并把order by` 从 SQL 中剥离,再将用户排序追加到前面;
  2. 最终拼接:通过 $this->db->getQueryBuilder()->buildOrderByAndLimit($sql, $orders, $limit, $offset) 由查询构建器生成带 ORDER BY / LIMIT / OFFSET 的最终 SQL,然后以 $this->params 作为绑定参数执行。

若排序与分页都被禁用,则直接执行原始 SQL 并返回全部行。

当未显式指定 totalCount 时,prepareTotalCount() 会把原始 SQL 包装为子查询:SELECT COUNT(*) FROM ({$this->sql}) AS sub 并自动带上 params 参数执行计数。

另外注意:SqlDataProvider 默认 db = 'db',并在 init() 中强制校验 sql 属性非空,否则抛出 InvalidConfigException。

ArrayDataProvider:基于内存数组的数据提供者

yii\data\ArrayDataProvider 最适合在处理一个大型数组时使用。它允许你返回按一个或多个列排序的数组数据页。使用 yii\data\ArrayDataProvider 时,你需要将 allModels 属性指定为那个大数组。大数组中的元素既可以是关联数组(例如 DAO 的查询结果),也可以是对象(例如 Active Record 实例)。例如:

use yii\data\ArrayDataProvider;

$data = [
    ['id' => 1, 'name' => 'name 1', ...],
    ['id' => 2, 'name' => 'name 2', ...],
    ...
    ['id' => 100, 'name' => 'name 100', ...],
];

$provider = new ArrayDataProvider([
    'allModels' => $data,
    'pagination' => [
        'pageSize' => 10,
    ],
    'sort' => [
        'attributes' => ['id', 'name'],
    ],
]);

// 获取当前请求页的数据行
$rows = $provider->getModels();

注意:与 ActiveDataProvider 和 SqlDataProvider 相比,数组数据提供者的效率较低,因为它需要把所有数据都加载到内存中。

底层实现:切片与排序

ArrayDataProvider::prepareModels() 的实现逻辑:

  1. 若 allModels 为 null,直接返回空数组;
  2. 若排序开启,调用 sortModels(),内部通过 yii\helpers\ArrayHelper::multisort() 完成多列排序(排序标志由 Sort::sortFlags 决定,默认为 SORT_REGULAR);
  3. 若分页开启,使用 array_slice($models, $pagination->getOffset(), $pagination->getLimit(), true) 截取当前页数据(第三个参数 true 保留原数组键名)。

ArrayDataProvider 还支持 modelClass 属性(自 2.0.9 起),用于声明数据所代表的模型类,从而帮助组件获取列名。若要使用排序功能,必须配置 sort 属性让提供者知道哪些列可以被排序。

处理数据键(Data Keys)

使用数据提供者返回的数据项时,你常常需要用唯一键来标识每一个数据项。例如,如果数据项代表客户信息,你可能希望用客户 ID 作为每个客户数据的键。数据提供者可以返回一组与 getModels() 返回的数据项相对应的键。例如:

use yii\data\ActiveDataProvider;

$query = Post::find()->where(['status' => 1]);

$provider = new ActiveDataProvider([
    'query' => $query,
]);

// 返回一个由 Post 对象组成的数组
$posts = $provider->getModels();

// 返回与 $posts 对应的主键值
$ids = $provider->getKeys();

在上面的例子中,因为你向 yii\data\ActiveDataProvider 提供的是 yii\db\ActiveQuery 对象,它足够智能,会返回主键值作为键。你也可以通过配置 key 属性(一个列名或计算键值的回调函数)来显式指定键值的计算方式。例如:

// 使用 "slug" 列作为键值
$provider = new ActiveDataProvider([
    'query' => Post::find(),
    'key' => 'slug',
]);

// 使用 md5(id) 的结果作为键值
$provider = new ActiveDataProvider([
    'query' => Post::find(),
    'key' => function ($model) {
        return md5($model->id);
    }
]);

各提供者的键生成策略

从源码看,三个内置提供者的键生成策略各不相同:

  • ActiveDataProvider::prepareKeys():显式设置了 key 时按列名/回调生成;否则若查询是 ActiveQuery,取模型类主键——单主键直接取值,复合主键则生成 [pk1 => v1, pk2 => v2] 形式的数组;兜底返回 array_keys($models);
  • SqlDataProvider::prepareKeys():显式 key 优先,兜底 array_keys($models);
  • ArrayDataProvider::prepareKeys():显式 key 时通过 ArrayHelper::getColumn() 提取列(支持点分路径、键数组、回调),兜底 array_keys($models)。

在 BaseDataProvider::prepare() 中,models 与 keys 会被惰性准备并缓存,getModels() 与 getKeys() 首次调用即触发准备;调用 refresh() 可清空缓存以便重新执行查询。

创建自定义数据提供者(Custom Data Provider)

要创建自己的数据提供者类,你需要实现 yii\data\DataProviderInterface。更简单的做法是继承 yii\data\BaseDataProvider,这样你只需聚焦于数据提供者的核心逻辑。具体而言,你主要需要实现以下三个抽象方法(见 BaseDataProvider):

下面是一个高效读取 CSV 数据的数据提供者示例:

<?php
use yii\data\BaseDataProvider;

class CsvDataProvider extends BaseDataProvider
{
    /**
     * @var string 要读取的 CSV 文件名
     */
    public $filename;

    /**
     * @var string|callable 键列名或返回键值的回调函数
     */
    public $key;

    /**
     * @var SplFileObject
     */
    protected $fileObject; // SplFileObject 非常适合在文件中定位特定行

    /**
     * {@inheritdoc}
     */
    public function init()
    {
        parent::init();

        // 打开文件
        $this->fileObject = new SplFileObject($this->filename);
    }

    /**
     * {@inheritdoc}
     */
    protected function prepareModels()
    {
        $models = [];
        $pagination = $this->getPagination();

        if ($pagination === false) {
            // 在没有分页的情况下,读取所有行
            while (!$this->fileObject->eof()) {
                $models[] = $this->fileObject->fgetcsv();
                $this->fileObject->next();
            }
        } else {
            // 在有分页的情况下,只读取一页
            $pagination->totalCount = $this->getTotalCount();
            $this->fileObject->seek($pagination->getOffset());
            $limit = $pagination->getLimit();

            for ($count = 0; $count < $limit; ++$count) {
                $models[] = $this->fileObject->fgetcsv();
                $this->fileObject->next();
            }
        }

        return $models;
    }

    /**
     * {@inheritdoc}
     */
    protected function prepareKeys($models)
    {
        if ($this->key !== null) {
            $keys = [];

            foreach ($models as $model) {
                if (is_string($this->key)) {
                    $keys[] = $model[$this->key];
                } else {
                    $keys[] = call_user_func($this->key, $model);
                }
            }

            return $keys;
        } else {
            return array_keys($models);
        }
    }

    /**
     * {@inheritdoc}
     */
    protected function prepareTotalCount()
    {
        $count = 0;

        while (!$this->fileObject->eof()) {
            $this->fileObject->next();
            ++$count;
        }

        return $count;
    }
}

这个示例充分利用了 SplFileObject 的 seek() 能力:分页开启时直接将文件指针定位到当前页的 offset,只读取 limit 行,从而避免把整个文件加载进内存。

分页与排序对象的核心配置项

在自定义提供者或日常使用中,理解 Pagination 与 Sort 的关键配置会让你的工作更顺手:

Pagination 常用属性:

  • pageParam(默认 'page'):存放当前页码的请求参数名;
  • pageSizeParam(默认 'per-page'):存放每页条数的请求参数名;
  • defaultPageSize / pageSize:每页条数,小于 1 表示无限(单页包含全部数据);
  • forcePageParam:是否总是在 URL 中保留 page 参数;
  • validatePage:是否校验 page 在合法范围内(0 到 pageCount-1);
  • totalCount、pageCount、offset、limit:由提供者填充或供自定义逻辑读取的只读派生值。

Sort 常用属性:

  • attributes:可排序属性列表,可简写为列名数组,也可用完整配置(asc / desc / default / label)声明每列的排序方向映射;
  • enableMultiSort(默认 false):是否允许多列组合排序;
  • sortParam(默认 'sort'):排序参数名;
  • defaultOrder:默认排序;
  • separator(默认 ','):多列排序时参数内的分隔符;
  • sortFlags(默认 SORT_REGULAR):传递给 multisort 的排序标志。

使用数据过滤器(Data Filter)灵活构建查询条件

除了像 数据组件指南 中手动为 ActiveDataProvider 构建过滤条件,Yii 2 还提供了数据过滤器(Data Filter),在你需要灵活的过滤条件时非常有用。数据过滤器可以这样使用(本节内容同样见于 英文版数据提供者指南):

$filter = new ActiveDataFilter([
    'searchModel' => 'app\models\PostSearch'
]);

$filterCondition = null;

// 你可以从任何来源加载过滤器。例如,
// 如果你偏好 JSON 请求体,
// 可改用 Yii::$app->request->getBodyParams():
if ($filter->load(\Yii::$app->request->get())) {
    $filterCondition = $filter->build();
    if ($filterCondition === false) {
        // 序列化器(Serializer)会从中取出错误信息
        return $filter;
    }
}

$query = Post::find();
if ($filterCondition !== null) {
    $query->andWhere($filterCondition);
}

return new ActiveDataProvider([
    'query' => $query,
]);

PostSearch 模型的作用是声明允许被过滤的属性及其取值规则:

use yii\base\Model;

class PostSearch extends Model
{
    public $id;
    public $title;

    public function rules()
    {
        return [
            ['id', 'integer'],
            ['title', 'string', 'min' => 2, 'max' => 200],
        ];
    }
}

数据过滤器非常灵活。你可以自定义条件如何构建,以及允许使用哪些运算符。详细说明请参阅 yii\data\DataFilter 的 API 文档。

从 DataFilter 源码可以看到其设计要点:

  • 它本身是一个特殊的 Model(filterAttributeName 默认 'filter',formName() 返回空字符串),通过 load() 从请求中灌入原始过滤条件;
  • 默认的 filterControls 定义了 and、or、not、lt、gt、lte、gte、eq、neq、in、nin、like 等运算符关键字(framework/data/DataFilter.php#L174-L187);
  • operatorTypes 规定了每种运算符支持的属性类型(如 <、> 仅支持整数/浮点/日期时间等,LIKE 仅支持字符串),校验失败时会产生结构化的错误信息;
  • 过滤属性的数据类型会从 searchModel 的验证规则中自动推断(detectSearchAttributeType()),例如 integer 验证器推断为 TYPE_INTEGER,DateValidator 推断为 TYPE_DATE / TYPE_DATETIME / TYPE_TIME;
  • build() 返回可供 andWhere() 直接使用的查询条件数组,校验失败则返回 false;
  • 若不想为每种搜索场景单独建类,还可以用 DynamicModel 配合 searchModel 回调来内联定义搜索模型。

测试与验证:数据提供者的行为约定

仓库中 tests/framework/data/ 目录下的测试套件完整覆盖了本指南涉及的核心行为,可作为你验证理解的参考:

小结

Yii 2 的数据提供者体系以 DataProviderInterface 为契约、BaseDataProvider 为骨架,将「分页 + 排序 + 键生成 + 总数统计」这一整套数据列表逻辑统一封装,向上对接 GridView / ListView 等数据组件,向下适配 Active Record、原生 SQL 与内存数组三种数据源:

  • ActiveDataProvider 适合绝大多数基于模型与查询构建器的场景,自动推导主键与可排序列;
  • SqlDataProvider 适合需要精细控制 SQL 或复用复杂语句的场景,会自动改写 ORDER BY 与 LIMIT;
  • ArrayDataProvider 适合小规模内存数据的快速分页排序;
  • 当内置提供者无法满足需求时,继承 BaseDataProvider 并实现三个 prepare* 方法即可打造任意数据源(CSV、API、日志文件……)的分页排序能力;
  • 需要灵活查询条件时,DataFilter / ActiveDataFilter 与搜索模型配合,可安全地把前端传入的复杂过滤表达式转换为查询条件。

结合 Pagination、Sort、DataFilter 等配套类以及 框架测试套件,你可以放心地把这套机制用于后台列表、前端分页浏览乃至 REST 接口的数据输出。

登录后查看全文
yii2