前端如何查看 GraphQL Schema？完整指南

Facebook LinkedIn Tweet

更新日期： 2025 年 6 月 10 日

在開發使用 GraphQL 的應用時，了解後端的 Schema 結構是非常重要的第一步。

GraphQL Schema 定義了有哪些資料可以查詢（Query）、可以修改（Mutation），以及這些資料的資料型別與欄位結構。

如果你不知道有哪些 API 可以用，或者不知道參數與回傳格式長怎樣，就很難正確發送請求。

本文將從最常見的幾種方式，帶你一步步了解前端該如何查看 GraphQL Schema，包含可視化工具、查詢技巧與程式碼自動化工具。

前言：為什麼前端要懂 Schema？

在傳統的 REST API 開發流程中，前端工程師經常會面臨這樣的情況：

API 規格沒有寫清楚，必須反覆詢問後端才能確認用法。
每個路由只能取得一種資源，導致要呼叫多支 API 才能組合出一個畫面所需的資料。
API 回傳欄位過多或過少，無法根據實際需求「精準取得資料」。
一旦後端調整資料結構或參數格式，前端就容易出錯，甚至不自知。

這些問題導致了前端開發效率低落、維護困難、系統脆弱度上升，尤其在多人協作或大型專案中格外明顯。

GraphQL 的核心解法：Schema + 自我描述能力

GraphQL 正是為了解決這些問題而誕生。

GraphQL 的 Schema 就是一種強型別的 API 描述語言，會明確定義：

所有可查詢的資料類型（例如 User、Post、Product）
每個類型包含的欄位與對應的資料型別（例如 email: String!）
可以使用的查詢（Query）、變更（Mutation）、訂閱（Subscription）操作
每個操作可傳入的參數（Arguments）與其格式與是否必填

🧠 不再猜、不再等：前端的查詢主導權

這樣的「自我描述」能力，為前端帶來三大好處：

無需猜測 API 結構：只要打開 Playground / Docs，就能查到所有欄位、參數與型別，甚至能即時測試。
減少與後端溝通成本：Schema 是共同語言，前端可以自行探索、查詢與驗證，不需頻繁溝通。
查詢自由度高：前端可以精確指定需要的欄位，避免 over-fetching（多拿不必要的資料）與 under-fetching（欄位不夠還得再打一次 API）。

前端與 Schema 的關係是什麼？

在 GraphQL 的設計中，Schema 是整個系統的核心骨架。

它由後端開發者撰寫並維護，清楚定義了整個 API 的結構，包括：

可以查詢（Query）與變更（Mutation）哪些資料
每個資料型別（Type）有哪些欄位
每個欄位支援哪些參數、資料型別為何
彼此之間的關聯與嵌套結構是什麼

也就是說，Schema 是由後端主導設計的 API「規格表」與「通用語言」，讓前端得以依此進行查詢、整合與開發。

GraphQL 最大的特色：前端決定資料格式

在傳統 REST API 中，前端只能使用後端定義好的路由與回傳格式，像是：

GET /api/user/123

你拿到的資料可能包含你根本不需要的欄位，例如：

{
  "id": 123,
  "name": "Alice",
  "email": "[email protected]",
  "created_at": "2020-01-01T00:00:00Z",
  "updated_at": "2023-05-01T12:00:00Z",
  "last_login_ip": "127.0.0.1",
  "is_active": true
}

你只想要 name 和 email，卻得接收整包資料，造成 over-fetching 問題；

如果你需要的欄位沒有提供，又得跟後端申請新增欄位，造成開發卡關與延遲。

GraphQL 完全翻轉了這種開發方式：

前端可以依照自己的需求，自由組合資料欄位，甚至一次查詢多種資源。

範例：

query {
  user(id: 123) {
    name
    email
  }
}

只拿你要的，不多也不少，這就是 GraphQL 的精隨。

🧩 但這一切的前提，是你「看得懂 Schema」

GraphQL 給了前端強大的查詢能力，但也代表責任與自由並存。

要想發揮 GraphQL 的威力，前端開發者必須理解後端定義的 Schema，才能：

✔️ 確定有哪些查詢函數（Query）與變更函數（Mutation）可以用
✔️ 知道每個欄位需要什麼參數（如 $id: ID!）
✔️ 正確地撰寫查詢語法，搭配變數使用
✔️ 在出錯時能快速判斷錯在哪裡（欄位不存在？型別錯誤？參數遺漏？）
✔️ 搭配工具產生 TypeScript 型別，自動補全與錯誤提示，提升開發效率與安全性

👉 換句話說：Schema 是前端的 API 說明書、安全防護網、與開發導航圖。

如果你不熟悉 Schema，GraphQL 帶來的靈活性反而會變成風險來源；

但一旦你熟悉它，整個開發流程會變得快速、穩定、直觀且高維護性。

提升效率與維護性的關鍵

理解 Schema 不只是「可以查什麼欄位」這麼簡單，這是一種前端開發思維的進化。

當前端懂得如何查詢與使用 Schema，就能：

🔁 減少與後端的溝通來回，不需等待文件或詢問每個欄位
🧩 獨立完成查詢撰寫與整合流程，加快開發進度
🧠 自己定位錯誤與理解系統邏輯，提高 Debug 能力
🛡 搭配 Codegen 工具自動產生型別，減少錯誤與 Bug
🚀 對整個 API 結構有全局理解，更容易進行重構與維護

這就是為什麼在使用 GraphQL 的專案中，前端了解並善用 Schema 是一項基本功，也是你成為成熟開發者的重要里程碑。

方法一：使用可視化工具瀏覽 Schema

當你第一次接觸一個 GraphQL API，最推薦的方式之一就是使用圖形化的介面工具來「探索」它的結構，而不是直接閱讀文件或問後端。

這類工具最大的優勢在於可視化 + 互動式操作，讓你能像瀏覽說明書一樣查看 API，並立刻測試查詢是否正確。

常見工具：GraphQL Playground 與 Apollo Studio

以下是兩個最常見的圖形化工具，幾乎每個 GraphQL 專案都會使用其中之一：

工具名稱	說明
GraphQL Playground	輕量化、獨立應用程式或內嵌在後端服務中（例如 Hasura、NestJS）
Apollo Studio	Apollo 官方提供的雲端平台，支援多人協作、查詢分析與快取管理等進階功能

這兩者都具備類似的基礎功能，包含：

🔍 「Docs」側邊欄功能：

打開工具後，通常畫面分為左右兩側：

左側是查詢編輯區：你可以撰寫 query 或 mutation 的語法，像編寫程式一樣。
右側是「Docs」欄位：這是最強大的功能，它會列出 API 中所有可以使用的項目，包含：
Query: 可查詢的函數，例如 getUser(id: ID!): User
Mutation: 可執行的操作，例如 createPost(input: PostInput!): Post
Type: 自訂資料型別，例如 User, Post, Product
InputType: 用於 mutation 的輸入資料型別
Enum: 列舉型別，常見於狀態、角色等欄位
Scalar: 原始型別如 String, Int, Boolean

你可以點選每個函數，展開詳細資訊：

有哪些參數？哪些是必填？
回傳型別是什麼？
該型別的欄位有哪些？又對應到哪些子型別？

實用功能：即時撰寫與測試查詢

在 Docs 協助理解 API 結構後，你可以直接在畫面中撰寫查詢語法並立即執行測試。例如：

query {
  user(id: 123) {
    name
    email
  }
}

只要按一下「▶️執行」按鈕，系統就會回傳結果，顯示在下方。

這樣不僅可以驗證查詢是否正確，也能確認你理解的 Schema 結構是否一致。

✅ 適合時機：

使用情境	適合使用圖形化工具的原因
⏱ 快速查 API 結構	不需要問後端、不需要翻文件，幾秒鐘就能找到你要的欄位與用法。
🧪 手動測試查詢或 Mutation	寫查詢、傳參數、測回傳都在一個介面完成，無需跑完整前端程式。
🧭 開發早期探索用途	剛接手一個專案或剛串接新的 API，不確定可以做什麼時，快速摸清 Schema 結構。

這些工具能讓你在無需開發 UI 或串接程式碼的情況下，先熟悉資料結構、試出正確查詢邏輯，大幅降低開發風險與來回修正的時間。

小提示：有些後端服務已內建 Playground

像是 Hasura、Apollo Server、NestJS GraphQL module，部署後都會自動提供一個 /graphql 的路由供你打開 Playground。

如果你看到瀏覽器畫面中出現 Docs + 查詢編輯器，那你就可以立即開始使用了！

方法二：使用 Introspection 查詢 Schema

除了透過圖形化介面點選查詢之外，GraphQL 還提供一項非常獨特又強大的功能，叫做 Introspection（自我描述查詢）。

這項功能的核心概念是：

「你可以用 GraphQL 查詢語法來問 GraphQL 本身。」

也就是說，Schema 並不是藏在伺服器裡的黑盒子，而是一個可查詢的資料來源。

你能問它：「你有哪些型別？」「這些型別有哪些欄位？」「欄位的型別是什麼？」

Introspection 是怎麼做到的？

GraphQL 在設計上，內建了一組特殊的保留型別與欄位，例如：

__schema：代表整份 Schema 的資訊
__type(name: String)：查詢特定型別的詳細結構
__typename：查詢當前物件的實際型別
__enumValues：查列舉型別的所有值
__inputFields：查輸入型別的欄位列表

這些保留型別的前綴都是 __（雙底線），代表它們是用來 introspect（反查）Schema 結構的。

例如，這段查詢會回傳目前伺服器上註冊的所有型別名稱：

{
  __schema {
    types {
      name
    }
  }
}

或者你也可以查詢某個型別的欄位結構：

{
  __type(name: "User") {
    name
    fields {
      name
      type {
        name
        kind
      }
    }
  }
}

實務應用：用工具匯出完整 Schema（Introspection 查詢）

在實務開發中，我們不會手動撰寫 Introspection 查詢。

相反地，我們會使用工具從後端的 GraphQL Server 自動抓出完整的 Schema，並儲存成 .json 或 .graphql 檔案，方便後續搭配其他工具使用（如型別產生器 Codegen）。

最常見的匯出工具有兩種：

✅ 使用 `graphql-cli` 匯出：

graphql get-schema --endpoint=http://localhost:4000/graphql

✅ 使用 Apollo CLI 匯出：

npx apollo schema:download --endpoint=http://localhost:4000/graphql schema.json

這些指令會向指定的 GraphQL Server 發送 Introspection 查詢，並下載回整份 API 的 Schema 結構。

❓指令中的 `--endpoint` 是什麼？

--endpoint 參數的意思是：

你要去哪一個 GraphQL API 的網址查詢 Schema？

這個 endpoint 指的就是「GraphQL Server 暴露給外部請求的網址」，通常長這樣：

http://localhost:4000/graphql（本地開發環境）
https://api.example.com/graphql（線上正式環境）

前端平常撰寫查詢語法、發送 API 請求的對象，就是這個 endpoint。

不論你是用 fetch、Apollo Client，或像現在用 CLI 工具匯出 Schema，所有操作的目的地都是這個 GraphQL Server 的 endpoint。

🔌 所有 Schema 都由 GraphQL Server 控制嗎？

是的。只要你在專案中使用 GraphQL 架構，Schema 的定義與實作都集中在後端的 GraphQL Server 裡。
這個 Server 就是：

定義整體 API 結構（Query、Mutation、型別、欄位等）的地方
接收來自前端的查詢請求
根據 Schema 驗證查詢語法，並執行對應的 Resolver、資料庫操作等邏輯

你可以把 GraphQL Server 想成是：

一台「智慧型 API 機器」，而 Schema 就是它的完整說明書。

如果你的專案沒有使用 GraphQL Server，那麼自然也就不會有 /graphql endpoint、也無法透過工具匯出任何 Schema。

✅ 適合時機：

時機	原因
⚙️ 要搭配 Codegen 工具產生型別	需要完整的 Schema 結構，Introspection 查詢是必要步驟
🧪 專案初期要建立開發流程	可以匯出 Schema 作為前後端共同的契約規格
🧠 想深入理解某個型別的結構與欄位細節	__type 查詢非常有幫助
📦 使用自動化測試與變更檢測工具	Schema 匯出結果能追蹤版本差異（Git diff）或檢測破壞性變更

方法三：搭配 Codegen 工具，自動產生型別與函數

當你開始在專案中撰寫 GraphQL 查詢時，一定會遇到這個問題：

「我該怎麼確保我寫的查詢語法、變數型別、回傳資料結構都是正確的？」

手動定義型別不僅繁瑣、容易出錯，一旦後端 Schema 有變動，就必須重新對應整份型別，維護起來非常辛苦。

這時候就該出動 Codegen 工具（程式碼產生器），來幫你自動產生查詢函數與 TypeScript 型別，大幅降低開發負擔、提升安全性與開發速度。

推薦工具：GraphQL Code Generator

GraphQL Code Generator（簡稱 Codegen）是目前最主流的開源工具之一，它可以根據兩個資料來源：

🔍 GraphQL Schema（通常來自 Introspection 匯出的 schema.json 或 .graphql 檔）
🧾 你撰寫的 .graphql 查詢文件

來自動產生對應的：

TypeScript 型別定義（types.ts）
查詢與 mutation 函數
Hooks 版本的函數（如 useQuery、useMutation）
React、Vue、Svelte、Angular 等各框架的整合版本

你會得到什麼？

使用 Codegen 後，會自動產出以下幾類實用資源：

產出項目	說明
types.ts	查詢回傳資料的型別（包含巢狀結構），避免出現 any
查詢函數封裝	自動建立與你的查詢語法相對應的函數，例如 useGetUserQuery()
變數型別定義	根據查詢中 $xxx 參數自動建立型別提示，避免手動拼錯
型別與查詢同步更新	Schema 一變，型別即更新，確保一致性

這樣你在 React 中撰寫查詢時，就可以這樣使用：

const { data, loading, error } = useGetUserQuery({
  variables: { id: "123" }
});

此時，data 的型別會精準對應到 User 的欄位結構，打錯欄位名稱會立即報錯，變數格式錯誤也會被型別系統擋下，大幅減少潛在 Bug 發生機率。

🧪 實作範例流程

以一個 React + Apollo Client 專案為例，設定流程如下：

安裝 Codegen CLI 工具：

npm install @graphql-codegen/cli -D

初始化設定：

npx graphql-codegen init

你會被引導選擇：

你使用的框架（React）
使用的 client（Apollo）
要產生哪些型別（TypeScript + Hooks）
Schema 與文件的位置（例如：schema.graphql, src/graphql/*.graphql）

執行產生：

npx graphql-codegen

會在你指定的位置產生 generated/ 資料夾，裡面包含所有型別與函數。

在程式中使用：

import { useGetPostsQuery } from '../generated/graphql';

const { data } = useGetPostsQuery();

✅ 適合時機

使用情境	為什麼適合用 Codegen
🧑‍💻 使用 TypeScript 開發	自動產生型別、零 any 開發、開發體驗超順
🧩 串接 Apollo Client、React Query、URQL 等工具	Codegen 支援多種 plugin，自動產生對應 Hooks
🏗 中大型專案、多人協作	保持型別一致性、降低人為疏漏與版本落差
🔁 Schema 常變動	自動更新型別，減少對文件的依賴與重工
🛠 建立 CI/CD 流程	可設定在 PR 流程中自動跑 Codegen，避免手動更新型別

💡 延伸補充：與 `.graphql` 檔案搭配更佳

Codegen 最推薦的用法，是將查詢語法獨立寫成 .graphql 檔案，例如：

# src/graphql/GetUser.graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

好處包括：

查詢語法與邏輯分離，提升可讀性與維護性
可被 Codegen 自動掃描、產生函數與型別
搭配 VS Code 插件可即時語法提示與錯誤提示

需要我幫你接著寫一個結語段落或總結這三種方法的比較嗎？我也可以幫你整理成對照表或製作章節索引。

各方式比較總覽

以下是三種常見的 GraphQL Schema 查看與整合方式，分別介紹它們的用途、優缺點與適合情境：

1️⃣ GraphQL Playground / Apollo Studio

優點：

有圖形化介面，操作直觀，點一點就知道有哪些查詢可以用。
有 Docs 側邊欄，可以快速查欄位、參數、型別。
可以直接撰寫查詢語法並測試 API 是否正確回傳。

缺點：

所有操作都屬於手動操作，不利於重複使用。
查詢歷史與設定無法持久保存（除非使用進階帳號功能）。

適合對象 / 情境：

GraphQL 初學者、新手探索 API。
想快速了解某個 API 結構或立即測試 query 的開發者。

2️⃣ Introspection 查詢 Schema

優點：

能用查詢語法直接「問」伺服器 API 結構，抓下完整 Schema。
是自動化流程（例如型別產生器、CI 檢查）的核心資料來源。
可匯出成 schema.json 或 .graphql 檔，與其他工具整合。

缺點：

語法不直覺，通常不會手動撰寫，需要搭配工具使用。
主要作為後續工具使用的「中介步驟」，不太用於人工查詢。

適合對象 / 情境：

要搭配 Codegen、VS Code 外掛、Apollo CLI 等工具。
想把 Schema 整合進 CI/CD 或版本管理流程的開發團隊。

3️⃣ Codegen 工具（自動產生型別與函數）

優點：

根據 Schema 與查詢，自動產生 TypeScript 型別與函式。
查詢與回傳資料有完整型別保護，避免拼錯欄位或傳錯參數。
可搭配 Apollo、React Query 等工具自動產生 useQuery() 等 hooks。

缺點：

初期需設定 CLI 工具與設定檔（codegen.yml）。
必須先有 Introspection 匯出的 Schema 檔案作為來源。

適合對象 / 情境：

使用 TypeScript 的開發者或團隊。
中大型專案需要高度型別安全與模組化管理。
想提高開發效率、避免寫錯 query 的前端工程師。

✅ 小結建議

如果你是…	建議使用…
初學者剛開始接觸 GraphQL	✅ Playground / Apollo Studio
需要整合 Schema 到工具流程	✅ Introspection 查詢 + 匯出
使用 TypeScript 做專案開發	✅ Codegen 工具自動產生型別與函數

結語：熟悉工具，讓開發事半功倍

掌握 GraphQL 的關鍵之一，就是理解你正在跟誰溝通（Schema）。

從最基礎的 Docs 面板，到進階的 Introspection 與 Codegen，自由切換工具能大幅提升開發效率，減少溝通成本，也能更自信地寫出安全穩定的查詢語法。

建議你在專案初期就熟悉這些工具，讓自己在開發過程中無往不利！

前言：為什麼前端要懂 Schema？

GraphQL 的核心解法：Schema + 自我描述能力

🧠 不再猜、不再等：前端的查詢主導權

前端與 Schema 的關係是什麼？

GraphQL 最大的特色：前端決定資料格式

🧩 但這一切的前提，是你「看得懂 Schema」

提升效率與維護性的關鍵

方法一：使用可視化工具瀏覽 Schema

常見工具：GraphQL Playground 與 Apollo Studio

🔍 「Docs」側邊欄功能：

實用功能：即時撰寫與測試查詢

✅ 適合時機：

小提示：有些後端服務已內建 Playground

方法二：使用 Introspection 查詢 Schema

Introspection 是怎麼做到的？

實務應用：用工具匯出完整 Schema（Introspection 查詢）

✅ 使用 graphql-cli 匯出：

✅ 使用 Apollo CLI 匯出：

❓指令中的 --endpoint 是什麼？

🔌 所有 Schema 都由 GraphQL Server 控制嗎？

✅ 適合時機：

方法三：搭配 Codegen 工具，自動產生型別與函數

推薦工具：GraphQL Code Generator

你會得到什麼？

🧪 實作範例流程

✅ 適合時機

💡 延伸補充：與 .graphql 檔案搭配更佳

各方式比較總覽

1️⃣ GraphQL Playground / Apollo Studio

2️⃣ Introspection 查詢 Schema

3️⃣ Codegen 工具（自動產生型別與函數）

✅ 小結建議

結語：熟悉工具，讓開發事半功倍

Similar Posts

關於本站

✅ 使用 `graphql-cli` 匯出：

❓指令中的 `--endpoint` 是什麼？

💡 延伸補充：與 `.graphql` 檔案搭配更佳