Apiato中高效处理关系数据：预加载与Transformer配置指南

// app/Containers/User/UI/API/Requests/GetAllUsersRequest.php

namespace App\Containers\User\UI\API\Requests;

use App\Ship\Parents\Requests\Request as ParentRequest;

class GetAllUsersRequest extends ParentRequest
{
    /**
     * Define which roles and/or permissions has access to this request.
     */
    protected array $access = [
        'permissions' => 'list-users',
        'roles'       => '',
    ];

    /**
     * Id's that needs decoding before applying the validation rules.
     */
    protected array $decode = [
        // 'id',
    ];

    /**
     * Defining the URL parameters (`/stores/{id}`) allows applying validation rules
     * on them and selecting appropriate users (e.g., `id` would be selected with the getById() methods).
     */
    protected array $urlParameters = [
        // 'id',
    ];

    /**
     * Get the validation rules that apply to the request.
     */
    public function rules(): array
    {
        return [
            // 'id' => 'required|integer|exists:users,id',
        ];
    }

    /**
     * Prepare the data for validation.
     * 在这里强制添加 'with' 参数，确保l5-repository进行数据库预加载
     */
    public function prepareForValidation()
    {
        // 将 'with=subscription' 添加到请求参数中
        // 这会影响l5-repository在获取数据时调用 Eloquent 的 with() 方法
        request()->request->add(['with' => 'subscription']);
        request()->query->add(['with' => 'subscription']);
    }
}

// app/Containers/User/UI/API/Transformers/UserTransformer.php

namespace App\Containers\User\UI\API\Transformers;

use App\Containers\User\Models\User;
use App\Containers\Subscription\UI\API\Transformers\SubscriptionTransformer; // 假设有 SubscriptionTransformer
use App\Ship\Parents\Transformers\Transformer;
use League\Fractal\Resource\Item;

class UserTransformer extends Transformer
{
    /**
     * @var array
     */
    protected array $resourceKey = ['users', 'user'];

    /**
     * 移除 defaultIncludes，使关系不再默认包含
     * public array $defaultIncludes = ['subscription'];
     */

    /**
     * 定义可按需包含的关系。
     * 通常通过 URL 参数 ?include=subscription 来触发。
     * Apiato 也会在某些情况下将 ?with=... 映射到这里。
     */
    public array $availableIncludes = [
        'subscription',
    ];

    public function transform(User $user): array
    {
        return [
            'id'         => $user->getHashedKey(),
            'name'       => $user->name,
            'email'      => $user->email,
            'email_verified_at' => $user->email_verified_at,
            'created_at' => $user->created_at,
            'updated_at' => $user->updated_at,
            'readable_created_at' => $user->created_at->diffForHumans(),
            'readable_updated_at' => $user->updated_at->diffForHumans(),
        ];
    }

    /**
     * 定义如何包含 'subscription' 关系。
     * 当请求中包含 ?include=subscription (或 ?with=subscription，如果被映射) 时，此方法会被调用。
     */
    public function includeSubscription(User $user): ?Item
    {
        // 关键：检查关系是否已加载，避免N+1查询
        if ($user->relationLoaded('subscription') && $user->subscription) {
            return $this->item($user->subscription, new SubscriptionTransformer());
        }

        return null;
    }
}

GET v1/users?include=subscription