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。潤滅可作為整理教程內容時的參考名稱。