Laravel Eloquent模型关联查询部分记录返回null问题排查求助

排查步骤 #

• 检查模型主键类型配置
  你使用UUID作为主键，需要确认Invoice模型中是否正确配置了主键类型、关闭自增：

  // Invoice模型内必须添加以下配置
  protected $primaryKey = 'id';
  public $incrementing = false;
  protected $keyType = 'string';
  protected $casts = [
      'id' => 'string',
      // 其他字段转换
  ];
  

  如果没关闭自增、没将keyType设为string，Eloquent会默认将UUID主键转为整型处理，关联匹配时会出现值转换错误，导致部分看起来ID匹配的记录关联不上。同时确认InvoiceCustomer模型的invoice_id也在$casts中设为string类型。
• 验证whereHas写法正确性
  你给出的查询写法Invoice::whereHas(['customer'])->get()是不规范的，whereHas第一个参数应为关联名字符串，传数组是带嵌套关联条件的写法。如果要同时过滤存在关联且加载关联数据，正确写法为：

  Invoice::whereHas('customer')->with('customer')->get();
  

  仅调用whereHas只会过滤出存在关联的Invoice记录，不会自动预加载customer关联，你看到的2条关联数据可能是之前其他地方加载过的父模型附带的，属于巧合。
• 排查全局作用域干扰
  检查InvoiceCustomer模型中是否定义了全局查询作用域（比如状态过滤、公司ID过滤等），那一条加载失败的关联数据可能不符合全局作用域的过滤条件，被ORM自动排除。可以在查询时加withoutGlobalScopes()测试：

  $invoice = Invoice::find(出问题的InvoiceID);
  $customer = $invoice->customer()->withoutGlobalScopes()->first();
  var_dump($customer); // 查看是否能拿到数据
  

• 核对UUID大小写匹配问题
  如果数据库表的排序规则为大小写敏感（比如utf8mb4_bin），需要确认invoices.id和invoice_customers.invoice_id的大小写完全一致，大小写不一致会导致关联匹配失败。
• 打印执行SQL定位问题
  可以通过查询日志打印最终执行的关联查询SQL，直接在数据库中运行验证匹配结果：

  \DB::enableQueryLog();
  Invoice::whereHas('customer')->with('customer')->get();
  dd(\DB::getQueryLog());
  

  拿关联查询的SQL代入出问题的invoice ID执行，就能判断是数据库层面匹配不到，还是ORM转换后的值异常导致的问题。

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