GraphQL入门教程：PHP实战指南

本文是一份面向PHP开发者的GraphQL实战入门指南，直击webonyx/graphql-php库落地过程中的核心痛点：resolver必须严格遵循四参数签名（$root、$args、$context、$info），NonNull字段严禁返回null/0/false/""等“假值”，HTTP入口需手动解析JSON并输出符合规范的{ "data", "errors" }结构响应，且Schema必须显式手写构造——没有自动扫描、无注解魔法、不依赖约定目录。文章摒弃抽象原理，聚焦真实编码中极易踩坑的细节：参数错位导致$args为空、$context误用$_POST、空字符串触发类型校验失败、嵌套null引发子树崩塌、缺失errors数组致客户端静默失败……帮你绕过玄学报错，快速跑通第一个可交付的GraphQL接口。

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 } }，如果 profile resolver 返回 null，整个子树崩掉，要么改用可空类型，要么提前判空

HTTP 入口必须手动解析 JSON body，且响应必须含 errors 数组

GraphQL 规范强制要求响应结构为 { "data": {}, "errors": [] }。Apollo Client 等客户端会因缺失 errors 字段直接判定请求失败。

• 入口脚本要读 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 异常，很难定位。

到这里，我们也就讲完了《GraphQL入门教程：PHP实战指南》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！