PHP Eloquent 关系字段 怎样处理

Eloquent 预加载关系时裁剪字段，必须保留关系匹配需要的键；接口不想输出这些键，应在响应层明确挑选字段，而不是先从查询里删掉。下面只讨论工单属于客户的 belongsTo 关系，不把同一套列清单直接套用到多对多或多态关系。

官方文档入口：https://laravel.com/framework/docs/13.x/eloquent-relationships。示例以 Laravel 13.x 文档核对常规关系语义，旧项目应对应自己的框架版本。这里使用原创假设业务，不声称来自生产事故或已经运行的性能实验。

先把查询列、关联键和响应字段分开

设想一个已授权的工单列表：页面只需工单编号、标题和客户显示名称，开发者希望少查几个字段，却发现客户关系突然为空。我更倾向于先列出三份清单：数据库要读取哪些列、模型靠什么键匹配、接口承诺输出什么字段。三者有关联，但不能简单画等号。

本例约定 tickets 包含 id、customer_id、subject；customers 包含 id、display_name，以及接口不需要的其他业务字段。查询中的 customer_id 是工单的外键，customers.id 是客户的所有者键。它们是内部匹配所需信息，不代表一定要出现在最终 JSON 中。

同时，字段裁剪不是授权。工单是否属于当前用户能访问的范围，客户名称是否允许对当前角色展示，都应由应用的身份与授权机制决定。本文不提供绕过这些前置条件的公开查询端点。

在模型中写明关系究竟使用哪两个键

将下面的方法放到已有的 Ticket 模型内，并按项目规范导入类型。假定 Customer 也位于 App\Models。类中原有的表名、连接及其他配置继续保留，不用示例覆盖整份模型。

use Illuminate\Database\Eloquent\Relations\BelongsTo;

// 放在已有 Ticket 模型内：明确本地外键与客户所有者键
public function customer(): BelongsTo
{
    return $this->belongsTo(Customer::class, 'customer_id', 'id');
}

customer() 返回关系对象，customer 动态属性用于访问关系数据。查询代码要和这条定义配套，不能因为字段显示成“客户名称”，就把关联键也换成名称。名称可能重复，重命名也不应改变记录身份。

如果真实项目使用 customer_code 与 customers.code，应以实际关系定义为准，检查唯一性、类型及需要保留的列，不能继续生搬 id。我的判断是：先明确键语义，再做列裁剪，通常比看到空值后到处补字段更容易维护。

裁剪列时保留工单外键与客户主键

下面是已有应用服务或控制器中的查询片段。变量 $authorizedTicketQuery 是前置授权逻辑提供的 Ticket Eloquent Builder，已包含当前用户允许访问的工单范围；它不是框架自动提供的变量，不能直接替换成无限制的全表查询。示例通过明确参数控制最多读取 30 条。

// 前置条件：已通过授权逻辑获得 Ticket Builder，范围限制不得删除
$tickets = $authorizedTicketQuery
    // customer_id 参与 belongsTo 匹配，不能因接口不显示就删掉
    ->select(['tickets.id', 'tickets.customer_id', 'tickets.subject'])
    // 客户 id 是匹配键，display_name 是本接口需要的业务列
    ->with('customer:id,display_name')
    ->orderBy('tickets.id')
    ->limit(30)
    ->get();

这里有两处容易混淆：主查询裁剪工单字段，with 中裁剪客户字段，二者并不是同一张表的列列表。若从主查询拿掉 customer_id，模型失去属于哪个客户的信息；若关联查询不取 id，则缺少把客户结果匹配回工单的关键列。

官方关系文档也提醒，指定预加载列时需要保留 id 和相关外键。具体到当前 belongsTo 方向，外键在工单侧，客户侧保留所有者键。反方向 hasMany 的外键位置不同，不能只记住“每个查询都随便加一个 id”。

把响应做成明确字段，而不是返回整个模型

查询拿到内部键后，我会在接口边界显式构造返回结构。下面代码紧接上一段使用同一组 tickets；它不直接对模型调用 toArray，也不会把客户的所有属性递归展开。

use App\Models\Ticket;

// 显式构造接口字段，读取关系前先确认已经预加载
$items = $tickets->map(function (Ticket $ticket): array {
    if (! $ticket->relationLoaded('customer')) {
        // 配置遗漏应显式暴露，避免在循环里悄悄追加查询
        throw new \LogicException('customer relation must be loaded');
    }

    $customer = $ticket->getRelation('customer');

    return [
        'id' => $ticket->id,
        'subject' => $ticket->subject,
        // 无可见关联记录时保留 null，不编造客户信息
        'customer' => $customer === null ? null : [
            'display_name' => $customer->display_name,
        ],
    ];
})->values();

return response()->json(['data' => $items]);

输出仅有 id、subject 和 customer.display_name；内部 customer_id、客户 id 不在这个响应结构中。这个字段约定是示例设计，不是框架默认 JSON 格式。如果客户不存在、被关系约束或全局作用域排除，本例返回 customer 为 null，不能由此直接断言数据库发生了孤儿记录。

Eloquent 的模型序列化可以包含已加载关系，隐藏属性也属于序列化控制；这些机制和“查询没有读取该列”不是一回事。团队若采用 API Resource，可以把响应约定集中到资源类，但仍需维持授权与查询列的独立职责。

排查记录只保留必要元信息

关系为空时，建议按关系是否已加载、主模型外键是否读取、客户查询的匹配列是否保留、作用域是否过滤逐项判断。不要用输出整条客户模型的方式“快速调试”，这可能把不属于接口合同的字段带进日志。

如果需要排查记录，可考虑请求标识、接口名称、返回工单条数、缺失关系条数及所用字段配置版本。是否记录业务标识应遵循团队数据治理要求；不要记录完整 SQL 绑定值、凭据或整个模型快照。日志是排查辅助，不能替代权限控制。

我不会把“少查几个列”直接描述成性能必然提升。字段宽度、查询计划、数据量和模型处理方式都会影响结果，收益应在真实工作负载下评估。当前示例强调关联正确与输出明确，没有给出测得的内存或耗时数字。

上线前看清空关系与字段变化的含义

为什么 with 已经写了，关系仍然为空？预加载不是对匹配结果的保证，还要看键值和查询约束。为什么不直接返回 toArray？它的职责是模型序列化，而本接口希望明确固定输出范围。能否把外键设为隐藏再删掉 select 中的外键？不可以，隐藏输出与保留匹配信息解决的是两个问题。

对我来说，适合生产维护的做法不是不断添加补丁，而是让关系定义、查询字段和响应合同相互对应。先保住匹配所需的键，再精确控制输出，才能避免一次看似简单的字段精简改变接口含义。

参考：Laravel Eloquent 关系与指定列预加载；Laravel Eloquent 序列化。