如何重构Eloquent集合以优化API数据访问结构？

嘿，这个需求在Eloquent里其实有好几种实用的实现方式，我给你梳理几个最适合的方案，都能完美支持单个对象和列表场景：

1. 推荐：使用Eloquent资源类（Resource Classes） #

这是Laravel官方推荐的API响应格式化方案，专门用来统一API输出结构，天然支持单个模型和集合两种场景，可维护性拉满。

步骤： #

• 首先生成一个资源类：

php artisan make:resource ObjectResource

• 打开生成的app/Http/Resources/ObjectResource.php，修改toArray方法定义你的目标结构：

<?php

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

class ObjectResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @return array<string, mixed>
     */
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'type' => $this->type,
            'text' => [
                'title' => $this->title,
                'shorttext' => $this->shorttext,
                'spacetext' => $this->spacetext,
                'description' => $this->description,
            ],
        ];
    }
}

• 在控制器里使用：
  • 单个对象请求：

  // 注意这里用first()而不是get()，因为单个对象不需要集合
  return new ObjectResource($this->where('id', $id)->first());
  

  • 列表请求：

  return ObjectResource::collection($this->select('objects.*')->get());
  

这个方案的优势是结构集中管理，以后要调整字段或者格式，只需要修改资源类，不会污染模型或控制器代码，完全符合REST API的最佳实践。

2. 快速实现：使用集合的transform()方法 #

如果只是临时需求或者不想创建资源类，用transform()方法可以快速处理集合和单个模型：

单个对象场景： #

$object = $this->where('id', $id)->first();

// 处理空对象的情况
$data = $object ? [
    'id' => $object->id,
    'type' => $object->type,
    'text' => [
        'title' => $object->title,
        'shorttext' => $object->shorttext,
        'spacetext' => $object->spacetext,
        'description' => $object->description,
    ],
] : [];

return response()->json($data);

列表场景： #

$data = $this->select('objects.*')->get()->transform(function ($item) {
    return [
        'id' => $item->id,
        'type' => $item->type,
        'text' => [
            'title' => $item->title,
            'shorttext' => $item->shorttext,
            'spacetext' => $item->spacetext,
            'description' => $item->description,
        ],
    ];
});

return response()->json($data);

3. 全局生效：模型追加自定义属性 #

如果希望这个结构在所有模型实例返回时都生效，可以在模型里定义访问器并追加属性：

在模型类中添加： #

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Object extends Model
{
    // 自动追加text属性到模型数组/JSON输出
    protected $appends = ['text'];

    // 隐藏原来的文本字段，避免重复输出
    protected $hidden = ['title', 'shorttext', 'spacetext', 'description'];

    /**
     * 定义text属性的访问器
     */
    public function getTextAttribute()
    {
        return [
            'title' => $this->title,
            'shorttext' => $this->shorttext,
            'spacetext' => $this->spacetext,
            'description' => $this->description,
        ];
    }
}

这样之后，不管你是查询单个模型还是集合，返回的结构都会自动包含text字段，并且隐藏原来的单独文本字段。不过这个方法是全局生效的，如果某些场景不需要这个结构，可能需要额外处理，所以更适合所有地方都需要统一结构的场景。

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