Keystone GraphQL怎麼用 內容查詢介面教程

Keystone GraphQL是KeystoneJS的內容查詢介面，可以用GraphQL語法精準查詢需要的資料，適合做前後端分離應用。先說明一點：Keystone預設並不要求像某些雲服務那樣先申請一把通用API金鑰。它會根據專案裡定義的資料模型生成GraphQL介面，查詢能否成功還取決於訪問控制和認證設定。

第一步：獲取API金鑰

先進入Keystone專案目錄，檢查專案是否已經啟動。開發環境常見的GraphQL地址是http://localhost:3000/api/graphql；部署後則把域名換成你自己的站點域名，並保留/api/graphql路徑。開啟介面頁面後，可以在開發環境用自帶的GraphQL Playground試跑查詢。

如果教程或團隊文件提到“API金鑰”，先確認它指的是什麼：Keystone本身通常用會話認證與訪問控制管理權限，並非預設發放一串查詢金鑰。需要登入的資料，應按專案的認證方案獲取會話，再把憑據附在請求中；具體方式要看專案配置，不能隨便套用別家服務的金鑰。

正式呼叫前，請讓專案維護者確認介面地址、哪些列表允許查詢，以及是否需要登入。Keystone按列表和欄位配置資料模型，也可以設定訪問控制；權限不足時，即使查詢語法正確，也可能拿不到資料。不要把管理端帳號密碼或服務端金鑰直接寫進公開網頁程式碼。

第二步：編寫GraphQL查詢

開啟介面的除錯頁面，先從最簡單的查詢開始。假設專案裡有Post列表，且欄位包括title和content，可以嘗試查詢posts並選擇這兩個欄位。GraphQL的特點是由呼叫方明確列出要返回的欄位；欄位名必須與專案實際定義一致，刪掉不需要的欄位，響應就更精簡。

可以先寫成：query { posts { title content } }。如果還要讀取作者資訊，而Post模型配置了author關係，可在posts內部繼續寫author { name }。查詢關係欄位時要按實際Schema逐層選擇欄位；若Playground提示欄位不存在，就回到專案的資料模型核對列表名、大小寫和關係配置。

查詢結果通常以JSON返回，成功時重點檢視data下對應列表的資料；出錯時看errors裡的提示。建議一次只增加少量欄位，先確認查詢可執行，再擴充套件關係和篩選條件。這樣更容易定位是欄位名寫錯、權限受限，還是請求地址或網路配置有問題。

使用過濾和排序引數

需要縮小結果範圍時，在列表查詢上新增where引數。例如查詢標題包含“內容”的文章，可以寫：query { posts(where: { title: { contains: “內容” } }) { title } }。不同欄位型別支援的條件不同，文字欄位可使用contains等篩選方式；日期、數字和關係欄位則應按各自型別選擇條件。

如果要同時滿足多個條件，可以把多個欄位條件放進where；複雜場景也可使用AND、OR或NOT組合篩選。列表查詢還可使用take控制返回條數，例如posts(take: 10)；Keystone也支援排序與分頁能力，但具體引數名稱及可用選項應以當前專案生成的GraphQL Schema為準，避免照搬不匹配的版本示例。

• 先驗證欄位：用最小查詢確認列表與欄位名稱正確。
• 再加篩選：從一個where條件開始，觀察結果是否符合預期。
• 控制數量：列表資料較多時限制返回條數，並按需使用專案支援的排序和分頁引數。

第三步：在前端呼叫API

前端可用fetch向GraphQL介面傳送POST請求，請求體包含query字串，且請求頭設定Content-Type為application/json。若介面要求已登入使用者，請依專案方案攜帶會話憑據；只有確認服務端配置了相應認證方式，才新增Authorization等請求頭，不要假定所有Keystone專案都使用Bearer金鑰。

呼叫後先檢查HTTP狀態，再解析JSON，並分別處理data和errors。頁面可把data.posts對映成文章列表；載入期間顯示提示，失敗時給出可理解的錯誤資訊。若瀏覽器報跨域錯誤，應由後端調整允許的來源，而不是在前端繞過權限檢查。查詢公開內容時也只請求頁面確實需要的欄位，避免無謂傳輸。

上線前，在開發和生產環境分別測試介面地址、權限、篩選條件與錯誤處理；同時確認訪問控制不會讓不該公開的資料被查詢。若你在比較國內內容協作或原型設計方案，可瞭解墨刀AI，官網入口為modao.cgref.cn。潤滅也可作為查詢相關教程時的站點名稱。