ActiveDataProvider是Yii中专为ActiveRecord设计的数据提供者，适用于列表页、GridView、API分页等场景，依赖ActiveQuery实例，自动下推分页排序至SQL层，避免内存OOM。
ActiveDataProvider 是什么，什么时候该用它
ActiveDataProvider 是 Yii 中最常用的数据提供者，专为 ActiveRecord 模型设计，自动支持分页、排序、过滤。如果你在写列表页、后台表格、带搜索的网格视图，它就是默认选择——不是“可以考虑”，而是“大概率就该用它”。
它不直接查数据库，而是封装一个 Query 或 ActiveQuery，把分页/排序逻辑下推到 SQL 层，避免全量加载再内存处理。这点很关键：不用它而手写 array_chunk 或 array_slice 处理大数组，很容易 OOM。
- 适合场景：
GridView渲染、API 分页响应、后台数据导出前的预览 - 不适合场景：聚合统计（如 SUM/COUNT）、跨库关联、非 ActiveRecord 数据源（比如 Redis 缓存结果）
- 注意：它依赖模型的
search()方法返回的ActiveQuery实例，不是任意数组或查询构造器
初始化 ActiveDataProvider 的三个必要参数
创建实例时，query、pagination、sort 这三个配置项决定行为边界。漏掉或配错其中任何一个，都可能让分页失效、排序不生效、甚至报 Invalid Configuration 错误。
-
query必须是ActiveQuery实例（比如User::find()），不能是数组、Query基类或已执行的all()结果 -
pagination默认启用，设为false会禁用分页；想限制每页条数，用['pageSize' => 20]，别直接改模型里的defaultPageSize -
sort默认开启字段白名单保护，未在attributes中声明的字段无法被排序，防止 SQL 注入；例如：'sort' => ['attributes' => ['id', 'username', 'created_at']]
常见错误：new ActiveDataProvider(['query' => User::find()->where(['status' => 1])]) 看似没问题，但如果没配 sort，前端传 sort=-id 会静默忽略；配了但没列 id，就会 400 报错 Invalid Sort Attribute。
和 SqlDataProvider、ArrayDataProvider 的关键区别
别因为名字像就混用。三者定位完全不同：
-
ActiveDataProvider：绑定 ActiveRecord，自动映射属性、支持验证、能复用模型关系（with()）、可直接调save()/delete() -
SqlDataProvider：只接受原生 SQL 字符串或Command对象，适合复杂视图、 UNION 查询、或非 Yii 模型数据；但没有属性规则、不能直接更新，sort需手动映射字段别名 -
ArrayDataProvider：纯内存操作，适合小量静态数据（如配置项枚举）、测试 mock；大数据量时性能断崖式下跌，且分页是切数组，不是 SQL LIMIT
性能提示：用 ActiveDataProvider 查 10 万行？只要 SQL 走索引、count() 不触发全表扫描（比如避免 LIKE '%xxx' 在 count 中），就没问题；换成 ArrayDataProvider 反而更慢，还吃内存。
常见报错和绕过陷阱的写法
实际开发中最卡人的不是不会写，而是某些组合导致行为反直觉：
- 报错
Calling unknown method: yii\db\ActiveQuery::search()：说明你把普通Query当成ActiveQuery用了，检查是否少写了use app\models\User;或误用了new Query() - 分页后总数不准（
totalCount偏低）：大概率用了groupBy却没配pagination['totalCount']回调，或者关联查询没加distinct导致重复计数 - 排序字段不起作用：确认
sort配置里声明了该字段，且模型中该属性可读（public 或有 getter），数据库字段名和模型属性名一致；若用别名（如CONCAT(first_name, last_name) as full_name），必须在sort['attributes']中显式映射 - 关联字段无法排序/过滤：要用
joinWith('profile')+addSelect('profile.nickname')，再在sort和filter中引用profile.nickname，不能只靠with()
最易被忽略的一点：ActiveDataProvider 的 query 在第一次调用 getModels() 或 getCount() 时才真正执行。调试时别只看构造参数，要检查最终生成的 SQL —— 开启 yii\db\Command::enableLogging = true 或看 debug toolbar 的 query 面板。
