ThinkPHP 6+ 集成 webonyx/graphql-php 失败主因是路由接管、请求体解析与自动加载未对齐：须用 Route::any('/graphql') 显式注册，禁用 Json 中间件，改用 getRawInput() 解析原始 JSON，Schema 单例化并缓存，执行 composer dump-autoload -o 更新类映射。
ThinkPHP 6+ 集成 webonyx/graphql-php 跑不起来，十有八九卡在路由接管或请求体解析上——不是报 415 Unsupported Media Type，就是 query 字段为空、variables 丢失，或者直接抛出 Class 'GraphQL\Type\Schema' not found。核心问题从来不在 GraphQL 本身，而在 ThinkPHP 的中间件链、自动加载和输入处理机制怎么跟它对齐。
Route::post('/graphql') 必须显式注册，禁用默认 rule() 和 REST 式路由
ThinkPHP 的 Route::rule() 或资源路由会把 /graphql 当普通路径匹配，但 GraphQL 要求所有操作（query/mutation/subscription）都走同一个 POST 端点，且必须原样接收 JSON body。用 Route::get() 或 Route::post('graphql', ...) 不带 any() 语义，容易漏掉非标准 Content-Type（比如 application/graphql）的请求。
- 必须用
Route::any('/graphql', [...])或明确的Route::post('/graphql', [...])，并在闭包/控制器里手动接管 - 在
app_middleware.php中确认think\middleware\ValidatePostSize、think\middleware\VerifyToken（CSRF）等中间件对/graphql路径放行，否则 403/413 频发 - 禁用
think\middleware\Json中间件对/graphql的自动解析——它会提前file_get_contents('php://input')并清空流，导致后续getRawInput()拿不到原始数据
用 getRawInput() 解析原始 body，别碰 input('query') 或 input()
$this->request->input() 是 ThinkPHP 的参数过滤入口，会对 JSON 字符串做二次 decode + 类型转换 + 过滤，直接破坏 GraphQL 查询语法（比如把 { product(id: 1) { name } } 变成空数组或报错）。所有字段：query、variables、operationName，必须从原始 body 提取。
- 在控制器方法里写
$raw = $this->request->getRawInput();，然后$data = json_decode($raw, true); - 若前端发的是纯 query 字符串（Content-Type:
application/graphql），需手动补全：['query' => $raw] - 务必检查
$data['query']是否存在且非空，variables和operationName按需传入executeQuery()第四、第五参数 - 不要依赖
input('query')、param('variables')这类封装，它们已不可信
Schema 必须单例化，且不能放在 public/ 或可 web 访问路径下
每次请求都 new 一个 Schema 实例，性能差且类型定义易错乱；如果 Schema 文件放在 public/ 或通过 URL 可直接访问，会造成源码泄露甚至执行风险。
立即学习“PHP免费学习笔记（深入）”；
- 把 Schema 构建逻辑抽到服务提供者或静态方法中，首次调用后缓存实例（例如用
static $schema = null;+if (!$schema) { $schema = new Schema([...]); }） - Schema 定义文件（含
ObjectType、resolve闭包）应放在app/graphql/或app/common/graphql/这类非公开目录 - resolver 中若要用 ThinkPHP Model，直接
use app\model\Product;即可，无需额外绑定——但注意事务、连接池等上下文是否隔离 - 时间字段返回前必须转为
DateTime对象，否则 Webonyx 序列化时会报Cannot convert value to DateTime
composer dump-autoload -o 后再跑，别信开发环境缓存
Class 'GraphQL\Type\Schema' not found 表面是类没加载，实际常因 Composer 自动加载映射未更新。ThinkPHP 6+ 的容器别名、PSR-4 配置若与 webonyx/graphql-php 冲突，dump-autoload 就是唯一解法。
- 执行
composer require webonyx/graphql-php后，立刻运行composer dump-autoload -o（加-o强制优化） - 删掉
runtime/container/下所有缓存文件，避免 ThinkPHP 容器加载旧绑定 - 严禁在
config/app.php的alias数组里添加'GraphQL' => \GraphQL\GraphQL::class这类别名——命名空间会被覆盖，导致GraphQL\Type\...解析失败 - 调试时临时关闭 ThinkPHP 的 APP_DEBUG，让错误直出（Webonyx 的异常堆栈比 ThinkPHP 的更准）
最易被忽略的点：GraphQL 不是“加个路由就能用”的功能模块，它是请求生命周期的接管者。从 php://input 到 executeQuery()，中间每一步的 ThinkPHP 默认行为都可能成为断点。稳住原始输入、绕过中间件污染、冷启动一次 Schema，这三件事没做对，后面 resolver 写得再漂亮也白搭。
