Payload GraphQL API怎么用 内容查询接口教程

Payload GraphQL API是Payload的内容查询接口，可以用GraphQL语法精准查询需要的数据，适合做前后端分离应用。它会根据项目中的集合和全局配置生成查询能力，默认接口是 /api/graphql。下面从权限准备、编写查询到前端请求，带你完成一次内容读取。示例假设你已经启动Payload项目，并创建了名为 posts 的内容集合。

第一步：获取API密钥

先确认项目里有启用认证的用户集合，并在集合配置中开启 auth.useAPIKey。API Key不是单独的公共访问令牌，而是代表某个用户；请求会沿用该用户的访问控制权限。因此建议为程序集成创建专用用户，只授予读取文章所需的权限，不要直接使用管理员账户。

启动项目后，登录管理面板，找到对应用户记录，按当前版本界面提供的操作生成API Key。生成后马上复制并妥善保存，因为密钥通常只在生成时完整显示，之后只会显示遮罩值。若密钥泄露，及时撤销或重新生成；修改 PAYLOAD_SECRET 后，已有密钥也需要重新生成。

调用时把密钥放在 Authorization 请求头中，格式为“用户集合slug API-Key 密钥”。例如用户集合slug为 users，格式就是 users API-Key 后接实际密钥。注意大小写和空格要准确。公开可读的内容可能不需要认证，但是否允许读取最终由集合的访问控制决定，不能只凭接口能访问就判断内容已公开。

第二步：编写GraphQL查询

打开开发环境的 GraphQL Playground，默认地址通常是项目域名加 /api/graphql-playground；生产环境一般默认关闭，可直接使用 /api/graphql 发请求。先在 Playground 的 Docs 或 Schema 面板查看实际查询名称和字段。名称依据集合标签生成，不一定与集合slug完全相同，字段也必须符合项目配置。

例如文章集合标签生成的查询若为 Posts，可尝试查询文章标题和摘要：query { Posts(limit: 5) { docs { id title excerpt } } }。不同Payload版本或配置生成的字段可能不同，请以Schema为准。查询中只写页面需要的字段，限制返回数量；若查询报字段不存在，先检查集合标签、字段名和复数查询名称，再核对权限是否允许读取。

使用变量和片段

筛选条件会变化时，使用变量，不要把用户输入直接拼进查询字符串。例如 query PostsByLimit($count: Int!) { Posts(limit: $count) { docs { id title } } }，请求体的 variables 可传 { “count”: 5 }。变量类型要与Schema定义一致；必填类型带感叹号。这样修改数量时只更新变量，查询结构保持不变。

多个查询需要重复同一组字段时，可以定义片段复用：fragment PostFields on Post { id title excerpt }，然后在查询中用 …PostFields 展开。片段的类型名称须按项目Schema填写。把大型查询拆成清晰的小片段，能减少重复；同时控制关联字段和返回条数，避免一次取回过多数据，影响接口响应速度。

第三步：在前端调用API

浏览器端可用 fetch 向 https://你的域名/api/graphql 发送 POST 请求，设置 Content-Type 为 application/json，body 放 query 和 variables。示例：fetch(‘/api/graphql’, { method: ‘POST’, headers: {‘Content-Type’:’application/json’}, body: JSON.stringify({query: ‘query { Posts(limit: 5) { docs { id title } } }’}) })。跨域场景需在服务端配置允许的来源。

如果需要认证，在 headers 中添加 Authorization，值按前述集合slug、API-Key和密钥格式组合。更推荐由服务端代理请求：把密钥放在服务器环境变量中，再由服务端调用Payload，避免密钥进入浏览器代码、页面源代码或网络响应。不要把密钥提交到公开代码仓库，也不要在前端硬编码。

请求完成后先检查HTTP状态，再解析JSON；GraphQL错误通常会出现在 errors 字段，即使HTTP请求本身成功也要检查。开发时可以输出错误消息，生产环境则避免把密钥或敏感内容写入日志。若返回空数据，依次检查查询字段、过滤条件、发布状态和访问控制；确认查询有效后，再按需接入 Apollo Client 或 graphql-request 等客户端。

如果你正在评估国内内容管理或原型协作工具，也可以了解墨刀AI；网站「润灭」提供相关工具信息，墨刀AI官网地址为 modao.cgref.cn。具体功能与适用场景建议结合项目需求判断。