GraphQL Playground: ทดสอบ API ในเบราว์เซอร์
รัน GraphQL query, mutation, variables และ schema introspection กับ endpoint ที่เปิด CORS ได้ — ไม่ต้องติดตั้งแอปบนเดสก์ท็อป
Table of Contents
จุดแข็งของ GraphQL คือเลือก field ที่ต้องการได้ตรง ๆ — จุดอ่อนคือหลายคนต้องเปิด IDE หนัก ๆ แค่เพื่อลอง query เดียว GraphQL Playground ให้ใส่ HTTP endpoint เขียน query หรือ mutation เติม JSON variables กับ headers แล้ว execute จากเบราว์เซอร์ได้เลย
เครื่องมือมาพร้อม demo สาธารณะ (https://countries.trevorblades.com/) และตัวอย่าง query countries กด Execute ได้ทันที จากนั้นค่อยเปลี่ยน URL ของตัวเอง ตรวจ syntax ก่อนยิงเครือข่าย จัดรูปแบบเอกสารที่ยุ่งเหยิง และดึงสรุป schema ผ่าน introspection
คู่มือนี้สรุปว่า playground ทำงานอย่างไร แนวคิด GraphQL ที่เกี่ยวข้อง และเมื่อไหร่ client ในเบราว์เซอร์พอ กับเมื่อไหร่ควรยิงจากเซิร์ฟเวอร์ ถ้าคุณเพิ่งย้ายจาก REST การได้เห็น JSON ที่สะท้อน selection set ทันทีช่วยเชื่อมช่องว่างระหว่างเอกสาร schema กับคำขอจริงได้เร็วกว่าการอ่าน spec อย่างเดียว
Why Use GraphQL Playground?
- ติดตั้งศูนย์. วาง endpoint แล้วรัน ไม่ต้อง build GraphiQL, ไม่ต้อง npm client, ไม่ต้องดูแล Postman collection สำหรับงานครั้งเดียว
- จับ syntax ก่อนยิง. Validate ใช้ไลบรารี graphql แปลงเอกสาร วงเล็บหายหรือ operation ไม่ถูกจะพังในเครื่องก่อน
- อ่านง่าย. Format พิมพ์ AST ใหม่ให้ย่อหน้าสม่ำเสมอ เหมาะกับ query ที่ copy จาก log แบบย่อ
- สำรวจ schema. Schema ส่ง introspection แล้วสรุป type, field, argument — สำรวจ API ที่ไม่ได้เขียนเองได้
- Auth และ variables. ช่อง Headers (Bearer token, custom key) และ Variables ($id: ID!) ตรงกับที่ production client เรียกจริง
- ข้อความ query อยู่บนหน้า. จนกว่าจะกด execute คำขอออกจาก เบราว์เซอร์ของคุณ ไปยัง endpoint โดยตรง ไม่ใช่ proxy สำหรับ API ลับ
Key Features
| ฟีเจอร์ | ทำอะไร |
|---|---|
| Endpoint URL | ชี้ไปยัง GraphQL HTTP server ที่รับ POST แบบ { query, variables } |
| Query editor | เอกสารเต็มรูปแบบ: query, mutation และ syntax ของ subscription |
| Validate | parse() และตรวจว่ามี operation อย่างน้อยหนึ่ง |
| Format | print() AST ให้จัดหน้าสม่ำเสมอ |
| Execute | fetch POST แล้ว pretty-print JSON data / errors |
| Schema | Introspect root ของ query/mutation/subscription และรายการ type |
| Variables | อ็อบเจ็กต์ JSON รวมใน request body |
| Headers | HTTP header เพิ่ม เช่น Authorization |
- คำตอบแสดง HTTP status เมื่อเซิร์ฟเวอร์ตอบ GraphQL error ยังอยู่ในอาร์เรย์ errors แม้ HTTP จะเป็น 200
- JSON ใน Variables หรือ Headers ที่ผิดรูปแบบจะถูกปฏิเสธก่อนส่งคำขอ
- CORS ที่ล้มเหลวมีข้อความชัด: API ส่วนตัวมักบล็อก origin จากเบราว์เซอร์ API สาธารณะที่ส่ง Access-Control-Allow-Origin ใช้ได้ทันที
How to Use
- เปิด GraphQL Playground demo endpoint และ query รายชื่อประเทศถูกกรอกไว้แล้ว
- กด Execute จะได้ JSON ของ code, name, capital, emoji คัดลอกผลไปใส่ตั๋วหรือ test fixture ได้
- เปลี่ยน GraphQL Endpoint URL เป็นเซิร์ฟเวอร์ที่เปิด CORS path ตามที่ API ใช้ (/graphql, /api หรือ URL เต็ม)
- แก้ operation กด Validate ทุกครั้งที่เปลี่ยนโครง แล้ว Format ถ้าอ่านยาก เปิด Variables และ Headers เมื่อต้องการ $variables หรือ auth
- กด Schema เพื่อ introspect อ่านสรุปชื่อ type และ field แล้วเขียน query ให้แคบลง Clear ล้างแผงคำตอบเมื่อเริ่มทดลองใหม่
ถ้า execute ล้มเหลวด้วยข้อความ CORS แปลว่า API ปฏิเสธเบราว์เซอร์ ใช้สคริปต์ฝั่ง backend, เดสก์ท็อปไคลเอนต์ หรือ proxy ที่คุณควบคุม — playground ข้ามนโยบายนี้ไม่ได้ ทีมที่ล็อก origin ไว้เพื่อความปลอดภัยกำลังทำถูกแล้ว อย่าพยายามหลบ CORS จากหน้าเว็บสาธารณะ
Understanding GraphQL in the Playground
คำขอ GraphQL ทาง HTTP มักเป็น JSON ที่มี query (สตริง) และ variables (อ็อบเจ็กต์) ตามต้องการ playground สร้าง body นี้ให้ เซิร์ฟเวอร์ตอบ { "data": … } เมื่อสำเร็จ และอาจมี { "errors": [ { "message", "locations" } ] } เมื่อเอกสารเป็น GraphQL ที่ถูกแต่รันไม่ผ่าน (field ไม่รู้จัก, auth, nullability)
Query อ่านข้อมูล ตัวอย่าง countries { code name } คือ selection set: ตั้งชื่อ field เซิร์ฟเวอร์เติมค่า อ็อบเจ็กต์ซ้อนทำงานแบบเดียวกัน — เยื้อง field ใต้ parent
Mutation เปลี่ยนข้อมูล syntax เป็นเอกสารแบบเดียวกัน มักส่งตัวแปรเพื่อไม่ hard-code ID ในสตริง operation:
mutation UpdateTitle($id: ID!, $title: String!) {
updatePost(id: $id, title: $title) { id title }
}
ใส่ { "id": "1", "title": "Hello" } ใน Variables Headers ใส่ Bearer เป็น JSON: { "Authorization": "Bearer TOKEN" }
Subscription มักใช้ WebSocket playground นี้โพสต์ทาง HTTP จึง validate และ format เอกสาร subscription ได้ แต่สตรีมเหตุการณ์สดต้องใช้ไคลเอนต์เฉพาะ ถือว่าเป็นขั้น lint ไม่ใช่ live feed
Introspection ถาม __schema เพื่อ root type และรายการ type พร้อม field กับ argument เซิร์ฟเวอร์ production อาจปิด introspection ถ้า Schema error แปลว่า API ล็อกไว้ — ใช้ SDL ที่เผยแพร่หรือเอกสารที่ generate แทน
CORS คือข้อจำกัดหลักของเบราว์เซอร์ playground เรียก fetch จากโดเมนไซต์ (หรือ localhost ตอนพัฒนา) ถ้าเซิร์ฟเวอร์ไม่อนุญาต origin นั้น เบราว์เซอร์จะบล็อกคำตอบ นี่เป็นพฤติกรรมของเว็บ ไม่ใช่บั๊กของเครื่องมือ หากคุณเป็นเจ้าของ API และอยากทดสอบจากหน้านี้ ต้องตั้ง Access-Control-Allow-Origin ให้ตรงกับโดเมนที่เปิดหน้า playground รวมถึงอนุญาต header ที่คุณส่งในแผง Headers เช่น Authorization
ความต่างที่มักทำให้มือใหม่สับสนคือ HTTP 200 กับ GraphQL errors อยู่ด้วยกันได้ เซิร์ฟเวอร์รับเอกสารแล้ว แต่ resolver ปฏิเสธ field หรือสิทธิ์ แผงคำตอบของ playground แสดงทั้งสองชั้นนี้ จึงแยก “ยิงไม่ถึงเซิร์ฟเวอร์” ออกจาก “ยิงถึงแล้วแต่ schema หรือ auth ไม่ผ่าน” ได้ชัด
Practical Use Cases
ทดสอบ API GraphQL สาธารณะแบบเร็ว
เจอ URL ของ countries, GitHub (ผ่าน proxy ที่เปิด CORS) หรือ CMS ในเอกสาร วางลง รันตัวอย่าง แล้วตัด field จน payload เล็กพอแปะ Slack introspection บอก type ที่มีเมื่อ README เก่า
ดีบัก query ที่พังจากไคลเอนต์
คัดลอก operation จาก log ของแอป Validate ในเครื่องเพื่อแยก parse error จาก server error ถ้าเอกสารถูกแต่ errors บอก unknown field ให้ดึง Schema แล้วเช็กว่า type ยังมี field นั้น Format ก่อน commit เพื่อให้โค้ดรีวิวอ่านง่าย
ทดลอง variables และ headers
ตั๋วฝั่ง backend มักบอก “ยิง mutation นี้พร้อม JWT” วาง mutation ใน editor, ตัวแปรเป็น JSON, Bearer ใน Headers วนซ้ำโดยไม่ต้อง rebuild มือถือหรือ SPA อย่าวาง production secret บนเครื่องแชร์ ใช้ token ชั่วคราว
สอน selection set
เพื่อนร่วมทีมใหม่เริ่มจาก query ประเทศ เพิ่ม emoji ลบ capital แล้วดูรูป JSON เปลี่ยน วนซ้ำนี้เร็วกว่าอ่าน spec จับคู่กับ GraphQL Formatter เมื่อต้องการจัดหน้า query นอก playground
Best Practices
- ใช้ variables แทนต่อสตริง. เก็บ ID และอินพุตผู้ใช้ใน JSON Variables ให้ operation เป็นเอกสารคงที่
- Validate ก่อน Execute กับเอกสารใหญ่ parse error ถูกกว่าเครือข่ายที่ล้ม
- มอง CORS เป็นข้อจำกัดของผลิตภัณฑ์. API ภายในที่ต้อง auth ควรรันจาก CI หรือ backend ใช้ playground กับ endpoint ที่เปิด CORS จริง
- อย่า commit token สด ลงโน้ตที่แชร์ หมุนอะไรที่พิมพ์ใน Headers ตอนเดโม
- Introspect เฉพาะที่อนุญาต. การล็อก production เป็นเรื่องปกติ เก็บไฟล์ schema ในรีโปเป็นแหล่งความจริง
- คัดลอกคำตอบไปทำ fixture. JSON ที่จัดหน้าแล้วพร้อมใช้กับ mock server และ contract test
เมื่อต้องการประกอบ query จาก field โดยไม่ต้องสู้กับวงเล็บ ใช้ GraphQL Query Builder เมื่อ API คงที่และอยากได้ TypeScript types จาก schema ใช้ GraphQL to TypeScript
พร้อมยิงเอกสารกับ endpoint จริงแล้วหรือยัง เปิด GraphQL Playground กด Execute กับเดโม แล้วชี้ไปที่ API ที่เปิด CORS ของคุณ
Related Tools You Might Like:
- GraphQL Formatter — จัดรูปแบบและตรวจเอกสาร GraphQL
- GraphQL Query Builder — ประกอบ query จาก field โดยไม่ต้องต่อวงเล็บเอง
- GraphQL to TypeScript — สร้าง types จาก GraphQL operations
Happy querying!