PHP实现GraphQL需严格遵循webonyx/graphql-php规范：resolver必须四参数签名（$root、$args、$context、$info），NonNull字段禁止返回null/0/false/""，HTTP入口须手动解析JSON并返回含"errors"数组的标准响应，Schema须显式构造。
PHP 实现 GraphQL 不需要从“GraphQL 原理”开始学，直接上手 webonyx/graphql-php 就能跑通第一个查询——但卡点全在 resolver 参数签名、schema 构造方式和 HTTP 入口的手动处理上。
resolver 必须写满四个参数，少一个 $args 就为空
resolver 不是普通回调函数，它严格按位置传参：$root、$args、$context、$info。漏掉任意一个，PHP 就会把后续参数错位，导致 $args 变成空数组。
function($root, $args) { /* ✅ 正确 */ }function($args) { /* ❌ 错误：$args 实际接收的是 $root */ }-
$args只包含 query 中显式传入的参数，比如user(id: "123")→$args = ['id' => '123'] - 想用数据库连接或用户信息？得提前塞进
$context，再透传进来，不能在 resolver 里直接读$_POST或$_SERVER
NonNull 类型下返回 null、0、false 都会报错
GraphQL 执行阶段会做类型校验，不是 PHP 报错，错误信息像 "Field 'email' expected to return 'String!' but got NULL"。根本原因是 resolver 返回值和 schema 声明不匹配。
-
Type::nonNull(Type::string())字段，绝不能返回null、0、false、"" - 别写
return $user->email ?: '';——0会被转成空字符串，触发校验失败 - 该写
return $user->email ?? '';（??只对null生效） - 嵌套字段如
user { profile { avatar } }，如果profileresolver 返回null，整个子树崩掉，要么改用可空类型，要么提前判空
HTTP 入口必须手动解析 JSON body，且响应必须含 errors 数组
GraphQL 规范强制要求响应结构为 { "data": {}, "errors": [] }。Apollo Client 等客户端会因缺失 errors 字段直接判定请求失败。
立即学习“PHP免费学习笔记（深入）”；
- 入口脚本要读
php://input，json_decode(file_get_contents('php://input'), true) - 提取
query和可选的variables字段，传给GraphQL::executeQuery($schema, $query, null, $context, $variables) - 输出必须是
echo json_encode(['data' => $result->data, 'errors' => $result->errors ?: []], JSON_UNESCAPED_UNICODE); - 不能只 echo
$result->toArray()—— 它可能不带errors，尤其当没错误时
Schema 必须显式构造，没有自动扫描或注解
webonyx/graphql-php 不提供任何“魔法加载”。所有类型、Query、Mutation 都得手写，用 GraphQL\Type\Schema 显式组装。
- 别信“基于目录约定自动生成 schema”的包，它们多一层抽象陷阱
- 每个
ObjectType要明确写'fields' => [...]，字段的'type'和'resolve'都得手动配 - 根 Query 类型必须单独定义，并作为
GraphQL\Type\Schema的'query'参数传入 - 没
@field注解，没schema.graphql文件扫描，也没make:graphql命令
最容易被忽略的是：resolver 的四参数签名和 NonNull 类型下的返回值约束。这两个地方一错，现象都是“查不到数据”或“字段为空”，但实际是执行期类型校验失败，不是逻辑 bug，也不抛 PHP 异常，很难定位。
