Symfony 5 中使用 OverblogGraphQLBundle 的核心是确保 Schema 正确加载与请求响应，关键步骤包括：验证 PHP ≥8.1、配置 overblog_graphql.yaml、手动定义 Type 类、规范字段类型与 resolver 实现、正确设置路由与 JSON 请求格式，并通过 context_provider 注入运行时上下文。
Symfony 5 项目里写 GraphQL 接口，核心不是“怎么写语法”，而是“怎么让 OverblogGraphQLBundle 正确加载 Schema 并响应请求”。很多项目卡在 graphql:dump-schema 报错或 POST 到 /graphql 返回 500/404，问题基本不出在 resolver 逻辑，而在初始化阶段就断了。
composer require 后必须立刻验证基础环境
执行 composer require overblog/graphql-bundle 后，别急着建 UserType。先跑这个命令：
php bin/console graphql:dump-schema
失败说明底层没通，常见三类硬伤：
- PHP 版本低于 8.1 —— Symfony 5 兼容的 OverblogGraphQLBundle 最低要求 PHP 8.1（Bundle 1.x），但 Symfony 5.4 实际推荐 PHP 8.2+；
-
config/packages/overblog_graphql.yaml缺失或内容为空 —— 至少要有schema:和definitions:两个顶层键； - Doctrine 实体没加
@ORM\Entity注解，或没运行过php bin/console doctrine:schema:validate—— Type 类依赖实体元数据，校验不通过会导致解析器注入失败。
Type 类必须手动定义，不能靠 Doctrine 自动映射
哪怕你有个 User 实体带 id、email、posts 关联，也得单独写 UserType 类。Bundle 不会扫描 @ORM 注解生成字段。
关键细节：
-
ID字段返回类型必须是String，哪怕数据库是int：return (string) $this->id; -
@Field的type参数不能写int或string，得用 GraphQL 类型名：type="String!"或type="Int"； - 关联字段如
posts不会自动懒加载，resolver 里必须显式调 Repository：$this->postRepository->findBy(['user' => $value])； - 敏感字段（如
email）不能直接return $value->email，要在 resolver 里查权限：if (!$this->security->isGranted('VIEW_EMAIL', $value)) { return null; }
前端请求前，先确认端点和 Content-Type
Symfony 默认路由走 /graphql，但生产环境建议改前缀。改法在 config/routes/graphql.yaml：
overblog_graphql_endpoint:
resource: "@OverblogGraphQLBundle/Resources/config/routing/graphql.yml"
prefix: /api/graphql
前端 AJAX 必须用 POST，且 Content-Type 设为 application/json，body 是标准 JSON：
{"query":"{ user(id:\"1\") { name email } }","variables":{}}
常见错误：
- 用 GET 请求（浏览器地址栏直接输
/api/graphql?query=...）—— Bundle 默认只接受 POST； - body 是 form-data 或 urlencoded —— 必须是 raw JSON；
- 漏传
variables字段（即使为空也要写"variables":{}），否则某些版本会解析失败。
Resolver 拿不到 Request？Context 是唯一入口
resolver 函数签名固定为 (mixed $value, array $args, $context, ResolveInfo $info)，没有 Request、Session 或 TokenStorage。
想读 JWT token 或当前用户，必须通过 $context 注入：
- 在
config/packages/overblog_graphql.yaml里配：context_provider: 'App\GraphQL\ContextProvider'； -
ContextProvider类里注入RequestStack和TokenStorageInterface，把$user和$token塞进数组返回； - resolver 里直接取：
$context['user']或$context['token']->getToken()。
这个环节最容易被跳过——不配 context_provider，resolver 就永远拿不到运行时上下文，所有鉴权、日志、多租户逻辑都会失效。
