ThinkPHP接入GraphQL需显式注册/graphql路由并手动解析原始JSON体，禁用参数过滤；Schema必须单例化存于非公开目录；中间件须放行CSRF与JSON预检，否则403/415错误频发。
在ThinkPHP项目中接入GraphQL接口，需绕过框架默认的REST式路由机制，手动接管/graphql端点并正确解析JSON请求体，否则query字段被过滤、variables丢失、Schema重建导致CPU飙升等问题会直接阻断调试进程。
ThinkPHP 6.x / 8.x 接入 GraphQL 的基础路径
必须用 Route::any() 或 Route::post() 显式注册 /graphql 路径，禁用 ThinkPHP 默认的参数过滤逻辑。
第一步：在 app/route/app.php 中添加路由规则 → Route::any('graphql', 'api.GraphQL/index');
第二步：创建控制器 app/controller/api/GraphQL.php，其中不调用 $this->request->param()，改用 input('param', '', null, false) 获取原始 JSON 字符串；【此处若仍用 input('query') 会触发自动类型转换和 XSS 过滤，破坏 GraphQL 查询语法】
立即学习“PHP免费学习笔记（深入）”；
第三步：在控制器方法内调用 webonyx/graphql-php 的 executeQuery()，传入 Schema 实例与原始 JSON 解析结果（json_decode($rawInput, true)）。
Schema 单例化与安全存放位置
每次请求都执行 Schema::create() 会导致 QPS 上升时 CPU 瞬间拉满，必须将 Schema 对象缓存为单例。
方法一：在 app/common/GraphQL/Schema.php 中定义静态 get() 方法，首次调用时构建 Schema 并存入静态属性，后续直接返回；
方法二：把 SDL 文件（.graphql 后缀）放在 app/schema/ 目录下，该目录不在 public/ 内，可避免被 deny_files 规则拦截；【public/ 下读取 SDL 文件会触发 403 错误】
方法三：使用 thinkphp 的容器绑定 Schema 实例，在 app/provider.php 中写 App::bind('GraphQLSchema', function () { return Schema::create(...); });
中间件放行与 CSRF 绕过策略
GraphQL 请求必须跳过 CSRF 校验和 JSON 格式预检，否则 403 或 415 错误会高频出现。
打开 app/middleware.php，找到 hinkmiddlewareValidatePostSize::class 和 hinkmiddlewareCheckRequestCache::class，将它们从全局中间件列表中移除；
在 app/middleware.php 的中间件分组配置中，为 graphql 路由单独定义一个中间件组，仅保留 hinkmiddlewareAllowCrossDomain::class 和 hinkmiddlewareTrustHosts::class；
这一步操作起来很简单，直接把文件拖进去就行。
PHP 8.5.5 兼容性关键处理
webonyx/graphql-php 在 PHP 8.5.5 下需关闭 opcache.enable_cli=1 的 CLI 模式缓存，否则 composer dump-autoload -o 后仍可能报 Class not found；
运行 php -d opcache.enable_cli=0 artisan optimize:clear；
确认 composer.json 的 autoload 部分未覆盖 PSR-4 标准路径，尤其不能存在 "GraphQL\": "vendor/webonyx/graphql-php/src/" 这类手动映射——它会与 ThinkPHP 的类绑定冲突；
所有 use 语句必须显式写出完整命名空间，例如 use GraphQLExecutorExecutionResult;，禁止在 config/app.php 中添加 'GraphQL' => GraphQLGraphQL::class 这类别名。
