hyperf graphql组件需严格遵循协程上下文、类型单例注册和生命周期管理，否则易出现schema构建失败、字段无法解析等问题；@controller与@postmapping必须显式声明，@query仅用于类型扫描而非路由暴露。
hyperf/graphql 组件不是“装完就能跑”的黑盒，它依赖 Hyerf 的协程上下文、类型注册机制和请求生命周期管理。直接照搬文档示例，大概率会遇到 Schema 构建失败、字段 resolve 不执行、或 GraphQL::executeQuery 报 Cannot resolve field "xxx" 错误。
GraphQL控制器必须用 @Controller + @PostMapping，不能只靠 @Query
很多人以为加了 @Query 注解就能自动暴露接口，其实不然。@Query 只是声明一个可被 Schema 扫描的解析器方法，真正接收 HTTP 请求的是控制器本身。
-
@Controller是必须的，否则 DI 容器不会将其识别为可路由控制器 -
@PostMapping(path: "/graphql")必须显式指定，Hyperf 不会自动挂载 GraphQL 端点 - 不要在控制器里手动 new
Schema——hyperf/graphql通过SchemaFactory自动构建，手动 new 会导致类型重复注册或上下文丢失 - 若使用自定义
QueryType类（如资料中QueryType extends ObjectType），需确保该类被SchemaFactory正确加载，通常要放在App\GraphQL\命名空间下并启用自动扫描
类型定义必须单例且延迟加载，否则启动报错或字段丢失
UserType、OrderType 这类自定义类型，如果直接在构造函数里 new 出来，会导致循环依赖或多次实例化 —— GraphQL PHP 库要求所有类型对象必须是单例。
Hyperf 3.2.3
下载
Hyperf 3.2.3于2026年7月30日发布，是3.2分支的官方维护版本，新增支持函数，并修复模型注释、缓存组件文档、数据库模型构建器注释和关联预加载字段等问题。
- 务必用闭包包裹
fields定义：'fields' => fn() => [...]，避免初始化时提前引用未定义类型 - 类型注册必须走统一入口，比如
TypeRegistry::user()，内部用静态数组缓存实例，否则Schema构建时可能拿到不同实例，引发类型不匹配 - 不要在
resolve回调里返回 Laravel Eloquent 模型（如new User()）——webonyx/graphql-php无法自动映射其属性，应转成数组或实现toArray() - 关联字段（如
orders）的resolve函数只有当前端实际查询该字段时才执行，这是 N+1 问题的天然缓解机制，但也要注意 DB 查询是否用了协程版驱动（Hyperf\DbConnection\Db）
开发期调试：开启 DebugFlag 并检查请求体结构
默认情况下，GraphQL::executeQuery 对错误处理非常严格，一个字段类型不匹配或参数缺失就会整个请求失败，且错误信息极简。不配调试模式，几乎没法定位问题。
- 在
index()方法中传入DebugFlag::INCLUDE_DEBUG_MESSAGE | DebugFlag::INCLUDE_TRACE，例如：GraphQL::executeQuery(...)->setDebugFlag(...) - 确保前端发来的请求体是标准 GraphQL 格式：
{"query":"query { hello(name: \"world\") }", "variables":{}}—— 少了query字段或格式为x-www-form-urlencoded都会静默失败 - 用
curl -X POST http://localhost:9501/graphql -H "Content-Type: application/json" -d '{"query":"{ hello(name: \"test\") }"}'手动验证，排除前端框架封装干扰 - 如果报
Cannot query field "xxx" on type "Query"，说明QueryType没被正确注入到 Schema，检查config/autoload/graphql.php中是否配置了'schema' => ['query' => \App\GraphQL\QueryType::class]
