Laravel自定义Batch模型hasOne关联预加载返回Null问题排查

以下是几种常见的原因和对应的解决办法：

1. 主键类型不匹配 #

Batch模型用UUID作为主键（字符串类型），但如果没在模型里明确声明主键类型，Laravel预加载时会默认按整数类型生成查询SQL，导致用整数去匹配UUID字符串，自然查不到数据。

解决办法：
在Batch模型里指定主键相关配置：

class Batch extends Model
{
    protected $primaryKey = 'id'; // 确保主键名正确
    protected $keyType = 'string'; // 主键为字符串类型
    public $incrementing = false; // 非自增主键
}

同时确认CsvExport模型的关联定义参数正确：

class CsvExport extends Model
{
    public function batch()
    {
        // hasOne参数顺序：关联模型，关联模型的主键，当前模型的外键
        return $this->hasOne(Batch::class, 'id', 'batch_id');
    }
}

2. 全局作用域过滤了数据 #

如果Batch模型有全局作用域（比如软删除SoftDeletes），预加载时会自动应用这个作用域，若目标Batch数据被软删除，预加载就会返回null；这种情况下需要显式包含已删除数据：

CsvExport::with(['batch' => function($query) {
    $query->withTrashed();
}])->find(1);

另外检查Batch模型是否有其他自定义全局作用域，是否过滤掉了目标数据。

3. 关联定义的外键顺序错误 #

hasOne方法的参数顺序很容易搞反：第一个是关联模型，第二个是关联模型的主键字段，第三个是当前模型的外键字段。如果顺序写反了，预加载生成的SQL会用错误的字段关联，导致查不到数据。

比如错误写法：

return $this->hasOne(Batch::class, 'batch_id', 'id');

这种情况下预加载会拿CsvExport的id去匹配Batch的batch_id，自然找不到对应数据，需调整为正确的参数顺序。

4. 模型表名配置错误 #

如果Batch模型没有指定表名，Laravel会默认用类名的复数形式（batches），但你的实际表是job_batches，这会导致预加载时查询错误的表，返回null。

解决办法：在Batch模型里指定表名：

class Batch extends Model
{
    protected $table = 'job_batches';
}

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