Laravel模型中::query()方法的使用场景、优势及规范是什么

User::where()这类静态调用查询方法的写法，本质是依赖Eloquent模型的魔术方法__callStatic做转发：调用时PHP会先new一个当前模型的实例，再通过实例的__call魔术方法初始化查询构造器，最终转发调用对应的查询方法。
而User::query()是显式调用方法，直接返回绑定了当前模型的Illuminate\Database\Eloquent\Builder查询构造器实例，后续所有链式调用都是直接调用查询构造器的真实方法，不存在魔术转发逻辑。

除了你提到的IDE代码提示更准确之外，::query()还有几个实际开发中很有用的优势：

核心优势 #

• 避免方法名冲突
  如果你在模型中自定义了和查询方法同名的静态方法（比如自定义where()方法实现特殊权限过滤），直接静态调用会优先执行你自定义的方法，不会走原生查询逻辑。而::query()返回的是查询构造器实例，后续链式调用永远走查询构造器的原生方法，不会被模型自定义方法覆盖，不会出现意料之外的逻辑错误。
• 动态条件拼接更顺畅
  写列表页接口这类需要根据请求参数动态追加查询条件的场景时，可以先初始化查询实例，再按需追加条件，不需要写无意义的初始条件兜底：

  // 动态拼接查询示例
  $userQuery = User::query();
  // 按用户名筛选
  if ($keyword = request('keyword')) {
      $userQuery->where('name', 'like', "%{$keyword}%");
  }
  // 按账号状态筛选
  if ($status = request('status')) {
      $userQuery->where('status', $status);
  }
  $userList = $userQuery->paginate(15);
  

  如果不用query()初始化，你要么得写User::where('id', '>', 0)这种没实际意义的初始条件，要么得多层嵌套when()方法，可读性差很多。
• 自定义方法识别更稳定
  如果你通过查询构造器的Macro机制扩展了自定义查询方法，或者在模型中定义了复杂的关联查询、全局作用域，直接静态调用时IDE和静态检测工具（PHPStan/Larastan）经常无法识别这些方法，会报"方法不存在"的误报。用query()显式拿到Builder实例后，只要做好类型提示，所有扩展方法、关联方法都能被正常识别，不会出现误报。
• 可测试性、复用性更强
  显式拿到的查询构造器实例可以被传递到其他类/方法中复用公共查询逻辑，单元测试时也可以方便地对查询实例做Mock，拦截、替换查询逻辑。静态魔术调用的方式很难被Mock，测试成本高很多。

使用规范指引 #

• 单行简单固定条件查询，两种写法性能、执行逻辑完全一致，直接用静态调用写法更简洁，比如User::where('is_active', 1)->get()这种场景不需要刻意加query()。
• 只要涉及动态条件拼接、查询逻辑复用、调用自定义查询Macro/复杂关联查询的场景，统一用::query()初始化查询实例，减少隐性bug和IDE误报。
• 团队如果接入了Larastan这类静态检测工具，建议统一查询写法用::query()开头，可以大幅降低静态检测的误报率，提升代码一致性。
• 注意不要在query()获取实例后、执行查询（get/first/paginate等）前，手动修改查询实例绑定的模型，避免查询绑定错误。

补充：两种写法最终生成的执行SQL完全一致，不存在性能差异，区别只在开发阶段的可维护性、类型安全性上。

内容的提问来源于stack exchange，提问作者Lui229