ThinkPHP6多对多关联模型belongsToMany配置详解

ThinkPHP 6.x 框架中，多对多关联关系的正确配置方法是使用 `belongsToMany` 方法。请注意，方法名必须准确无误，不能使用 `_belongsToMany` 或 `belongToMany` 等错误拼写。同时，为确保关联查询的精确性，建议显式传递全部六个参数，包括：关联模型类、中间表名、当前模型外键、关联模型外键、当前模型主键以及关联模型主键。若需访问中间表的额外字段（即 pivot 数据），则必须建立对应的中间模型，并通过 `through` 方法进行指定。

在 ThinkPHP 6.x 框架中进行多对多关联配置时，对方法名称和参数顺序的准确性要求极高。任何一个字母的拼写错误，或是遗漏了某个参数，都可能导致整个关联功能失效。更棘手的是，框架可能不会抛出明确的错误信息，而是直接返回一个空的数据集合，这给问题排查带来了不小的困难。

belongsToMany 方法名与参数顺序必须准确

首先，关联方法必须严格命名为 `belongsToMany`。使用 `_belongsToMany` 或 `belongToMany` 等变体都是无效的，框架无法识别，关联关系将无法建立。

该方法的完整签名格式如下：

belongsToMany(关联模型类, 中间表名, 当前模型外键, 关联模型外键, 当前主键, 关联主键)

这六个参数必须全部显式传递，即使您的主键和外键默认名称都是 `id`，也需要完整地填写两次。以下是一个标准的配置示例：

public function roles(){
    return $this->belongsToMany(Role::class, 'sys_user_role', 'uid', 'rid', 'id', 'id');
}

• 第二个参数 `'sys_user_role'` 指定的是中间表的表名，注意此处无需包含数据库前缀。
• 第三个参数 `'uid'` 是当前模型（例如 User 模型）在中间表中对应的外键字段名，必须与数据库中的实际字段名（包括大小写）完全一致。
• 第四个参数 `'rid'` 是关联模型（例如 Role 模型）在中间表中的外键字段名。
• 第五个和第六个参数默认值为 `'id'`，但如果您的模型主键并非 `id`（例如使用 `user_id` 或 `role_code`），则必须在此处进行相应修改。

中间表字段不匹配导致数据查询失败（无错误提示）

ThinkPHP 默认遵循一些命名约定，例如它会按照字母顺序自动拼接表名（生成类似 `role_user` 的表名），并假设外键名为 `user_id` 和 `role_id`。如果您的数据库设计未遵循这些约定，例如中间表名为 `sys_user_role`，字段使用 `uid` 和 `rid`，但您未在 `belongsToMany` 方法中明确声明，框架就会去查询一个不存在的表。其结果是返回空数据，且调试日志中可能找不到相关的 SQL 查询记录。

如何验证？您可以开启调试模式，检查日志中是否存在类似 `SELECT * FROM `sys_user_role` WHERE `uid` = ?` 的查询语句。如果没有，基本可以确定是参数配置不匹配。

• 最可靠的实践是始终显式传递全部六个参数，避免依赖框架的默认约定。
• 如果您的中间表在数据库中带有前缀（例如 `tp_sys_user_role`），那么在 `belongsToMany` 方法的第二个参数中只需填写 `'sys_user_role'` 即可，表前缀由数据库配置文件统一管理。
• 还需注意字段名的大小写问题，MySQL 在某些配置下是严格区分大小写的。

访问中间表额外字段（如 created_at、status）需创建中间模型并使用 through

仅使用 `belongsToMany` 方法，您只能获取到关联的模型实例（例如 Role），而中间表中的额外字段（如创建时间 `created_at`、状态 `status`、排序 `sort` 等）不会被加载。若想访问 `$role->pivot->created_at` 这类数据，必须通过中间模型来实现。

首先，需要创建一个中间模型（例如命名为 `UserRole`），继承 `think\Model`，并指定其对应的表名：

namespace app\model;
use think\Model;
class UserRole extends Model{
    protected $name = 'sys_user_role';
}

然后，在 User 模型中修改关联方法，使用 `through` 方法指定中间模型：

public function roles(){
    return $this->belongsToMany(Role::class)
                ->through(UserRole::class);
}

• 中间模型的类名需要传递完整的命名空间路径，或使用 `::class` 语法。
• 中间模型本身通常无需定义复杂的关联方法，只要确保其表名和主键配置正确即可。
• 完成配置后，通过 `$user->roles` 获取的每个 `Role` 对象都会附带一个 `pivot` 属性，其中包含了中间表（`UserRole`）对应数据行的所有字段。

在 with 闭包中使用 where 条件可能覆盖原始查询逻辑

在对多对多关联进行预加载（`with`）并附加筛选条件时，有一个常见的陷阱。您不能直接在闭包中使用 `$query->where(...)`，因为这可能会覆盖框架为关联查询自动生成的 `IN` 条件，导致最终只查询到一条记录，甚至查询结果为空。

正确的做法是，先获取底层的查询对象（`Query`），再在其上添加条件：

$data = User::where('status', 1)
    ->with(['roles' => function ($query) {
        $query->getQuery()->where('roles.status', 1)->order('sort desc');
    }])
    ->select();

• 关键在于使用 `$query->getQuery()` 来获取底层的 `Query` 对象，然后在该对象上调用 `where` 和 `order` 等方法。
• 如果直接使用 `$query->where(...)`，会破坏关联查询中用于匹配中间表记录的 `IN` 逻辑，SQL 语句可能只剩下一个简单的等值条件。
• 另外，需要注意字段的别名问题，关联表的字段通常需要带上表别名，例如使用 `'roles.status'`，而不是 `'role.status'`。

最后，补充一个与框架版本相关的细节。在 ThinkPHP 6.0.7 版本中，`getRelation` 方法存在一个可能导致 `pivot` 数据丢失的 Bug。如果您发现通过关联获取到的 `$role->pivot` 是空数组，可以检查一下框架版本。临时的解决方案是，将 `vendor/topthink/think-orm/src/model/relation/BelongsToMany.php` 文件中的 `getRelation` 方法替换为 6.0.3 版本的实现。