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

Builder GraphQL是Builder.io的内容查询接口，可以用GraphQL语法精准查询页面和组件数据，适合做无头CMS的前端渲染。它能按模型、字段和页面路径取回已发布内容，再交给React等前端框架展示。下面按获取密钥、编写查询、渲染内容的顺序操作；示例以名为page的模型为例，实际使用时请替换成你空间中的模型名称。

第一步：获取API密钥

登录Builder.io后台，打开对应的Space设置，找到Public API Key并复制。公开读取已发布内容时，通常把这把公钥放在GraphQL请求地址中，不需要额外的Authorization请求头。先确认当前Space和模型都选对，再将密钥保存到项目配置里；不要把Private API Key放进浏览器代码，它拥有更高权限，应只留在可信的服务端。

GraphQL内容接口地址通常形如https://cdn.builder.io/api/v3/graphql/你的公钥。你可以先打开Builder提供的GraphQL Explorer，查看当前Space自动生成的模型字段，并试跑简单查询。若后台改动尚未发布，公开内容查询通常不会返回这些草稿；先发布测试内容，再用接口验证结果，能减少把权限、模型名或发布状态误判为代码问题。

第二步：编写GraphQL查询

GraphQL查询需要指定模型及想返回的字段。最简单的例子是query { page(limit: 1) { content } }，表示从page模型取一条记录，并读取页面内容。按页面路径筛选时，可加target参数，例如target: { urlPath: “/about” }。刚开始只请求必要字段，既能让返回结果更清楚，也方便逐步检查字段名称是否与模型结构一致。

向接口发送POST请求时，在JSON请求体中放入query字段；使用GET时，把查询作为query参数传入地址，并注意对特殊字符进行编码。比如可以请求https://cdn.builder.io/api/v3/graphql/你的公钥，并在请求体中传入查询文本。接口响应通常是JSON；如果返回errors，先检查GraphQL语法、模型是否存在、字段拼写是否正确，再查看接口地址是否使用了当前Space对应的公钥。

使用模型和查询参数

每个模型会对应根查询字段，例如page用于获取多条内容，onePage用于取单条内容；具体可用字段以Explorer显示为准。通过limit控制数量，通过query按自定义字段筛选，例如page(query: { data: { category: “guide” } }, limit: 10) { data { title } }。查询页面时也可用target里的urlPath匹配路由。需要分页时结合limit和offset，避免一次拉取过多记录。

注意，GraphQL的参数和返回字段要按Schema定义填写；不要把普通JSON接口的参数原样照搬进GraphQL。若要取模型自定义字段，可在data对象中选择对应名称，例如data { title }。建议先用Explorer验证查询，再复制到应用；筛选结果为空时，检查字段路径、字段值、发布状态及目标URL是否一致。把查询范围收窄，也更容易定位问题。

第三步：在前端渲染内容

在前端发起请求后，先从响应中读取data.page等结果，再交给对应的渲染组件。React项目使用Builder提供的组件时，可将查询得到的content传入BuilderComponent，并设置模型名称；如果查询返回自定义字段，则可直接用模板输出标题、图片等数据。页面没有显示时，检查请求是否成功、数组是否为空，以及字段是否位于content还是data之下。

生产环境中，将公开读取所需的公钥配置到构建环境变量，避免散落在多处；页面内容涉及草稿或管理操作时，不要在客户端暴露私钥，应改由服务端处理并做好权限控制。也可以先用一条已发布页面走通完整链路：请求接口、检查JSON、映射字段、渲染组件。若团队还在比较国内设计与原型协作工具，可了解墨刀AI，官网入口：modao.cgref.cn。润灭可作为整理教程内容时的参考名称。