Spatie Laravel Query Builder 升级指南：版本迁移全解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00794/article/details/148527648

Spatie Laravel Query Builder 升级指南：版本迁移全解析

laravel-query-builder Easily build Eloquent queries from API requests 项目地址: https://gitcode.com/gh_mirrors/la/laravel-query-builder

前言

Spatie Laravel Query Builder 是一个强大的 Laravel 扩展包，它简化了构建复杂查询的过程。随着版本的迭代，包的功能不断优化，同时也带来了一些破坏性变更。本文将详细解析各版本间的升级注意事项，帮助开发者顺利完成迁移。

版本升级路线图

从 v5 升级到 v6

主要变更：类型声明强化

v6 版本对代码进行了类型强化，主要体现在：

查询构建器类现在使用了类型属性（typed properties）
方法参数增加了类型声明

影响范围：

自定义排序（Custom Sorts）
自定义包含关系（Custom Includes）
自定义过滤器（Custom Filters）

升级建议：

检查所有自定义实现，确保：

类属性已添加类型声明
方法参数已添加类型声明
返回类型已明确定义

从 v4 升级到 v5

主要变更：Laravel 版本支持调整

新增对 Laravel 9 的支持
移除了对旧版本 Laravel 的支持

功能变更：

移除了查询附加属性（appending attributes）功能，以简化包的维护工作。

升级建议：

确保项目已升级到 Laravel 9 或更高版本
如果使用了附加属性功能，需要寻找替代方案

从 v3 升级到 v4

重大变更：请求处理方式重构

v4 版本彻底改变了过滤器、包含关系和字段请求的处理方式：

移除了自动转换功能：
- 不再自动将关系名转换为驼峰式
- 不再自动将字段名转换为复数蛇形命名
现在严格使用请求 URL 中的原始参数

示例说明：

对于遵循 Laravel 驼峰式命名约定的关系，请求示例如下：

GET /api/users
        ?include=latestPosts,friendRequests
        &filter[homeAddress.city]=Antwerp
        &fields[related_models.test_models]=id,name

对应的查询构建器配置：

QueryBuilder::for(User::class)
    ->allowedIncludes(['latestPosts', 'friendRequests'])
    ->allowedFilters(['homeAddress.city'])
    ->allowedFields(['related_models.test_models.id', 'related_models.test_models.name']);

升级建议：

检查所有 API 请求，确保参数命名一致
更新查询构建器配置，使用原始请求参数名
特别注意嵌套关系的命名方式

从 v2 升级到 v3

架构变更：继承关系调整

QueryBuilder 类不再继承自 Laravel 的 Eloquent\Builder
所有 Eloquent 方法调用会被转发到内部的 Eloquent\Builder 实例

兼容性影响：

不能直接将 QueryBuilder 实例传递给期望 Eloquent\Builder 实例的地方
可以通过 getEloquentBuilder() 方法获取内部的 Eloquent\Builder 实例

升级建议：

检查代码中所有 QueryBuilder 的类型提示和使用场景
需要原始构建器实例时，使用 $queryBuilder->getEloquentBuilder()

从 v1 升级到 v2

重大重构：类和方法重命名

v2 版本进行了大规模的重命名操作，建议使用 IDE 的重构功能（如 PhpStorm 的 Rename）而非简单的查找替换。

主要变更列表：

类重命名：
- Sort → AllowedSort
- Included → AllowedInclude
- Filter → AllowedFilter

请求宏变更：旧方式：

request()->filters()
request()->includes()

新方式：

QueryBuilderRequest::fromRequest($request)->filters()
QueryBuilderRequest::fromRequest($request)->includes()

自定义排序/过滤器实例化方式变更：旧方式：

AllowedSort::custom('name', MySort::class)

新方式：

AllowedSort::custom('name', new MySort())

升级建议：

使用 IDE 的重构功能进行重命名
检查所有请求宏的使用，更新为新的 QueryBuilderRequest 方式
确保所有自定义排序和过滤器都已实例化
注意调用顺序：
- allowedFields() 必须在 allowedIncludes() 之前调用

升级最佳实践

逐步升级：建议按照版本顺序逐步升级，而不是直接从很旧的版本跳到最新版
全面测试：每次升级后，运行完整的测试套件
查看变更日志：除了本文提到的内容，还应查阅完整的变更日志
利用IDE：使用PHPStorm等IDE的重构功能，可以大大减少人为错误

常见问题解决方案

问题1：升级后某些查询突然不工作了

解决方案：检查是否因为命名转换规则的改变导致，特别是v3到v4的变更

问题2：类型错误

解决方案：确保所有自定义实现都添加了正确的类型声明，特别是v5到v6的变更

问题3：找不到类或方法

解决方案：检查是否完成了所有必要的重命名操作，特别是v1到v2的变更

结语

Spatie Laravel Query Builder 的每次大版本升级都带来了显著的改进和优化。虽然升级过程可能需要一些调整，但这些变更有助于构建更健壮、更易维护的应用程序。建议开发团队根据项目实际情况制定升级计划，并在测试环境中充分验证后再部署到生产环境。

laravel-query-builder Easily build Eloquent queries from API requests 项目地址: https://gitcode.com/gh_mirrors/la/laravel-query-builder

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考