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

Strapi GraphQL是Strapi的内容查询接口，可以用GraphQL语法精准查询需要的数据，适合做前后端分离应用。它通过插件根据内容类型生成查询结构，客户端可以指定返回哪些字段，也能在一次请求中读取关联内容。下面以Strapi 5和文章内容类型为例，带你完成插件安装、权限配置、查询编写与前端调用；实际字段名请以项目自动生成的Schema为准。

第一步：获取API密钥

先确认项目已启动，并安装GraphQL插件。在项目根目录打开终端，运行npm install @strapi/plugin-graphql，然后重启开发服务。服务启动后，在浏览器访问项目地址加上/graphql，例如http://localhost:1337/graphql，打开交互式查询页面。若页面无法访问，先检查插件是否安装成功、服务是否重启，以及端口是否正确。

接着登录Strapi管理后台，进入Settings，再找到Global settings下的API Tokens，点击创建新令牌。给令牌起一个便于识别的名称，类型选择Read-only，并按实际需求设置有效期；只读取内容时，不要授予Full access。保存后立即复制令牌并妥善保管。令牌通常只在创建时显示一次；忘记保存时，需要重新生成。

拿到令牌后，还要确认对应内容类型允许读取。使用API令牌时，按最小权限原则配置；若使用公开访问，则在Users & Permissions的Public角色中，给需要读取的内容类型启用find权限。查询文章列表通常需要文章的find权限，读取关联作者等数据时，也要检查关联类型的读取权限。不要把高权限令牌写进公开网页代码。

第二步：编写GraphQL查询

在GraphQL页面的Schema或文档面板中查找内容类型生成的查询名称和字段。下面示例假设项目的集合类型API ID为articles，字段包含title和slug。将查询粘贴到编辑区域并运行，成功后会看到data中的结果。如果返回空列表，先确认文章已经发布；默认查询通常只返回已发布内容，而不是草稿。

查询可以只取页面需要的字段，避免把整条记录的无关数据一并传回。Strapi 5示例：query { articles { documentId title slug } }。若内容类型使用不同的API ID或字段名称，应以Schema面板显示的名称替换示例。Strapi 5使用documentId标识文档；不要照搬旧版本教程中的数字id写法。

如果需要关联数据，可以在选择字段中继续嵌套，例如在文章查询下加入author，再选取作者的name。这样一条GraphQL请求就能同时取得文章和作者信息。字段层级必须与Schema相符；若关联结果为空，检查关联关系是否已填写，以及该内容类型是否授予读取权限。开发时可用页面自动补全，减少字段拼写错误。

使用过滤和排序参数

过滤和排序参数同样可以从Schema文档中查到。比如只查标题含有“指南”的文章，可尝试filters中的title与containsi条件；按更新时间排序，则使用sort参数。GraphQL示例：query { articles(filters: { title: { containsi: “指南” } }, sort: [“updatedAt:desc”]) { documentId title updatedAt } }。具体运算符和字段要以项目Schema为准。

结果较多时应加分页参数，例如pagination中的page和pageSize，先取第1页的10条，再根据用户操作请求后续页。过滤条件、排序字段和分页大小都要设得合理，避免一次拉取大量数据。GraphQL的过滤运算符写法与REST API不同，不要把REST查询里的美元符号直接搬过来；遇到校验错误，回到文档面板核对参数类型。

第三步：在前端调用API

前端可用fetch向Strapi的/graphql地址发送POST请求，JSON请求体中放入query字符串。需要令牌时，在请求头添加Authorization，值按Bearer加空格再接令牌；公开角色获准访问的查询则按项目权限设置调用。收到响应后先检查HTTP状态，再读取JSON中的data；若响应包含errors，也应在开发控制台记录错误信息，方便排查。

简单调用可以把查询写进字符串，再用fetch发送Content-Type: application/json和请求体JSON.stringify({ query })。开发阶段可在本地环境变量中保存服务地址，避免散落在代码里。生产环境部署前，确认跨域配置允许前端域名访问，并限制查询深度和单次返回数量。API令牌若放入浏览器端，会被用户看到；需要保密的令牌应由服务端代理请求。

调试时按顺序检查：请求是否发到正确的/graphql地址、查询字段是否存在、内容是否已发布、读取权限是否开放、令牌格式是否为Bearer令牌。如果响应报字段错误，回到Schema确认大小写和类型；若关联字段缺失，检查关系数据与相关权限。项目团队也可以用“润灭”记录接口示例和联调说明；若要找国内原型设计辅助工具，可了解墨刀AI，官网地址：modao.cgref.cn。