Laravel Eloquent关联查询生成矛盾SQL的问题排查

问题场景 #

User模型定义 #

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;

class User extends Model
{
    protected $table = 'user';
    protected $primaryKey = 'userId';
    public $timestamps = false;
    
    protected $fillable  = [
        'name',
        'email'
    ];

    public function address(): HasMany
    {
        return $this->hasMany(Address::class);
    }
}

Address模型定义 #

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class Address extends Model
{
    protected $table = 'address';
    protected $primaryKey = 'addressId';
    public $timestamps = false;
    
    protected $fillable  = [
        'addressLine1',
        'addressLine2',
        'county',
        'postcode'
    ];

    public function user()
    {
        return $this->belongsTo(User::class);
    }
}

执行的查询代码 #

$this->userModel->address()->where('userId', $userLoginData['userId'])->get();

生成的SQL语句 #

select * from `address` where `address`.`userId` is null and `address`.`userId` is not null and `userId` =?

核心原因 #

1. 关联定义未适配自定义主键/外键 #

Laravel默认关联键规则为：

• hasMany关联自动使用模型小写名+_id作为外键（如user_id），同时默认以当前模型的id作为本地主键。
  但你的场景中：
• User模型主键是自定义的userId，而非默认的id；
• Address表的外键是userId，而非Laravel默认预期的user_id。
  未在关联定义中明确指定这些自定义键名，导致Laravel生成错误的关联条件。

2. 调用关联的模型实例未加载主键值 #

如果$this->userModel是未从数据库获取的空实例（比如直接new User()创建，而非通过User::find()等方法获取的有效用户模型），Laravel会认为要查询关联到"无主键用户"的地址，自动添加address.userId is null的条件。
此时手动添加的where('userId', $userLoginData['userId'])与自动生成的条件冲突，最终出现矛盾的SQL语句，导致无结果返回。

解决方法 #

修正关联定义 #

在两个模型的关联方法中明确指定自定义的外键和本地键：

User模型的address方法

public function address(): HasMany
{
    // 参数依次为：关联模型类、关联表的外键字段、当前模型的主键字段
    return $this->hasMany(Address::class, 'userId', 'userId');
}

Address模型的user方法

public function user(): BelongsTo
{
    // 参数依次为：关联模型类、当前表的外键字段、关联模型的主键字段
    return $this->belongsTo(User::class, 'userId', 'userId');
}

修正查询逻辑 #

确保调用关联的是已加载的有效用户实例，无需手动添加外键条件：

// 先获取数据库中存在的用户实例
$user = User::find($userLoginData['userId']);
// 直接通过关联获取地址，Laravel会自动添加正确的外键条件
$addresses = $user->address;
// 如需额外筛选，可链式调用查询方法
$addresses = $user->address()->where('county', 'xxx')->get();

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