Laravel使用efficient-uuid时with关联查询返回空结果问题排查

问题背景 #

在Laravel项目中使用efficient-uuid包处理UUID生成、转换与解析，此前运行正常，现出现关联查询异常：请求返回的用户关联Role数据为空数组，生成的SQL语句显示 select * from role where role.user_id in (NULL)。

相关代码与配置 #

查询写法

写法1：

$roles = Role::with('role')->whereUuid($db_token->user_id)->get();

写法2：

$user = User::with('roles')
    ->select(['*'])
    ->whereUuid($db_token->user_id)
    ->first();

模型关联定义

User.php：

public function roles()
{
    return $this->hasMany(Role::class, 'user_id', 'role_id');
}

Role.php：

public function role(): \Illuminate\Database\Eloquent\Relations\BelongsTo
{
    return $this->belongsTo(User::class);
}

数据库表结构

• 用户表：使用efficientUuid('user_id')作为主键
• 角色表：使用efficientUuid('user_id')作为外键关联用户表

排查思路 #

1. 修正模型关联的明显错误 #

关联定义参数不匹配是导致SQL生成异常的常见原因：

• User模型的hasMany关联：hasMany的第二个参数是关联表的外键，第三个参数是当前模型的主键。原代码错误将第三个参数设为role_id，正确写法应为：

  public function roles()
  {
      return $this->hasMany(Role::class, 'user_id'); // 第三个参数默认是当前模型主键user_id，可省略
  }
  

• Role模型的belongsTo关联：关联方法名应与关联模型对应（应为user而非role），同时需明确指定外键字段：

  public function user(): \Illuminate\Database\Eloquent\Relations\BelongsTo
  {
      return $this->belongsTo(User::class, 'user_id');
  }
  

2. 验证$db_token->user_id的有效性 #

• 直接输出$db_token->user_id的值，确认它并非null或无效UUID格式；
• 尝试用主键直接查询用户：User::find($db_token->user_id)，若无法查到用户，说明UUID格式或转换存在问题，需检查efficient-uuid的转换逻辑是否正确处理了该值。

3. 检查efficient-uuid的模型配置 #

• 确保User和Role模型正确设置了主键属性：

  protected $keyType = 'string';
  public $incrementing = false;
  

• 测试whereUuid方法的SQL生成：执行User::whereUuid($validUuid)->toSql()，查看生成的SQL是否正确绑定了UUID值，而非NULL。

4. 验证数据库中的关联数据 #

• 直接在数据库中执行查询（注意若UUID存储为二进制，需先转换格式）：SELECT * FROM role WHERE user_id = '目标用户UUID'，确认是否存在真实的关联角色数据，排除数据本身为空的情况。

5. 开启查询日志排查完整执行链 #

启用Laravel查询日志，查看完整的查询流程：

\DB::enableQueryLog();
$user = User::with('roles')->whereUuid($db_token->user_id)->first();
dd(\DB::getQueryLog());

重点检查：用户查询是否返回了正确的user_id，后续预加载角色的SQL是否使用了该user_id，而非NULL。

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