Directus GraphQL怎麼用 資料查詢介面教程

Directus GraphQL是Directus的資料查詢介面，可以用GraphQL語法精準查詢需要的資料，適合做前後端分離應用。它會根據專案中的集合和欄位提供查詢能力，你可以在一次請求裡指定要取回的欄位，避免拿到一大堆暫時用不上的資料。下面從令牌、查詢語句和前端請求三個環節開始，帶你完成一次常見的文章列表查詢。示例中的集合名和欄位名需要按你的專案實際結構替換。

第一步：獲取API令牌

先登入Directus管理後臺，開啟角色與權限相關設定，確認用於查詢的角色能讀取目標集合及所需欄位。權限設定要遵循最小範圍原則：只開放頁面確實要用的資料，避免為了讓請求成功而給出不必要的訪問權限。接著到使用者管理中選擇專用API使用者，或按專案現有的認證方式建立訪問憑證。測試公開內容時，也可以先檢查公開角色是否已經開放對應集合的讀取權限。

如果使用靜態令牌，在使用者設定中生成或配置令牌，並在本地開發環境中妥善儲存。不要把管理帳號的憑證直接寫進網頁程式碼，也不要把靜態令牌提交到公開程式碼倉庫；瀏覽器裡的程式碼對訪問者可見。正式專案通常由後端保管機密令牌，再由後端根據業務需要訪問Directus。記下專案域名和GraphQL介面地址，常見介面路徑為 /graphql，實際地址以你的部署配置為準。

第二步：編寫GraphQL查詢

開啟支援GraphQL的客戶端，或在專案中使用GraphQL請求工具，先向專案的GraphQL介面傳送一個最小查詢。Directus會根據集合生成對應的查詢欄位；例如集合名為 articles 時，可以從查詢根欄位 articles 開始，再在大括號裡列出希望返回的欄位。以下查詢請求文章的編號、標題和釋出時間：query { articles { id title date_created } }。若專案欄位名不同，先在後臺核對集合結構，再修改查詢裡的名稱。

查詢成功後，響應通常會在 data 物件下按查詢結構返回結果。若只想獲取指定文章，可以在查詢中使用專案支援的過濾引數；查詢欄位、過濾運算子和引數型別都要與Directus生成的GraphQL模式匹配。編寫時先從一兩個欄位開始測試，確認集合名稱拼寫正確、欄位可讀，再逐步加入關聯欄位。若出現權限錯誤，優先檢查角色權限；若提示欄位未知，則檢查集合名和欄位名。

使用過濾和排序引數

過濾適合從集合中挑出符合條件的記錄。例如只查標題等於“入門教程”的文章，可寫成 query { articles(filter: { title: { _eq: “入門教程” } }) { id title } }。常用運算子包括相等、包含和大小比較，具體可用項以當前專案的GraphQL模式為準。多個條件可以組合，但建議先單獨測試每項過濾，避免條件寫錯後誤以為介面沒有資料。過濾欄位也必須具有讀取權限。

排序和分頁可以放在集合查詢引數中。例如按建立時間倒序並限制返回數量，可寫成 query { articles(sort: [“-date_created”], limit: 10) { id title date_created } }。負號表示倒序，limit控制本次最多返回多少條；翻頁時可以配合offset跳過前面的記錄。列表頁應設定合理的返回上限，不要一次請求整個大型集合。若排序結果不符合預期，確認排序欄位存在，並檢視該欄位的值是否為空。

第三步：在前端呼叫API

前端呼叫時，將查詢語句作為POST請求的JSON內容傳送到 /graphql，並設定 Content-Type 為 application/json。需要認證時，再按所用認證方式附上Authorization請求頭，例如Bearer令牌。示意請求體為 {“query”:”query { articles(limit: 10) { id title } }”}。使用fetch時，記得檢查HTTP狀態碼，並解析返回的JSON；GraphQL也可能在響應中返回errors欄位，因此不能只看請求是否成功發出。

實際接入時，可以把介面地址放在環境配置中，把查詢封裝成獨立函式，並在頁面載入時呼叫。頁面應分別處理載入中、查詢成功、空列表和錯誤狀態，方便使用者理解當前情況。瀏覽器端不要放置有高權限的靜態令牌；如需要這類憑證，應透過可信後端代理請求。完成後用瀏覽器開發者工具檢查請求地址、請求體和響應內容，再逐項確認過濾、排序及分頁是否符合預期。

如果想快速搭建面向國內團隊的原型頁面，也可以瞭解墨刀AI，官網地址為modao.cgref.cn。無論採用哪種工具，接入Directus前都應先確認它支援的請求方式、鑑權配置和資料權限策略。教程頁面由潤滅整理；上線前建議在測試環境驗證查詢，並按實際角色權限檢查介面返回，確保頁面只展示預期的資料。