绝大多数场景用 find()，它是 CakePHP ORM 的标准查询入口；query() 是底层 SQL 构建器，适用于原生 SQL 或复杂 JOIN、子查询等 find() 难以表达的逻辑，需手动防注入和字段映射。
用 find() 还是 query()？看你要不要绕过 ORM
直接说结论：绝大多数场景用 find()，它才是 CakePHP ORM 的标准查询入口；query() 是底层 SQL 构建器，适合写原生 SQL 或复杂 JOIN、子查询等 find() 不易表达的逻辑。
常见误区是以为 query() “更底层=更推荐”，其实相反——find() 自动处理关联加载、类型转换、安全过滤（如自动转义参数），而 query() 一旦手写 SQL，就得自己防 SQL 注入、自己处理字段映射。
-
find('all')：查全部，返回ResultSet，支持->contain()、->select()链式调用 -
find('first')：查单条，返回实体（Entity）或null -
find('list')：查键值对，常用于下拉菜单，->setKeyField('id')->setValueField('name') - 用
query()时，必须显式调用->execute()才真正执行，且返回的是原始 PDOStatement，不是 Entity
WHERE 条件里传数组还是用 where()？优先用后者
CakePHP 4+ 强烈建议用 where() 方法传闭包或表达式对象，而不是老式的数组语法。数组写法（如 ['status' => 'active']）虽然还能用，但不支持嵌套条件、运算符自定义、以及与 OR 混用的安全组合。
容易踩的坑：直接拼字符串进 where()，比如 ->where("created > '$date'") —— 这会绕过参数绑定，有注入风险。
立即学习“PHP免费学习笔记（深入）”；
- 正确写法：
->where(['status' => 'active'])（简单等值） - 带运算符：
->where(['age >=' => 18])或->where(function ($exp) { return $exp->gte('age', 18); }) - OR 条件：
->where(function ($exp) { return $exp->or_(['type' => 'A', 'type' => 'B']); }) - NULL 判断：
->where(['deleted IS NULL'])（注意不能写成['deleted' => null]，那会被当成 = NULL）
contain() 加载关联时，为什么数据没出来？检查三件事
关联数据为空，90% 是这三个原因导致的：关联名写错、目标表字段缺失、或未启用 eager loading。
CakePHP 不会自动加载关联，必须显式调用 contain()，且关联名必须和表类中 initialize() 里定义的完全一致（大小写敏感）。例如 ArticlesTable 里写了 $this->belongsTo('Authors')，那查询时就得写 ->contain(['Authors'])，不能写 ->contain(['author'])。
- 确保关联目标表存在对应外键字段，比如
articles.author_id必须存在且非空 - 如果关联是
hasMany或belongsToMany，默认只加载主表 ID，要查具体字段得再加->select()或在关联定义里设'foreignKey' => 'xxx' - 用
debug($query->sql())看生成的 SQL，确认 JOIN 是否出现、别名是否正确
分页、排序、限制数量这些操作，统一走 paginate() 而不是手动 limit()
手动用 ->limit(10)->offset(20) 做分页，看似简单，实则埋雷：总数统计要另写一次查询、URL 参数解析要自己处理、缓存失效难控制。CakePHP 的 paginate() 方法会自动做这些事，而且和控制器里的 $this->paginate 配置联动。
性能影响明显：手动 limit + count(*) 分开查，可能扫两次全表；paginate() 在支持的数据库（MySQL 8.0+、PostgreSQL）上能用窗口函数优化 COUNT，甚至支持 count => 'all' 跳过 COUNT 查询。
- 控制器里直接
$this->paginate = ['limit' => 15, 'order' => ['created' => 'DESC']] - 查询时用
$this->Articles->paginate()，它返回已切片的数据 + 元信息（current_page,count等） - 排序字段必须存在于 SELECT 中，否则某些数据库（如 PostgreSQL）会报错，所以别漏掉
->select(['id', 'title', 'created'])
关联字段排序（比如按作者名排序）需要先 contain()，再在 order 里用别名，如 ['Authors.name' => 'ASC']，否则会找不到字段。
