关键在控制条件注入时机、隔离参数作用域、保持链式完整性：需用when()显式判真并return查询对象，field()仅在关联闭包或定义中生效，buildSql()调试后须用select()执行，推荐Trait封装复用逻辑。
ThinkPHP 8.0 中构建真正灵活、安全、可复用的动态查询构建器，关键不在“堆 where”，而在**控制条件注入时机、隔离参数作用域、保持链式完整性**。直接拼接或盲目调用容易出错、难调试、易漏判空，也不利于后续扩展。
用 when() 实现零干扰的条件注入
when() 是 TP8.0 官方推荐的动态条件入口，但必须满足两个硬性前提：第一个参数需明确判真（不能依赖 PHP 松散比较），闭包内必须显式 return 查询对象。
- 正确写法示例：
->when(!is_null($status), function ($query) use ($status) {<br> return $query->where('status', $status);<br>}) - 对数组类参数（如 $ids）务必前置判空：
->when(!empty($ids), function ($query) use ($ids) {<br> return $query->whereIn('id', $ids);<br>}) - 避免误判：字符串 "0"、数字 0、空字符串 "" 都会被 when 当作 false 跳过——若业务需支持 status=0，就得改用
->when($status !== '' && $status !== null, ...)
字段精简与关联裁剪同步控制
动态查询不只是加条件，也包括减字段。TP8.0 中 field() 对主模型有效，但对关联字段无效；真正生效的裁剪点只在关联定义内部或 with() 的闭包中。
- 在模型关联方法里固化常用字段（含外键）：
public function profile() {<br> return $this->hasOne(Profile::class)->field(['user_id', 'nickname', 'avatar']);<br>} - 运行时按需裁剪（不同接口不同字段）：
User::with(['profile' => function ($q) {<br> $q->field(['user_id', 'nickname']);<br>}])->select(); - 注意：闭包中 field() 只接受纯字段名列表，不支持表前缀（如 profile.nickname），否则被忽略；每个关联需独立写 field()，不可复用同一 $query 实例
获取 Query 实例，延迟执行与调试分离
真正灵活的构建器，必须能“拿在手里不执行”。TP8.0 中 Db::table() 和 Db::name() 返回的都是 think\db\Query 实例，所有中间方法（where/order/limit）都返回自身，只有 select()/find()/value() 等末尾方法才触发执行。
- 先构造，后执行：
$query = Db::table('user')->where('status', 1)->order('created_at', 'desc');<br>// 此时未查库，$query 可继续链式追加<br>$users = $query->limit(20)->select(); // 到这里才真正执行 - 调试 SQL（不含参数值）：
echo $query->buildSql(); // 输出 SELECT * FROM `user` WHERE `status` = ? ORDER BY `created_at` DESC - 查看绑定参数：
var_dump($query->getBind()); // 显示 ['status' => 1] - ⚠️ buildSql() 结果仅用于调试，不能直接拼接执行；真实查询必须走 select()，由 PDO 完成参数绑定与防注入
封装可复用的条件组装 Trait（长期推荐）
当项目中多处出现相似的动态筛选逻辑（如时间范围 + 状态 + 关键词），建议抽离为 Trait，避免重复判断和硬编码。
- 定义 trait：
trait Searchable<br>{<br> public function scopeSearch($query, $params)<br> {<br> if (!empty($params['q'])) {<br> $query->where('name', 'like', "%{$params['q']}%");<br> }<br> if (isset($params['start_time']) && isset($params['end_time'])) {<br> $query->whereBetween('created_at', [$params['start_time'], $params['end_time']]);<br> }<br> return $query;<br> }<br>} - 在模型中使用：
use Searchable;<br>// ...<br>User::scopeSearch($query, $request->only(['q', 'start_time', 'end_time']))->select();
- 优势：逻辑集中、测试友好、便于统一加缓存或审计日志
