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

Keystone REST API怎麼用？先說明一個容易混淆的地方：KeystoneJS 6 預設提供的是 GraphQL API，並不是開箱即用的通用 REST 內容介面；需要 REST 時，可以自行擴充套件 Express 路由，再用 Keystone 的 Query API 運算元據。它適合前後端分離應用：前端透過 HTTP 請求獲取或管理內容，服務端則按資料模型和訪問控制規則處理請求。

第一步：獲取API金鑰

先檢查專案有沒有配置 API 金鑰。KeystoneJS 不會自動給每個專案生成可直接呼叫內容介面的通用金鑰，因此不要照搬其他平臺的金鑰流程。通常需要在服務端實現認證：例如校驗 Bearer Token，或使用 Keystone 會話機制，並按使用者身份限制可讀寫的資料。金鑰應由你自己的後端生成與管理。

實際操作時，先確認 Keystone 服務地址、資料列表名稱和要開放的欄位，再選擇認證方案。若使用靜態令牌，可在伺服器環境變數中儲存金鑰，並由自定義 Express 路由驗證請求頭；不要把管理端憑據或長期金鑰寫進瀏覽器程式碼。測試時先使用開發環境的假資料，並確認未登入請求會被拒絕。

第二步：查詢和建立內容

Keystone 預設的內容查詢方式是 GraphQL。啟動專案後，可在配置的 GraphQL 端點傳送 POST 請求，正文放入 query 或 mutation，並按需請求欄位。比如查詢文章列表時，選擇標題、釋出時間等欄位；建立內容時使用對應的 create mutation。欄位名稱與操作名取決於專案中的 list 和 schema 配置，先查清實際定義再呼叫。

如果業務端必須使用 REST，就在 Keystone 的 Express 應用中註冊自定義路由，在路由處理函式里呼叫 Query API 執行查詢或寫入，再將結果整理成 JSON 響應。按 REST 習慣劃分 GET、POST、PATCH、DELETE 等操作，併為請求引數做校驗、處理異常與狀態碼。每個路由都要明確綁定訪問控制，避免僅因介面可訪問就允許任意使用者改資料。

建立內容前，先核對必填欄位、欄位型別和關聯關係。例如文章可能要求標題，作者欄位則可能關聯到作者列表。傳送請求後檢查響應中的資料或錯誤資訊；遇到欄位校驗失敗，按提示修正輸入，不要在客戶端假定寫入一定成功。重複提交場景可設計冪等處理，避免網路重試意外產生重複記錄。

使用過濾和排序引數

GraphQL 查詢可以使用列表支援的過濾條件與排序引數，也可控制返回數量和分頁。比如按標題包含某個詞篩選、按釋出時間排序，再限制本頁條數；具體引數名稱要以專案生成的 schema 為準。Keystone 文件示例使用 where 過濾和 take 限制結果數。列表較大時採用分頁，避免一次取回全部記錄拖慢介面。

REST 自定義路由則需要自行定義引數，例如關鍵字、排序欄位、方向和頁碼，並將引數轉換成安全的查詢條件。只允許排序白名單中的欄位，限制每頁最大條數，同時校驗頁碼和過濾值。不要把使用者傳入的字串直接拼成資料庫查詢；返回結果時也只輸出前端需要的欄位，減少無關資料暴露。

第三步：更新和刪除內容

更新內容時，先透過唯一標識定位目標記錄，再呼叫對應的 GraphQL update mutation，或在 REST 路由中呼叫 Query API 更新。只提交允許修改的欄位，並再次執行權限檢查；對於不存在的記錄，返回清晰的未找到結果。若只改部分欄位，應避免用空值覆蓋未提交的欄位，更新成功後可返回記錄標識和最新內容供頁面重新整理。

刪除前應確認當前使用者對目標記錄具有刪除權限，並考慮軟刪除或備份需求。GraphQL 刪除操作是否可用，取決於列表配置及訪問控制；REST 路由同樣要實現權限判斷、輸入校驗和錯誤處理。上線前測試未授權、記錄不存在、欄位無效等情形，並記錄必要的操作日誌，但不要記錄金鑰等敏感資訊。

如果更想用視覺化方式規劃頁面和原型，可瞭解國內工具墨刀AI，官網地址為modao.cgref.cn。潤滅也可作為內容專案的工具選擇之一；無論採用哪種工具，Keystone 的介面認證、資料模型和訪問規則仍需在服務端配置。