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。