讲师中心 微信公众号

工具推荐

视频效率加速
updream

一键生成高质量推广成片

AniShort
AniShort

AI短剧协同制作平台

Laper
Laper

剧本策划到成片协作

剧云
剧云

中文短剧剧本制作平台

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

阿杰酱_3979

阿杰酱_3979

发布时间:2025-11-12 12:05:02

|

757人浏览过

|

来源于php中文网

原创

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

本文详细阐述在apiato框架中,如何通过eager loading(预加载)技术解决n+1查询问题,并结合transformer进行关系数据的有效序列化。我们将探讨`l5-repository`的使用、请求参数处理以及transformer中`defaultincludes`与`availableincludes`的配置,确保数据库层面的性能优化与api响应的灵活输出同步进行。

1. 理解N+1查询问题及预加载的重要性

在开发API时,当我们需要获取一个主资源及其关联的多个子资源时,如果不采用适当的优化策略,往往会遇到臭名昭著的“N+1查询问题”。例如,在获取一个用户列表时,如果每个用户的订阅信息都需要单独查询,那么对于N个用户,将执行1次查询获取用户列表,再执行N次查询获取每个用户的订阅,总计N+1次数据库查询。这会严重影响API的性能和响应速度。

为了解决这一问题,Eager Loading(预加载)技术应运而生。通过预加载,我们可以在获取主资源时,一次性地将所有关联的子资源也查询出来,从而将N+1次查询减少到2次(一次主资源,一次所有关联子资源),显著提升数据库操作效率。

2. Apiato中的关系数据加载机制

Apiato框架基于Laravel,并集成了l5-repository(一个数据仓库模式实现)和Fractal Transformers(用于数据转换和序列化)。理解这三者如何协同工作是解决关系数据加载问题的关键:

  • l5-repository与Eloquent: 负责数据库层面的数据查询,包括Eager Loading。它通过with()方法来指定需要预加载的关系。
  • Fractal Transformers: 负责将Eloquent模型转换为标准化的API响应格式。它通过defaultIncludes(默认包含)和availableIncludes(按需包含)来控制哪些关系数据应被序列化并包含在最终响应中。

在Apiato中,通常使用?include=relationName这样的URL查询参数来触发Transformer的availableIncludes。而?with=relationName参数则主要用于指示l5-repository进行数据库层面的预加载。两者虽有区别,但在某些配置下,with参数也可能被Apiato内部处理并映射到Transformer的include逻辑。

3. 实现数据库层面的预加载

为了确保l5-repository在查询数据时能够执行预加载,我们需要在请求类中明确地传递with参数。这可以通过在请求类的prepareForValidation方法中添加参数来实现。

示例:强制在请求中添加with参数

// 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']);
    }
}

通过上述配置,无论API请求URL是否包含?with=subscription,l5-repository在执行查询时都会尝试预加载subscription关系。这解决了N+1查询问题,确保了数据库查询的效率。

4. 配置Transformer以响应预加载和按需包含

仅仅在数据库层面进行预加载是不够的。如果Transformer没有被告知要序列化这些关系数据,它们将不会出现在最终的API响应中。当从Transformer中移除defaultIncludes后,关系将不再自动包含。为了实现按需包含,我们需要使用availableIncludes和对应的include[RelationName]方法。

Build MCP servers and clients for PHP applications with the official PHP SDK
Build MCP servers and clients for PHP applications with the official PHP SDK

使用官方Model Context Protocol PHP SDK将PHP应用程序功能暴露为MCP工具、资源和提示,用于代理工作流。

下载

示例:配置UsersTransformer以按需包含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;
    }
}

解释:

  1. 移除defaultIncludes: 确保subscription关系不再默认出现在API响应中。
  2. availableIncludes = ['subscription']: 声明subscription是一个可以按需包含的关系。
  3. includeSubscription(User $user)方法: 当API请求的URL中包含?include=subscription(这是Apiato的标准方式)时,Fractal会调用此方法来序列化subscription数据。
  4. $user->relationLoaded('subscription'): 这是一个非常重要的检查。它确保只有当subscription关系已经通过Eager Loading加载到User模型上时,才进行序列化。这有效地防止了在Transformer层面重新引入N+1查询问题。

5. 综合示例与最佳实践

现在,结合数据库层面的预加载和Transformer的配置,我们可以通过以下URL请求来获取用户及其订阅信息:

API请求示例:

GET v1/users?include=subscription

当此请求到达Apiato时:

  1. GetAllUsersRequest的prepareForValidation方法会确保with=subscription参数被添加到请求中。
  2. l5-repository会根据with=subscription参数,在数据库查询时执行User::with('subscription')->get(),从而预加载所有用户的订阅数据。
  3. UsersTransformer会根据URL中的?include=subscription参数,调用其includeSubscription方法。
  4. includeSubscription方法会检查User模型上是否已加载subscription关系(由于步骤2的预加载,此时为true),然后使用SubscriptionTransformer对订阅数据进行序列化并包含在最终响应中。

注意事项:

  • with vs include: 在Apiato中,with通常用于控制数据库层面的预加载(l5-repository),而include用于控制Transformer层面的序列化输出。虽然在某些情况下with参数可能被Apiato内部映射到include,但为了清晰和标准,建议在API请求中明确使用?include=relationName来控制Transformer的输出。
  • 关系命名一致性: 确保Eloquent模型中的关系方法名(例如subscription())与availableIncludes数组中的名称以及include[RelationName]方法中的名称保持一致。
  • 嵌套关系: 对于更复杂的嵌套关系(例如user.subscription.plan),你需要在每个层级的Transformer中配置availableIncludes和相应的include方法。
  • 性能考量: 尽管预加载可以解决N+1问题,但过度预加载不必要的关联数据也可能导致查询的数据量过大,反而影响性能。应根据实际业务需求,按需选择预加载和包含的关系。

通过以上步骤,你可以在Apiato框架中高效地处理关系数据,既解决了N+1查询问题,又保持了API响应的灵活性和可控性。

热门AI工具

更多
豆包大模型

豆包大模型是一款由字节跳动推出的企业级大语言模型服务平台。

WorkBuddy

一款AI办公效率工具,主要用于腾讯云推出的AI原生桌面智能体工作台,适合需要提升相关任务效率的用户。

UP简历
UP简历 Hot

一款AI办公效率工具,主要用于基于AI技术的免费在线简历制作工具,适合需要提升相关任务效率的用户。

花生AI
花生AI Hot

一款AI视频创作工具,主要用于B站推出的AI视频创作工具,适合需要提升相关任务效率的用户。

讯飞智作

讯飞智作是一款AI视频创作工具,AI文本配音工具,数字人课程、营销视频制作。

函子Zion

一款支持AI搭建、可视化编辑和多端发布的全栈无代码开发平台。

DeepSeek

DeepSeek是一款面向对话、写作、编程和推理场景的AI大模型工具。

切问学术

切问学术是一款AI论文写作工具,复旦大学NLP团队推出的AI学术智能体。

Laper
Laper Hot

Laper是专为编剧、导演和制片人推出的 AI 原生剧本创作工具。

相关专题

更多
laravel组件介绍
laravel组件介绍

laravel 提供了丰富的组件,包括身份验证、模板引擎、缓存、命令行工具、数据库交互、对象关系映射器、事件处理、文件操作、电子邮件发送、队列管理和数据验证。想了解更多laravel的相关内容,可以阅读本专题下面的文章。

897

2024.04.09

laravel中间件介绍
laravel中间件介绍

laravel 中间件分为五种类型:全局、路由、组、终止和自定。想了解更多laravel中间件的相关内容,可以阅读本专题下面的文章。

875

2024.04.09

laravel使用的设计模式有哪些
laravel使用的设计模式有哪些

laravel使用的设计模式有:1、单例模式;2、工厂方法模式;3、建造者模式;4、适配器模式;5、装饰器模式;6、策略模式;7、观察者模式。想了解更多laravel的相关内容,可以阅读本专题下面的文章。

2528

2024.04.09

thinkphp和laravel哪个简单
thinkphp和laravel哪个简单

对于初学者来说,laravel 的入门门槛较低,更易上手,原因包括:1. 更简单的安装和配置;2. 丰富的文档和社区支持;3. 简洁易懂的语法和 api;4. 平缓的学习曲线。本专题为大家提供相关的文章、下载、课程内容,供大家免费下载体验。

5181

2024.04.10

laravel入门教程
laravel入门教程

本专题整合了laravel入门教程,想了解更多详细内容,请阅读专题下面的文章。

7650

2025.08.05

laravel实战教程
laravel实战教程

本专题整合了laravel实战教程,阅读专题下面的文章了解更多详细内容。

5016

2025.08.05

laravel面试题
laravel面试题

本专题整合了laravel面试题相关内容,阅读专题下面的文章了解更多详细内容。

9409

2025.08.05

PHP高性能API设计与Laravel服务架构实践
PHP高性能API设计与Laravel服务架构实践

本专题围绕 PHP 在现代 Web 后端开发中的高性能实践展开,重点讲解基于 Laravel 框架构建可扩展 API 服务的核心方法。内容涵盖路由与中间件机制、服务容器与依赖注入、接口版本管理、缓存策略设计以及队列异步处理方案。同时结合高并发场景,深入分析性能瓶颈定位与优化思路,帮助开发者构建稳定、高效、易维护的 PHP 后端服务体系。

1536

2026.03.04

GoFrame框架Web开发与路由中间件
GoFrame框架Web开发与路由中间件

本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。

0

2026.11.17

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程
墨刀帮助中心
墨刀帮助中心

共0课时 | 0人学习

MyEclipse学习中心
MyEclipse学习中心

共0课时 | 0人学习

Apache Subversion 官方手册
Apache Subversion 官方手册

共0课时 | 0人学习

关于我们 免责申明 举报中心 意见反馈 讲师合作 广告合作 最新更新
php中文网:公益在线php培训,帮助PHP学习者快速成长!
关注服务号
PHP中文网订阅号
每天精选资源文章推送

Copyright 2014-2026 https://www.php.cn/ All Rights Reserved | php.cn