พื้นฐาน GraphQL

GraphQL คือ query language สำหรับ API ที่มาคู่กับ type system ที่อธิบายว่า API ส่งข้อมูลอะไรกลับมาได้บ้าง แทนที่จะเรียก URL คงที่หลายตัวแล้วหวังว่าแต่ละตัวจะคืนข้อมูลในรูปแบบที่ต้องการ ฝั่ง client ส่ง request ครั้งเดียวไปยัง endpoint เดียว แล้วระบุ field ที่ต้องการ อย่างแม่นยำ ส่วน server ตอบกลับด้วย response ที่มีรูปร่างตรงกับ request ไม่มากไม่น้อยไปกว่านั้น

แนวคิดเดียวนี้เปลี่ยนอะไรหลายอย่าง ข้อมูลที่ API ของคุณให้บริการกลายเป็น graph ของ type ที่เชื่อมโยงกัน ส่วน query คือเส้นทางที่คุณลากผ่าน graph นั้น

โมดูลนี้ครอบคลุมอะไรบ้าง

นี่คือโมดูลพื้นฐานของคอร์ส เมื่อจบโมดูลนี้คุณจะอ่าน GraphQL ได้ อธิบายได้ว่าทำไมทีมถึงเลือกใช้ GraphQL และเข้าใจวิธีที่ server เปลี่ยน query ให้เป็น response บทเรียนทั้งห้ามีดังนี้:

พื้นฐาน GraphQL (คุณอยู่ที่นี่) — ภาพรวมกว้าง ๆ และ query จริงตัวแรกของคุณ
GraphQL คืออะไร — endpoint เดียว schema ที่มี type กำกับ และ query ที่ client เป็นผู้กำหนด
GraphQL vs REST — ข้อแลกเปลี่ยน และเมื่อไรที่แต่ละแนวทางเหมาะสม
Type System — object type, scalar, root type และ nullability
Request Lifecycle — วิธีที่ server parse, validate และ execute request

ทั้งคอร์สนี้สอนด้วย TypeScript และตัวอย่าง code ทุกชิ้นเป็นของจริง: ตัวรันใน browser ด้านล่างรัน GraphQL จริง ๆ ด้วย reference implementation ส่วนในบทเรียนถัด ๆ ไปเราจะยก server เต็มรูปแบบอย่าง GraphQL Yoga ขึ้นมาให้คุณรันเอง

รูปร่างของระบบ GraphQL

flowchart LR
  C["Client"] -->|"query: fields it needs"| E["Single GraphQL endpoint"]
  E --> S["Schema (the contract)"]
  E --> R["Resolvers (the logic)"]
  R --> D["Data sources"]
  E -->|"JSON shaped like the query"| C

client ขอ field ที่ต้องการอย่างแม่นยำจาก endpoint เดียว

ฝั่ง client สร้าง query ที่อธิบาย field ที่ต้องการ ส่วน server เก็บ schema (contract) และชุดของ resolver function (ตรรกะ) เอาไว้ โดย server จะตรวจ query เทียบกับ schema รัน resolver เพื่อรวบรวมข้อมูล แล้วคืน response ที่สะท้อนรูปร่างของ query

query จริงตัวแรกของคุณ

ด้านล่างคือตัวอย่าง GraphQL ที่ใช้งานได้จริง โดยนิยาม schema เล็ก ๆ ที่มี field เดียวคือ greeting ใส่ function สำหรับ resolve แล้วรัน query กด Run แล้วดู GraphQL engine ตัวจริงสร้างผลลัพธ์ JSON ในแผงผลลัพธ์

JavaScript

(async () => {
  const { graphql, buildSchema } = await import('https://esm.sh/graphql@16');

  // The schema is the contract: it says a Query has a "greeting" field
  // that takes an optional "name" and returns a String.
  const schema = buildSchema(`
    type Query {
      greeting(name: String): String
    }
  `);

  // The root holds the logic that produces each field's value.
  const root = {
    greeting: ({ name }) => 'Hello, ' + (name || 'world') + '! Welcome to GraphQL.',
  };

  // Ask for exactly one field, passing an argument.
  const query = '{ greeting(name: "learner") }';

  const result = await graphql({ schema, source: query, rootValue: root });
  console.log(JSON.stringify(result, null, 2));
})();

สังเกตว่าผลลัพธ์ถูกห่อไว้ในคีย์ data และข้างในนั้น field ชื่อ greeting แมปไปยังค่าที่ resolver คืนกลับมา response คาดเดาได้เพราะเป็นไปตาม query ลองเปลี่ยน argument name หรือเปลี่ยน field แล้วรันอีกครั้งดู