GraphQL接口需用Route::any()或Route::post()显式注册/graphql路径，手动解析原始JSON请求体，禁用参数过滤；Schema须单例化并存于非公开目录；调试时应关闭ThinkPHP调试模式直出错误。
GraphQL接口不能直接用ThinkPHP默认路由注册
ThinkPHP的Route::get()、Route::post()这类方法只认HTTP动作为粒度，而GraphQL要求所有查询（query/mutation）都走同一个POST /graphql端点，且请求体是JSON格式的query字段。硬套REST式路由会丢掉variables、operationName等关键字段，甚至被中间件误判为非法请求。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 必须禁用默认的
Route::rule()注册方式，改用Route::any()或Route::post()显式接管/graphql路径 - 在路由闭包或控制器方法里，手动解析
input()的原始JSON体，而不是依赖input('query')——后者会触发参数过滤和类型转换，破坏GraphQL语法结构 - 确保
app_middleware中校验CSRF、JSON格式的中间件对/graphql路径放行，否则415或403错误频发
用webonyx/graphql-php时要注意ThinkPHP的自动加载冲突
ThinkPHP 6+默认使用think\facade\App做类绑定，而webonyx/graphql-php依赖PSR-4标准自动加载。如果项目里手动修改过composer.json的autoload配置，或引入了其他GraphQL扩展（比如rebing/graphql-laravel的移植版），容易触发Class 'GraphQL\Type\Schema' not found。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 安装后务必运行
composer dump-autoload -o，避免开发环境缓存导致类找不到 - 不要在
config/app.php里给GraphQL相关类加别名（如'GraphQL' => \GraphQL\GraphQL::class），这会导致命名空间解析错乱 - 在控制器里用
use GraphQL\GraphQL;和use GraphQL\Type\Schema;显式导入，不依赖全局别名
Schema定义需绕过ThinkPHP的静态资源拦截
很多人把Schema::create()写在控制器里，每次请求都重建Schema对象，结果QPS一高就CPU飙升；还有人把SDL文件放在public/下想用file_get_contents()读取，却被ThinkPHP的deny_files规则拦截返回403。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- Schema对象必须单例化，推荐放在
app/common/GraphQLSchema.php中，用静态属性缓存：private static ?Schema $instance = null; - SDL文件应放在
app/graphql/schema.graphql这种非公开路径，用__DIR__.'/../graphql/schema.graphql'拼接绝对路径读取 - 如果用
GraphQL\Utils\BuildSchema::build()解析SDL，记得捕获GraphQL\Error\SyntaxError异常——语法错不会抛Fatal Error，但会导致整个接口静默失败
调试时debug=true反而掩盖真实错误
ThinkPHP开启调试模式后，error_reporting会被重置，而webonyx/graphql-php内部大量使用@抑制符（如@json_decode()）。一旦GraphQL请求体JSON格式有轻微问题（比如多了一个逗号），框架只返回空数组或null，根本看不到JSON_ERROR_SYNTAX提示。
实操建议：
立即学习“PHP免费学习笔记（深入）”；
- 开发阶段临时关闭ThinkPHP的
app_debug，改用ini_set('display_errors', '1');直出PHP错误 - 在GraphQL入口方法开头加一行：
$raw = file_get_contents('php://input'); if (!is_string($raw) || empty($raw)) { throw new \Exception('Empty request body'); } - 用
curl -H "Content-Type: application/json" -d '{"query":"{a}"}' http://localhost/graphql手工测，比Postman更容易暴露Content-Type缺失问题
GraphQL不是简单加个路由就能跑通的协议层，它的错误传播链比REST长得多——从HTTP头、JSON解析、AST构建、类型校验到执行器，任何一环没对齐ThinkPHP的生命周期，都会变成“没报错但没响应”的状态。最常卡住的地方，其实是php://input被提前读取过一次，或者Content-Type没设成application/json。
