Lighthouse 项目重大版本升级指南与技术解析-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00086/article/details/148577693

Lighthouse 项目重大版本升级指南与技术解析

lighthouse A framework for serving GraphQL from Laravel 项目地址: https://gitcode.com/gh_mirrors/li/lighthouse

前言

Lighthouse 作为 Laravel 生态中优秀的 GraphQL 服务端实现，在版本迭代过程中会引入一些破坏性变更。本文将从技术实现角度，深入解析各主要版本间的升级要点，帮助开发者顺利完成迁移。

核心配置变更检查

在每次大版本升级时，配置文件的变更往往是首要关注点。建议开发者：

备份现有 lighthouse.php 配置文件
对比最新版本的默认配置
特别注意中间件、认证守卫等安全相关配置的变化

v6 到 v7 升级详解

测试工具链优化

测试辅助特性现在会自动初始化，简化了测试代码：

// 之前需要显式调用
// 现在只需使用对应 trait 即可
use Tests\TestCase;
use Nuwave\Lighthouse\Testing\TestsSubscriptions;

class SubscriptionTest extends TestCase
{
    use TestsSubscriptions;
    
    // 测试方法...
}

安全中间件变更

EnsureXHR 中间件现在默认启用，这会阻止：

所有 GET 请求
可通过 HTML 表单创建的 POST 请求

如需允许这些请求，需在配置中显式禁用该中间件。

权限指令细化

原先的 @can 指令被拆分为多个专用指令，使权限控制更加精确：

type Mutation {
    # 模型级别权限
    createPost(input: PostInput! @spread): Post! 
        @canModel(ability: "create") 
        @create
    
    # 查找模型权限
    updatePost(input: PostInput! @spread): Post! 
        @canFind(find: "input.id", ability: "edit") 
        @update
        
    # 查询构造器权限
    deletePosts(ids: [ID!]! @whereKey): [Post!]! 
        @canQuery(ability: "delete") 
        @delete
}

v5 到 v6 重大变更

验证消息格式标准化

@rules(
    apply: ["max:280"],
    messages: [
        {
            rule: "max"
            message: "内容不能超过280个字符"
        }
    ]
)

删除操作指令增强

删除类指令现在统一使用参数过滤语法：

type Mutation {
    deleteUser(id: ID! @whereKey): User! @delete
    restoreUsers(userIDs: [ID!]! @whereKey): [User!]! @restore
}

订阅响应格式升级

{
  "extensions": {
    "lighthouse_subscriptions": {
      "version": 2,
      "channel": "post-updated"
    }
  }
}

分页结果非空保证

分页结果类型现在总是标记为非空，这虽然对客户端更友好，但会使验证错误向上传播。

枚举处理方式变更

BenSampo\Enum\Enum 实例现在会直接传递给 ArgBuilderDirective，不再自动解包。如需保持旧行为，需调整业务逻辑：

public function scopeByType(Builder $builder, AOrB $enum): Builder
{
    // 现在接收的是枚举实例
    return $builder->where('type', $enum->value);
}

v4 到 v5 迁移要点

中间件体系重构

@middleware 指令被移除，替代方案：

认证改用 @guard

type Query {
    profile: User! @guard
}

授权改用 @can
其他功能应通过自定义 FieldMiddleware 实现

指令定义规范化

所有指令现在必须提供 SDL 格式的定义：

public static function definition(): string
{
    return /** @lang GraphQL */ <<<'GRAPHQL'
"""
指令功能描述
"""
directive @example(
    """
    参数说明
    """
    arg: String
) on FIELD_DEFINITION
GRAPHQL;
}