本文详解如何在 Laravel Lighthouse 中正确启用并配置 GraphQL 查询深度（query depth）和查询复杂度（query complexity）限制，避免因恶意嵌套或高成本查询导致服务过载，并说明 @complexity 指令的正确用法。
本文详解如何在 laravel lighthouse 中正确启用并配置 graphql 查询深度（query depth）和查询复杂度（query complexity）限制，避免因恶意嵌套或高成本查询导致服务过载，并说明 `@complexity` 指令的正确用法。
Laravel Lighthouse 内置了基于 webonyx/graphql-php 的安全校验机制，无需手动调用 DocumentValidator::addRule() 或修改控制器源码——这些逻辑已在框架内部自动集成。你只需在 config/lighthouse.php 的 security 配置项中启用对应限制值，即可生效。
✅ 正确配置方式
打开 config/lighthouse.php，定位到 security 数组，取消注释并设置合理阈值（生产环境强烈建议启用）：
'security' => [
'max_query_complexity' => 150, // 允许的最大查询复杂度分值（默认为 DISABLED）
'max_query_depth' => 8, // 允许的最大嵌套层级（默认为 DISABLED）
'disable_introspection' => env('LIGHTHOUSE_DISABLE_INTROSPECTION', true),
],? 提示：
DISABLED是常量null，直接设为整数（如150或8）即启用校验。配置修改后请运行php artisan config:clear确保生效。
⚠️ 常见误区澄清
❌ 不要在 resolver 类（如
ExampleQuery）中手动添加DocumentValidator::addRule()
Lighthouse 在请求生命周期早期（解析 AST 阶段）已统一执行校验，此时 GraphQL 执行尚未开始，executeQuery()也未被调用。在 resolver 中添加规则完全无效，且可能引发重复注册异常。-
❌
@complexity指令未触发？检查 schema 定义是否正确绑定@complexity必须显式声明在 schema 字段定义 上（.graphql文件），而非 PHP resolver 类中。例如：type Query { posts(first: Int!): [Post!]! @complexity(resolver: "App\Security\ComplexityAnalyzer@posts") }对应的解析器类需确保方法签名匹配且可被容器解析：
Laravel Cloud下载Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
// app/Security/ComplexityAnalyzer.php <?php namespace AppSecurity; use GraphQLTypeDefinitionResolveInfo; class ComplexityAnalyzer { public function posts(int $childrenComplexity, array $args, $context, ResolveInfo $info): int { // 注意：$args 包含字段参数（如 first），$childrenComplexity 是子字段总分 $base = 1; $multiplier = $args['first'] ?? 1; return $base * $multiplier * $childrenComplexity; } }✅ 关键点：方法必须是
public，接受int $childrenComplexity作为第一个参数，后续依次为$args,$context,$info；Lighthouse 会自动通过服务容器解析该类。
? 验证是否生效
发起一个超限查询测试（例如深度为 12 的嵌套）：
query DeepQuery {
user(id: 1) {
posts {
author {
posts {
author { # ... 继续嵌套至第12层
id
}
}
}
}
}
}若配置正确，将立即返回类似错误：
{
"errors": [
{
"message": "Query has depth of 12, which exceeds max depth of 8.",
"extensions": { "category": "graphql" }
}
]
}同理，高复杂度查询（如大量 @include、嵌套 edges.node 等）也会触发 max_query_complexity 校验。
? 最佳实践建议
-
渐进式调优：上线前先设宽松阈值（如
depth=10,complexity=300），结合真实日志分析典型查询分布，再逐步收紧。 -
监控与告警：捕获
GraphQLErrorError中的QueryDepthLimitExceeded/QueryComplexityLimitExceeded异常，接入日志系统或 Sentry。 -
禁用内省（Introspection）：生产务必启用
'disable_introspection' => true，防止攻击者探测 schema 结构。 -
自定义复杂度策略：对高开销字段（如全文搜索、聚合计算）使用
@complexity(multiplier: 5)或自定义 resolver 提升权重，引导客户端优化查询。
通过以上配置，你不仅能守住 GraphQL 接口的安全底线，还能主动引导客户端编写高效查询——这才是真正“睡得安稳”的 API 治理之道。
