symfony中graphql需通过overblog/graphql-bundle集成，其底层依赖webonyx/graphql-php；bundle提供路由、上下文、错误处理等完整封装，安装后须执行php bin/console graphql:dump-schema验证配置。
GraphQL在Symfony里不是开箱即用的，得靠webonyx/graphql-php + overblog/graphql-bundle
Symfony本身不带GraphQL支持，官方也无意内置。目前最稳定、文档最全、维护最勤的方案是overblog/graphql-bundle，它底层封装的是webonyx/graphql-php（PHP原生GraphQL实现）。别试自己手写解析器或硬接graphql-php裸包——路由、上下文、错误处理、缓存集成这些事Bundle已经帮你兜住了。
安装时注意PHP版本和Bundle版本对齐：overblog/graphql-bundle 1.x 支持 Symfony 5.4–6.4，2.x 起只支持 Symfony 6.4+ 且强制 PHP 8.2+。运行composer require overblog/graphql-bundle后必须执行php bin/console graphql:dump-schema验证基础配置是否通。
schema.graphql文件里不能直接写@ORM\Entity注解，得靠Type映射
很多人误以为GraphQL Schema能自动从Doctrine实体生成，其实不能。Bundle要求你显式定义Query、Mutation和各类Type，哪怕只是转发数据库字段。比如一个User实体，你需要单独建UserType类，用@Field注解声明字段，并在resolve回调里手动调用Repository。
-
@Field(type="String") public function getName(): string { return $this->name; }—— 这种写法看似简单，但$this是User对象实例，不是DTO；如果字段要脱敏或加权限校验，就得在resolve里塞逻辑 - 别把
id: ID!直接映射到$user->getId()返回int，GraphQL会报Expected a value of type "ID" but received: 123—— 必须转成string - 关联字段如
posts默认不会懒加载，得在resolve里显式$this->postRepository->findBy(['user' => $this])，否则返回null
Resolver里拿不到$request或$session，要用RequestStack或Security服务
GraphQL Resolver函数签名固定为(mixed $value, array $args, $context, ResolveInfo $info)，没有Symfony常用的Request或SessionInterface。想读Header、JWT Token、当前用户，必须通过$context传入，而这个$context由Bundle在GraphQLController里组装。
推荐做法是在config/packages/overblog_graphql.yaml里配context_provider：
overblog_graphql:
definitions:
context_provider: 'App\GraphQL\ContextProvider'
然后在ContextProvider里注入RequestStack和TokenStorageInterface，把getUser()、getHeader('X-Trace-ID')等挂到返回数组里。不然你在Resolver里写$this->security->getUser()会报ServiceNotFoundException——因为Resolver不是容器管理的服务实例。
调试Cannot query field "xxx" on type "Query"时，先跑graphql:dump-schema再看schema.graphql是否被正确加载
这个错误90%不是语法问题，而是Bundle没扫描到你的Type类，或者schema.graphql路径没配对。Bundle默认只加载config/graphql/types/下的文件，如果你把schema放在src/GraphQL/里，就得改types_path配置。
另一个常见坑是Query类型没声明type Query { users: [User!]! }，只写了type User { id: ID! name: String }——Schema校验会通过，但GraphQL Playground里点不出users字段，控制台只报模糊的field not found。
真正有效的调试顺序是：php bin/console debug:container | grep graphql确认服务存在 → php bin/console graphql:dump-schema --format=json > schema.json看输出里有没有你的Query字段 → 最后打开var/cache/dev/overblog/graphql-bundle/下生成的PHP Schema文件，搜users确认是否被编译进去。
GraphQL和REST共存时，别指望用同一个UserNormalizer复用序列化逻辑——GraphQL Type是独立定义的，Serializer Groups对它完全无效。字段级权限、格式化、空值处理，都得在各自的Resolver里重写一遍。
