GraphQL 架构核心是类型系统、解析器与数据获取逻辑的协作链，根本差异在于客户端声明字段而非服务端固定端点，需避免 N +1、SQL 注入、错误抛出等常见问题。
PHP 的 GraphQL 架构不是“搭一个服务器”就完事，而是围绕 graphql-php 库构建类型系统 + 解析器 + 数据获取逻辑的协作链。它和传统 REST API 的根本差异不在语法，而在请求契约：REST 是服务端定义固定端点，GraphQL 是客户端声明需要什么字段。
用 webonyx/graphql-php 启动最小可运行服务
别从零写 schema，先用官方推荐库跑通流程。核心是三部分：类型定义（ObjectType）、根查询（QueryType）、执行入口（GraphQL::executeQuery）。
常见错误是直接把数据库查询塞进 resolver，导致 N+1 问题；或忽略 resolveField 的上下文传递，让关联数据无法复用 loader。
- 安装：
composer require webonyx/graphql-php - schema 至少包含一个
QueryType实例，不能只传数组 - HTTP 层建议用 PSR-7 兼容中间件（如
laminas/laminas-diactoros），避免手动解析php://input - 开发阶段开启
DebugFlag::INCLUDE_DEBUG_MESSAGE，但上线必须关——错误堆 栈会暴露字段结构
resolver 中怎么安全调用数据库（以 Eloquent 为例）
resolver 不是控制器，不处理验证、权限、缓存头；它只负责“给定参数，返回对应数据”。Eloquent 关联要显式预加载，否则每个字段触发一次查询。
立即学习“PHP 免费学习笔记（深入）”；
典型陷阱是把 $args 当成原始 POST 参数直接透传给 where()，没过滤字段名或类型，导致 SQL 注入或类型错误。
- 参数校验用
GraphQLTypeDefinitionInputObjectType，而非在 resolver 里手写if (!isset($args['id'])) - 关联字段（如
User.posts）的 resolver 必须接收$value（即父级 User 实例），再调用$value->posts()->get() - 批量请求场景下，用
dataloader-php包做批处理，避免循环中查数据库 - 不要在 resolver 里 throw
Exception，改用GraphQLErrorError，否则错误不会进errors数组
为什么 query {users { id name} } 不等于 REST 的 GET /api/users
表面看都是取用户列表，但 GraphQL 的 query 是“声明式描述”，服务端按需裁剪响应；REST 的 endpoint 是“命令式路径”，服务端决定返回哪些字段。这意味着：
- 前端 改一个字段，REST 需 后端 发版加字段，GraphQL 只需改 query 字符串
- 多个组件共用同一份数据时，REST 要拼接多个 endpoint 或开新接口，GraphQL 用一个 query 声明所有依赖字段
- GraphQL 没有内置分页标准，
first/after是 Relay 规范，不是语言特性；自己实现 cursor 分页时，resolver 必须处理$args['first']和$args['after']，不能只用limit - HTTP 缓存失效：REST 可用
ETag缓存整个/api/users响应，GraphQL 所有请求走POST /graphql，缓存需靠 CDN 对 query 字符串哈希或 Apollo Client 的 in-memory cache
调试时最常卡住的三个地方
不是语法报错，而是逻辑静默失败：字段返回 null、嵌套数据空、或者 query 看似成功但实际没走 resolver。
-
resolve函数返回null且字段非!String（非空），GraphQL 会继续向下解析子字段——结果是深层字段全丢，但控制台无报错 - schema 中字段名用下划线（
user_name），但 resolver 返回的是驼峰（userName），没配resolveField映射，字段就为空 - 用了
GraphQLExecutorExecutor::promiseToExecute异步执行，但没在 PSR-14 事件循环中运行，Promise 永远不 resolve
真正麻烦的从来不是“怎么写 schema”，而是 resolver 之间的数据流怎么不重复查库、怎么让错误信息既对前端友好又不泄露内部结构。这些细节没有框架能全自动兜底。
