# 查询构造器

<cite>
**本文引用的文件**
- [BaseQuery.php](file://vendor/topthink/think-orm/src/db/BaseQuery.php)
- [WhereQuery.php](file://vendor/topthink/think-orm/src/db/concern/WhereQuery.php)
- [AggregateQuery.php](file://vendor/topthink/think-orm/src/db/concern/AggregateQuery.php)
- [Db.php](file://vendor/topthink/framework/src/think/Db.php)
- [DbManager.php](file://vendor/topthink/think-orm/src/DbManager.php)
- [Db.php（门面）](file://vendor/topthink/think-orm/src/facade/Db.php)
- [Paginator.php](file://vendor/topthink/think-orm/src/Paginator.php)
- [ConnectionInterface.php](file://vendor/topthink/think-orm/src/db/ConnectionInterface.php)
- [Connection.php](file://vendor/topthink/think-orm/src/db/Connection.php)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录：常用方法速查](#附录常用方法速查)

## 简介
本指南面向 ThinkCMF 项目中基于 ThinkORM 的查询构造器，系统讲解链式调用语法、条件查询、连接查询、聚合查询、子查询与分页排序等能力，并结合源码路径定位关键实现，帮助开发者编写高效、可维护的数据库查询。

## 项目结构
围绕查询构造器的关键代码位于 ThinkORM 的 db 层，核心入口为抽象查询基类，配合 Concern 组合不同能力模块，最终由连接层执行 SQL。

```mermaid
graph TB
subgraph "应用层"
APP["业务控制器/服务<br/>使用 Db 门面发起查询"]
end
subgraph "查询层"
DBM["DbManager<br/>数据库管理器"]
FACADE["Db 门面"]
BASEQ["BaseQuery 抽象查询基类"]
CONC_W["WhereQuery 条件查询 Concern"]
CONC_A["AggregateQuery 聚合查询 Concern"]
PAGI["Paginator 分页器"]
end
subgraph "执行层"
CONN_I["ConnectionInterface 接口"]
CONN["Connection 实现"]
end
APP --> FACADE --> DBM --> BASEQ
BASEQ --- CONC_W
BASEQ --- CONC_A
BASEQ --> PAGI
BASEQ --> CONN_I --> CONN
```

图表来源
- [Db.php（门面）:21-32](file://vendor/topthink/think-orm/src/facade/Db.php#L21-L32)
- [DbManager.php](file://vendor/topthink/think-orm/src/DbManager.php)
- [BaseQuery.php:30-101](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L30-L101)
- [WhereQuery.php](file://vendor/topthink/think-orm/src/db/concern/WhereQuery.php)
- [AggregateQuery.php](file://vendor/topthink/think-orm/src/db/concern/AggregateQuery.php)
- [Paginator.php](file://vendor/topthink/think-orm/src/Paginator.php)
- [ConnectionInterface.php](file://vendor/topthink/think-orm/src/db/ConnectionInterface.php)
- [Connection.php](file://vendor/topthink/think-orm/src/db/Connection.php)

章节来源
- [Db.php（门面）:21-32](file://vendor/topthink/think-orm/src/facade/Db.php#L21-L32)
- [Db.php:20-117](file://vendor/topthink/framework/src/think/Db.php#L20-L117)
- [BaseQuery.php:30-101](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L30-L101)

## 核心组件
- 抽象查询基类 BaseQuery：提供链式方法、解析选项、执行查询、分页、缓存、锁读等通用能力。
- WhereQuery Concern：封装 where/andWhere/orWhere 等条件拼装逻辑。
- AggregateQuery Concern：封装 count/sum/avg/max/min 等聚合查询。
- Db 门面与 DbManager：对外暴露静态入口，管理连接与配置。
- Connection/ConnectionInterface：实际执行 SQL 的驱动层。

章节来源
- [BaseQuery.php:30-101](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L30-L101)
- [WhereQuery.php](file://vendor/topthink/think-orm/src/db/concern/WhereQuery.php)
- [AggregateQuery.php](file://vendor/topthink/think-orm/src/db/concern/AggregateQuery.php)
- [Db.php（门面）:21-32](file://vendor/topthink/think-orm/src/facade/Db.php#L21-L32)
- [Db.php:20-117](file://vendor/topthink/framework/src/think/Db.php#L20-L117)

## 架构总览
下面以“条件查询”和“聚合查询”的组合为例，展示从门面到具体执行的调用链路。

```mermaid
sequenceDiagram
participant C as "控制器/服务"
participant F as "Db 门面"
participant M as "DbManager"
participant Q as "BaseQuery"
participant W as "WhereQuery"
participant A as "AggregateQuery"
participant Conn as "Connection"
C->>F : "Db : : name('user')->where(...)"
F->>M : "获取/创建查询实例"
M->>Q : "newQuery()/name()/where()"
Q->>W : "解析并拼接 where 条件"
Q->>A : "解析聚合方法(count/sum/...)"
Q->>Conn : "执行 SQLselect/update/delete 等"
Conn-->>Q : "返回结果或影响行数"
Q-->>C : "链式返回集合/标量"
```

图表来源
- [Db.php（门面）:21-32](file://vendor/topthink/think-orm/src/facade/Db.php#L21-L32)
- [DbManager.php](file://vendor/topthink/think-orm/src/DbManager.php)
- [BaseQuery.php:159-186](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L159-L186)
- [WhereQuery.php](file://vendor/topthink/think-orm/src/db/concern/WhereQuery.php)
- [AggregateQuery.php](file://vendor/topthink/think-orm/src/db/concern/AggregateQuery.php)
- [Connection.php](file://vendor/topthink/think-orm/src/db/Connection.php)

## 详细组件分析

### 基础语法与链式调用
- 基类提供大量链式方法：field、where、order、limit、page、join、union、alias、cache、lock、master 等。
- 支持“移除查询参数”“设置/获取选项”“新建查询副本”等工具方法，便于复用与隔离。
- 新建查询副本时会复制表名、别名、JSON 映射、字段类型等上下文，避免污染原查询。

章节来源
- [BaseQuery.php:515-546](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L515-L546)
- [BaseQuery.php:669-689](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L669-L689)
- [BaseQuery.php:159-186](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L159-L186)

### 条件查询：where/andWhere/orWhere
- where：支持多种形式（字段比较、闭包、数组、表达式），内部将条件归一化并合并到 options['where']。
- andWhere/orWhere：通过 WhereQuery Concern 提供便捷别名，最终仍落到 where 的解析流程。
- 动态方法：如 whereName、whereOrName 等，可通过魔术方法自动映射到 where 条件。

```mermaid
flowchart TD
Start(["开始"]) --> Parse["解析 where 参数<br/>字符串/数组/闭包/Raw"]
Parse --> Merge["合并到 options.where"]
Merge --> Next{"是否还有条件？"}
Next --> |是| Parse
Next --> |否| Build["生成 where 子句"]
Build --> End(["结束"])
```

图表来源
- [WhereQuery.php](file://vendor/topthink/think-orm/src/db/concern/WhereQuery.php)
- [BaseQuery.php:129-141](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L129-L141)

章节来源
- [BaseQuery.php:129-141](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L129-L141)
- [WhereQuery.php](file://vendor/topthink/think-orm/src/db/concern/WhereQuery.php)

### 连接查询：innerJoin/leftJoin/rightJoin
- table/alias：支持多表与别名设置；join 时可配合 via 指定关联表别名。
- join：在解析阶段将连接信息写入 options['join']，最终由连接层渲染为 SQL。
- 注意：连接查询通常需配合 where 指定关联条件，建议显式写出 on 条件以提升可读性与性能。

章节来源
- [BaseQuery.php:698-708](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L698-L708)
- [BaseQuery.php:1088-1099](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L1088-L1099)
- [BaseQuery.php:1255-1260](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L1255-L1260)

### 聚合查询：count/sum/avg/max/min
- 聚合方法由 AggregateQuery Concern 提供，解析阶段将聚合字段与函数写入 options，最终由连接层生成聚合 SQL。
- 常见策略：
  - count：统计总数，常用于分页总记录数。
  - sum/avg/max/min：对数值字段做聚合，注意空集与 NULL 处理。
- 建议：在高频场景下结合索引与 where 条件，避免全表扫描。

章节来源
- [AggregateQuery.php](file://vendor/topthink/think-orm/src/db/concern/AggregateQuery.php)
- [BaseQuery.php:855-861](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L855-L861)

### 子查询与嵌套查询
- union/unionAll：支持将多个查询结果合并，适合跨表汇总或去重合并。
- table/closure：可在 table 中传入闭包，形成子查询来源；field 中可使用 Raw 包裹子查询表达式。
- 嵌套 where：通过闭包 where([...]) 将复杂条件分组，提升可读性与执行效率。

章节来源
- [BaseQuery.php:483-506](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L483-L506)
- [BaseQuery.php:515-546](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L515-L546)
- [BaseQuery.php:698-708](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L698-L708)

### 分页查询与排序
- paginate：支持简洁模式与完整模式，自动计算总记录数并生成分页对象；可配置每页数量、页码变量、URL 片段等。
- paginateX：基于主键索引的“基于游标”的分页，适合超大数据量场景，减少 offset 的性能损耗。
- more：按最后 ID 继续拉取 N 条，常用于“加载更多”。
- order：支持字符串或数组形式排序，可与 via 搭配限定字段表别名。

```mermaid
sequenceDiagram
participant S as "业务层"
participant Q as "BaseQuery"
participant C as "Connection"
participant P as "Paginator"
S->>Q : "paginate(listRows, simple)"
Q->>Q : "解析分页参数/生成分页配置"
Q->>C : "count() 计算总数非简单模式"
Q->>C : "select() 查询当前页数据"
C-->>Q : "结果集"
Q->>P : "Paginator : : make(...) 生成分页对象"
P-->>S : "分页结果"
```

图表来源
- [BaseQuery.php:829-882](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L829-L882)
- [BaseQuery.php:895-954](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L895-L954)
- [Paginator.php](file://vendor/topthink/think-orm/src/Paginator.php)

章节来源
- [BaseQuery.php:829-882](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L829-L882)
- [BaseQuery.php:895-954](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L895-L954)
- [Paginator.php](file://vendor/topthink/think-orm/src/Paginator.php)

### 复杂查询示例（方法路径）
以下为常见复杂查询的“方法路径参考”，请在业务代码中按需组合：
- 多条件与连接：先 field/alias，再 join/where，最后 order/limit/paginate
  - 示例路径参考：[BaseQuery.php:515-546](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L515-L546)、[BaseQuery.php:698-708](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L698-L708)、[BaseQuery.php:776-817](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L776-L817)
- 聚合统计：count/sum/avg/max/min
  - 示例路径参考：[AggregateQuery.php](file://vendor/topthink/think-orm/src/db/concern/AggregateQuery.php)
- 子查询：union/table(closure)/field(Raw)
  - 示例路径参考：[BaseQuery.php:483-506](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L483-L506)、[BaseQuery.php:515-546](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L515-L546)、[BaseQuery.php:698-708](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L698-L708)
- 分页与“加载更多”：paginate/paginateX/more
  - 示例路径参考：[BaseQuery.php:829-882](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L829-L882)、[BaseQuery.php:895-954](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L895-L954)、[BaseQuery.php:968-996](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L968-L996)

## 依赖关系分析
- 门面 Db 门面 -> DbManager -> BaseQuery
- BaseQuery 通过 Concern 组合 Where/Aggregate 等能力
- BaseQuery 依赖 ConnectionInterface/Connection 执行 SQL
- Paginator 作为分页结果载体，与 BaseQuery 的分页方法协作

```mermaid
classDiagram
class DbFacade {
+getFacadeClass()
}
class DbManager {
+newQuery()
}
class BaseQuery {
+field()
+where()
+order()
+paginate()
+select()
+find()
}
class WhereQuery
class AggregateQuery
class ConnectionInterface
class Connection
class Paginator
DbFacade --> DbManager : "门面路由"
DbManager --> BaseQuery : "创建查询实例"
BaseQuery ..> WhereQuery : "use"
BaseQuery ..> AggregateQuery : "use"
BaseQuery --> ConnectionInterface : "执行"
ConnectionInterface <|.. Connection : "实现"
BaseQuery --> Paginator : "生成分页结果"
```

图表来源
- [Db.php（门面）:21-32](file://vendor/topthink/think-orm/src/facade/Db.php#L21-L32)
- [DbManager.php](file://vendor/topthink/think-orm/src/DbManager.php)
- [BaseQuery.php:30-101](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L30-L101)
- [WhereQuery.php](file://vendor/topthink/think-orm/src/db/concern/WhereQuery.php)
- [AggregateQuery.php](file://vendor/topthink/think-orm/src/db/concern/AggregateQuery.php)
- [ConnectionInterface.php](file://vendor/topthink/think-orm/src/db/ConnectionInterface.php)
- [Connection.php](file://vendor/topthink/think-orm/src/db/Connection.php)
- [Paginator.php](file://vendor/topthink/think-orm/src/Paginator.php)

## 性能考量
- 使用索引字段作为 where 条件，优先命中索引。
- 聚合查询尽量带 where 条件，避免全表扫描；必要时使用复合索引。
- 分页场景优先考虑 paginateX（基于主键游标）替代传统 offset 分页，降低大偏移成本。
- 合理使用 cache/cacheAlways/cacheForce 控制查询缓存，避免频繁重复查询。
- order 与 where 同时存在时，确保排序字段上有合适索引。
- 子查询尽量物化或改写为 JOIN，减少嵌套层级与临时结果集。

## 故障排查指南
- 缺少更新/删除条件异常：当 update/delete 未设置 where/scope 时会抛出异常，需显式设置条件或使用软删除配置。
  - 参考路径：[BaseQuery.php:1382-1389](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L1382-L1389)、[BaseQuery.php:1427-1430](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L1427-L1430)
- miss update condition：更新时必须有明确条件，否则抛错。
  - 参考路径：[BaseQuery.php:1382-1389](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L1382-L1389)
- delete without condition：删除时同样要求条件明确。
  - 参考路径：[BaseQuery.php:1427-1430](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L1427-L1430)
- 分页总数为 0：paginate 在 total 为 0 时会返回空集合，注意前端提示。
  - 参考路径：[BaseQuery.php:861-870](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L861-L870)

章节来源
- [BaseQuery.php:1382-1389](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L1382-L1389)
- [BaseQuery.php:1427-1430](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L1427-L1430)
- [BaseQuery.php:861-870](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L861-L870)

## 结论
ThinkCMF 的查询构造器以 BaseQuery 为核心，通过 Concern 组合条件、聚合、关系等能力，配合 Db 门面与 DbManager 提供统一入口。遵循“先条件、后聚合、再分页”的思路，合理使用索引与缓存，可显著提升查询性能与可维护性。

## 附录：常用方法速查
- 基础链式：field、table、alias、via、order、limit、page、union/unionAll、lock、master、cache、strict、sequence、json、lazyFields、pk
- 条件：where、andWhere、orWhere、闭包 where([...])、Raw 表达式
- 聚合：count、sum、avg、max、min
- 连接：join（内/左/右/交叉）、on 条件
- 分页：paginate、paginateX、more
- 执行：select、find、insert/insertGetId/insertAll、update、delete、save

章节来源
- [BaseQuery.php:515-546](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L515-L546)
- [BaseQuery.php:698-708](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L698-L708)
- [BaseQuery.php:776-817](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L776-L817)
- [BaseQuery.php:829-882](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L829-L882)
- [BaseQuery.php:895-954](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L895-L954)
- [BaseQuery.php:968-996](file://vendor/topthink/think-orm/src/db/BaseQuery.php#L968-L996)
- [AggregateQuery.php](file://vendor/topthink/think-orm/src/db/concern/AggregateQuery.php)
- [WhereQuery.php](file://vendor/topthink/think-orm/src/db/concern/WhereQuery.php)