Yii2 数据提供者(Data Providers)完全指南:ActiveDataProvider、SqlDataProvider 与 ArrayDataProvider 实战与源码解析

原创2026-09-21 17:27:151,676 阅读
文章标签:后端Web框架

Yii2 数据提供者(Data Providers)完全指南:ActiveDataProvider、SqlDataProvider 与 ArrayDataProvider 实战与源码解析

数据分页与排序是 Web 应用中最常见的重复性工作,Yii2 通过一组数据提供者(Data Provider)类将其统一封装,让开发者只需配置数据源,即可获得分页、排序能力,并能直接接入 GridView、ListView 等数据组件。本文以 Yii2 官方指南 output-data-providers 为主线,结合框架源码 framework/data 与单元测试 tests/framework/data,系统讲解三种内置数据提供者的用法、底层实现原理,以及如何自定义数据提供者和使用 DataFilter 实现灵活过滤。读完本文,你将能够根据业务场景正确选型并熟练驾驭 Yii2 的数据提供者体系。

什么是数据提供者

在 Pagination 与 Sorting 两节中,我们已经学会了如何让最终用户选择显示某一页数据,并按某些列排序。由于分页和排序是非常普遍的需求,Yii2 专门提供了一组 数据提供者类 来封装这一过程。

数据提供者本质上是实现了 <a href="https://link.gitcode.com/i/0b1b0831946ec0acae2bc3fd529a5210" target="_blank">[yii\data\DataProviderInterface]] 接口的类,主要负责获取已分页、已排序的数据,通常与[数据组件配合使用,让终端用户能够交互式地对数据进行分页和排序。

在 DataProviderInterface 接口中,定义了数据提供者必须提供的核心能力:

  • prepare($forcePrepare = false):准备数据模型与键;
  • getModels():返回当前页的数据模型;
  • getKeys():返回与数据模型对应的键值列表;
  • getCount():返回当前页数据条数(等价于 count($provider->getModels()));
  • getTotalCount():返回所有页面的数据总条数;
  • getSort() / getPagination():返回排序对象与分页对象(为 false 表示禁用)。

Yii2 发行版内置了以下三种数据提供者类:

类 数据源 返回数据类型
yii\data\ActiveDataProvider yii\db\Query 或 yii\db\ActiveQuery 数组或 Active Record 实例
yii\data\SqlDataProvider 原生 SQL 语句 数组(数据行)
yii\data\ArrayDataProvider 内存中的大数组 数组切片

数据提供者的统一使用模式

所有数据提供者的用法都遵循同一个模式:先通过配置其 pagination 和 sort 属性创建实例,然后调用 getModels()、getCount()、getTotalCount() 获取数据:

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

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

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

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

这里 getCount() 与 getTotalCount() 在 BaseDataProvider 中的实现分别是 count($this->getModels()) 与(分页禁用时)返回 getCount()、否则调用 prepareTotalCount()(见 BaseDataProvider.php#L166-L185)。也就是说,getCount() 统计的是当前页的数据条数,而 getTotalCount() 是跨所有页面的数据总数,两者用途完全不同,在计算分页页码数量时依赖的是后者。

配置分页与排序行为

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

从源码看,setPagination() 与 setSort() 接受三种取值(见 BaseDataProvider.php#L223-L277):

  • 配置数组:例如 ['pageSize' => 10],会被合并到默认配置后通过 Yii::createObject() 创建对象;
  • 对象实例:Pagination / Sort 的实例或其子类实例;
  • false:禁用对应功能。

一个容易忽略的细节是:当配置为数组时,如果数据提供者的 id 属性不为 null(默认自动生成 'dp-1'、'dp-2' 等,见 BaseDataProvider.php#L71-L80),框架会自动为分页与排序设置独立的请求参数名:{id}-page、{id}-per-page 和 {id}-sort。这意味着同一页面上放置多个数据提供者时,它们的分页、排序请求参数不会互相冲突——这是从源码中可以确认的防冲突设计。

与数据组件协同工作

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

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

数据提供者的差异主要在于数据源的指定方式不同,接下来逐一深入讲解。

ActiveDataProvider:基于 ActiveQuery 或 Query

使用 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]);

关于查询子句覆盖行为(原文档明确提示):如果查询已经带有 orderBy 子句,终端用户通过 sort 配置给出的新排序指令会追加到原有 orderBy 子句之后;而查询中已有的 limit、offset 子句则会被终端用户通过 pagination 发出的分页请求覆盖。

从源码可以印证这一点:ActiveDataProvider::prepareModels() 先 clone 查询对象,然后执行 $query->limit($pagination->getLimit())->offset($pagination->getOffset()) 覆盖分页参数,再执行 $query->addOrderBy($sort->getOrders()) 追加排序;而 prepareTotalCount() 统计总数时会先 ->limit(-1)->offset(-1)->orderBy([]) 清除分页与排序影响,再执行 count('*', $this->db)。正是因为内部操作的是克隆后的查询对象,原查询对象不会被污染,这保证了数据提供者可以被安全复用。

另一个值得注意的源码特性在 ActiveDataProvider::setSort():当 query 是 ActiveQueryInterface 实例且没有显式配置 sort 的 attributes 时,框架会自动用模型(modelClass)的所有属性填充可排序字段(asc/desc 分别映射为 SORT_ASC/SORT_DESC)。因此使用 ActiveDataProvider + ActiveQuery 时,sort 属性常常可以省略,这与 SqlDataProvider、ArrayDataProvider 必须显式声明可排序属性形成了鲜明对比。

默认情况下,ActiveDataProvider 使用应用的 db 数据库连接组件。如需使用其他数据库连接,可以配置 db 属性(从 2.0.2 起也支持配置数组形式,见 ActiveDataProvider.php#L76-L80)。

SqlDataProvider:原生 SQL 语句

yii\data\SqlDataProvider 基于一条原生 SQL 语句来获取所需数据。根据 sort 与 pagination 的配置,提供者会自动调整 SQL 语句的 ORDER BY 与 LIMIT 子句,仅抓取所请求的那一页数据并按期望的顺序返回。

使用 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(原文档特别说明):totalCount 属性只有在需要分页数据时才必须提供。原因在于,提供者会修改经由 sql 指定的 SQL 语句,使其只返回当前请求的那一页数据,但它仍然需要知道数据的总条数,才能正确计算可用页数。

源码层面的实现细节非常值得了解(见 SqlDataProvider::prepareModels()):

  1. 如果分页与排序都被禁用,直接执行原 SQL 返回全部结果;
  2. 启用排序时,先通过正则 /\s+order\s+by\s+([\w\s,\."[]]+)$/i探测 SQL 尾部**已存在的**ORDER BY子句,将其提取为Expression` 放在排序列表最前面(即原排序优先级更高),再从 SQL 中移除它;
  3. 然后调用 $this->db->getQueryBuilder()->buildOrderByAndLimit($sql, $orders, $limit, $offset) 重新拼接 ORDER BY 与 LIMIT/OFFSET。

而 prepareTotalCount() 则是把原 SQL 包成子查询 SELECT COUNT(*) FROM ({$sql}) sub 来统计总数,这意味着即使不手动执行 COUNT(*),只要显式设置了 totalCount 也可以避免重复统计的额外开销。

SqlDataProvider 还支持通过 key 属性指定数据行的键,并且自带 params 属性用于绑定 SQL 参数,从而避免 SQL 注入风险。

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();

从源码看(ArrayDataProvider::prepareModels()),处理流程是:先通过 sortModels() 使用 ArrayHelper::multisort() 按排序指令重排整个数组,再通过 array_slice($models, $pagination->getOffset(), $pagination->getLimit(), true) 取出当前页的切片。

性能提示(原文档明确警告):与 Active Data Provider 和 SQL Data Provider 相比,ArrayDataProvider 效率较低,因为它需要把全部数据加载到内存中。因此它更适合数据量可控的场景,例如读取配置数据、CSV 解析结果或小规模数据集。

另外,ArrayDataProvider 的 key 属性除列名、可调用对象外,还支持点分隔路径(如 'author.name')与键数组,内部通过 ArrayHelper::getColumn() 取值(见 ArrayDataProvider.php#L105-L112)。

处理数据键(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();

在上面的示例中,由于给 ActiveDataProvider 传入的是 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 未配置且 query 是 ActiveQueryInterface 时,会读取 modelClass::primaryKey():单主键直接取值,复合主键则组装成 [pk1 => v1, pk2 => v2] 形式的关联数组;否则退化为返回 array_keys($models)(数组下标)。

这些键在 GridView 等组件中非常有用——例如行选择、行编辑定位,以及 DataColumn 的 value 回填都依赖键与行的对应关系。

自定义数据提供者:以 CsvDataProvider 为例

要创建自己的数据提供者类,需要实现 <a href="https://link.gitcode.com/i/b22f6761f4b41cb60c4fe0b3c77a438d" target="_blank">[yii\data\DataProviderInterface]]。更简单的方式是继承 [yii\data\BaseDataProvider,这样可以只专注于数据提供者的核心逻辑。具体来说,你只需实现以下三个方法(它们正是 BaseDataProvider 中声明的三个抽象方法,见 BaseDataProvider.php#L82-L99):

  • prepareModels():准备当前页可用的数据模型,并以数组形式返回;
  • prepareKeys($models):接收当前可用的数据模型数组,返回与它们关联的键;
  • prepareTotalCount():返回一个值,表示数据提供者中数据模型的总数。

以下是官方指南中给出的、能高效读取 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;
        }

        return array_keys($models);
    }

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

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

        return $count;
    }
}

这个例子巧妙运用了 SplFileObject 的 seek() 能力:启用分页时通过 $pagination->getOffset() 直接定位到当前页起始行,再读取 $pagination->getLimit() 行,从而避免把整个文件读入内存。同时注意 $pagination->totalCount = $this->getTotalCount() 这行——它把总数写回分页对象,分页对象才能正确计算页数。这与 BaseDataProvider::getTotalCount() 中"分页对象需要知道总数"的设计完全一致。

框架自身的测试(如 tests/framework/data/BaseDataProviderTest.php、tests/framework/data/ActiveDataProviderTest.php)也验证了这套抽象机制的完整性:prepare() 方法会先准备模型再准备键,且 refresh() 方法可以清空缓存(_totalCount、_models、_keys 置空),下次调用 getModels() 等会重新执行查询获取最新数据(见 BaseDataProvider.php#L284-L289)。

使用 DataFilter 灵活过滤数据

虽然你可以像数据组件指南的 Filtering Data 与 Separate Filter Form 小节描述的那样手动为 active data provider 构建过滤条件,但当需要灵活的过滤条件时,Yii2 提供了数据过滤器(Data Filters),用法如下:

$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) {
        // 序列化器会从中取出错误
        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],
        ];
    }
}

DataFilter 的底层机制

从源码看,DataFilter 本身就是一个特殊的 Model(自 2.0.13 引入),其 formName() 返回空字符串,attributes() 只暴露 filterAttributeName(默认 'filter')一个属性,因此请求参数以 filter 为键传入。load() 负责把原始过滤规格装载进来,build() 先执行校验、失败返回 false,成功则调用 buildInternal() 生成真正的查询条件(见 DataFilter.php#L708-L714)。

内置的过滤控制关键字定义在 $filterControls 属性中(见 DataFilter.php#L174-L187):

外部关键字 内部操作符 说明
and / or / not AND / OR / NOT 逻辑组合
lt / gt / lte / gte < / > / <= / >= 比较运算
eq / neq = / != 相等 / 不相等
in / nin IN / NOT IN 集合包含
like LIKE 模糊匹配

操作符与属性类型的关系由 $operatorTypes 约束(见 DataFilter.php#L212-L222):例如 <、>、<=、>= 只允许用于 integer、float、datetime、date、time 类型;LIKE 仅适用于 string;而 =、!=、IN、NOT IN 支持所有类型(*)。属性类型则通过 detectSearchAttributeTypes() 从 searchModel 的校验规则中自动推断(BooleanValidator → boolean、NumberValidator → integer/float、StringValidator → string、EachValidator → array、DateValidator → date/datetime/time,见 DataFilter.php#L334-L393)。

如何构建查询条件由 ActiveDataFilter 实现:其 $conditionBuilders 把 AND/OR/NOT 及各种比较操作符映射到对应的构建方法(见 ActiveDataFilter.php#L37-L50),最终生成兼容 QueryInterface::where() 的嵌套数组条件。例如 JSON 过滤规格 {"price": {"gt": 10, "lt": 50}} 会被构建为 ['and', ['>', 'price', 10], ['<', 'price', 50]]。

可定制点包括:

  • $filterControls:为同一操作符配置多个别名(例如 eq、=、== 都映射为 =),但要注意避免控制关键字与真实属性名冲突;
  • $conditionBuilders:可用 PHP 回调替换某个操作符的构建逻辑;
  • $queryOperatorMap:操作符到查询操作符的映射,例如使用 PostgreSQL 时配置 <a href="https://link.gitcode.com/i/bb46df277767aa10ef07580c9f575015" target="_blank">'LIKE' => 'ILIKE'] 实现大小写不敏感匹配(见 [ActiveDataFilter.php#L52-L66);
  • $attributeMap:过滤属性名到实际查询列名的映射,例如联表查询时 <a href="https://link.gitcode.com/i/9c843c5cbc623e2ef3f2e7228376cc63" target="_blank">'authorName' => '{{author}}.[[name]]'](见 [DataFilter.php#L226-L242);
  • $nullValue:表示 null 的特殊字符串,默认 'NULL',归一化时会被转换为真正的 null(见 DataFilter.php#L247);
  • $errorMessages:自定义各类结构错误的提示文案。

为了减少类数量,searchModel 也可以直接使用 yii\base\DynamicModel 实例(通过 PHP 可调用对象提供),例如:

function () {
    return (new \yii\base\DynamicModel(['id' => null, 'name' => null]))
        ->addRule(['id', 'name'], 'trim')
        ->addRule('id', 'integer')
        ->addRule('name', 'string');
}

需要说明的是,DataFilter 基类的 build() 只做归一化,真正把规格转换为数据库查询条件的是 ActiveDataFilter(继承自 DataFilter);如果你需要把过滤规格转成其他格式(如 MongoDB 条件),可以继承 DataFilter 并实现自己的 buildInternal()。

总结与选型建议

结合原文档与源码,可以给出如下选型建议:

  • 绝大多数业务场景优先使用 ActiveDataProvider:配合 ActiveQuery 可自动获得模型实例、自动推断主键与可排序字段,且查询对象在内部被克隆,不会污染原查询;
  • 需要编写复杂原生 SQL、或复用既有 SQL 查询时使用 SqlDataProvider,注意分页时必须提供 totalCount,排序时必须显式声明 attributes;
  • 数据量可控的内存数据(如 CSV、配置、缓存结果)使用 ArrayDataProvider,但要清醒认识到全量载入内存的成本;
  • 需要灵活的 API 过滤能力时,用 ActiveDataFilter + searchModel 校验规则组合,既能白名单约束可过滤属性,又能自动把 JSON 规格转化为安全的查询条件。

数据提供者是 Yii2 中"数据查询 → 展示"链路的核心抽象,理解其统一模式与各实现的差异,能让你在 GridView、ListView、REST 集合接口等场景下写出更简洁、更健壮的代码。相关单元测试(tests/framework/data 下的 ActiveDataProviderTest.php、SqlDataProviderTest.php、ArrayDataProviderTest.php、DataFilterTest.php、ActiveDataFilterTest.php 等)展示了官方对这些行为的完整验证,可作为深入学习的补充材料。

登录后查看全文
yii2