การออกแบบ Schema

ตอนนี้คุณอ่าน GraphQL schema เป็นแล้ว โมดูลนี้ว่าด้วยการ เขียน schema ให้ดี ตัว schema ไม่ใช่ผลพลอยได้จาก database แต่เป็น contract สาธารณะ ระหว่าง server ของคุณกับ client ทุกตัวที่เข้ามาเรียกใช้ ปล่อย field ออกไปแล้วย่อมมีคนพึ่งพา field นั้น การออกแบบ schema ที่ดีคือการเลือก type และ field ที่อธิบาย domain ได้ชัดเจนพอจน contract ยังซื่อสัตย์อยู่ได้แม้ product จะโตขึ้น

Schema คือสัญญา

เมื่อคุณออกแบบ REST endpoint ตัว URL กับ JSON ที่คืนกลับมาผูกกันหลวม ๆ คุณแอบเพิ่ม field เข้าไปเงียบ ๆ ได้โดยไม่มีใครสังเกต ส่วน GraphQL schema ตรงกันข้าม — ชัดเจนและ strongly typed ทุก type ทุก field ทุก argument เขียนไว้ครบและระบบตรวจสอบให้ ฝั่ง client เขียน query โดยอิง contract นั้น เครื่องมือ generate code จาก contract และ server ของคุณก็สัญญาว่าจะรักษา contract ไว้

คำสัญญานี้คือหัวใจของทุกอย่าง ตัว schema ที่ออกแบบมาดีช่วยให้ทีม frontend ทำงานกับ type ที่มองเห็นได้จริง ช่วยให้เครื่องมือดักข้อผิดพลาดก่อน runtime และช่วยให้คุณประเมินผลกระทบของการเปลี่ยนแปลงได้ ต้นทุนคือวินัย — คุณต้องตัดสินใจตั้งแต่ต้นว่า domain นี้หน้าตาเป็นอย่างไร

ออกแบบรอบ ๆ domain ไม่ใช่รอบ ๆ ฐานข้อมูล

ความผิดพลาดข้อใหญ่ที่สุดของคนที่เพิ่งเริ่มออกแบบ schema คือ map ตาม table ใน database แบบหนึ่งต่อหนึ่ง ตัว table เองออกแบบมาเพื่อการจัดเก็บ — foreign key, join table, column แบบ snake_case, flag ที่ denormalize ไว้ ส่วน schema ของคุณต้องออกแบบมาเพื่อ คำถามที่ client ถาม

ลองนึกถึงแอปห้องสมุดง่าย ๆ ฝั่ง database อาจเก็บ table books, table authors และ join table book_authors ส่วน client ไม่สนใจ join table แต่สนใจ Book ที่ มี authors และ Author ที่ มี books ตัว schema จึงแสดงความสัมพันธ์นั้นออกมาตรง ๆ:

type Book {
  id: ID!
  title: String!
  authors: [Author!]!
}

type Author {
  id: ID!
  name: String!
  books: [Book!]!
}

join table หายไปจาก contract ความสัมพันธ์ที่ client ไล่ไปตามจริง ๆ — จากหนังสือไปยังผู้แต่งแล้ววนกลับ — กลายเป็น field แบบ first-class ส่วนการเชื่อมไปยัง storage จริงเป็นหน้าที่ของ resolver ทีหลัง ตัว schema พูดด้วยภาษาของ domain

flowchart LR
  Query["Query (entry point)"]
  Book["type Book"]
  Author["type Author"]
  Scalars["Scalars: ID, String"]
  Query -->|"book(id)"| Book
  Book -->|"authors"| Author
  Author -->|"books"| Book
  Book --> Scalars
  Author --> Scalars

Schema คือกราฟของ type ใน domain และความสัมพันธ์ระหว่างกัน

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

โมดูลนี้ไล่ส่วนประกอบพื้นฐานทุกอย่างที่คุณต้องใช้ออกแบบ schema ให้สะอาด ทีละบทเรียน:

การออกแบบ Schema (คุณอยู่ตรงนี้) — แนวคิดเรื่อง contract และการออกแบบรอบ domain
Types และ Fields — object type, argument ของ field, description และวิธีที่ type เชื่อมโยงกัน
Scalars และ Enums — scalar แบบ built-in และแบบ custom กับเหตุผลที่ควรใช้ enum แทน string อิสระ
Interfaces และ Unions — จำลองรูปร่างที่ใช้ร่วมกันและทางเลือกแบบเลือกอย่างใดอย่างหนึ่ง แล้วแยกเคสด้วย fragment
Inputs และ Nullability — input object type สำหรับ argument, เครื่องหมาย non-null !, list และค่า default

จบโมดูลนี้ คุณจะแปลงไอเดีย product ที่ยังคลุมเครือให้เป็น schema ที่แม่นยำ สื่อความหมายชัด และ query ได้ลื่นมือ

query ที่ออกแบบตาม domain รันได้จริง

ตัวอย่างด้านล่างจำลองห้องสมุดข้างต้น ต่อ resolver แล้วรัน query ที่ข้ามจาก Book ไปยัง Author แล้ววนกลับ กดปุ่ม Run เพื่อรันบน GraphQL engine จริง

JavaScript

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

  // Types shaped around the domain — book and author — not around tables.
  const schema = buildSchema(`
    type Author {
      id: ID!
      name: String!
      books: [Book!]!
    }

    type Book {
      id: ID!
      title: String!
      authors: [Author!]!
    }

    type Query {
      book(id: ID!): Book
    }
  `);

  const author = { id: 'au1', name: 'Ada Quill' };
  const book = { id: 'bk1', title: 'Designing the Graph', authors: [author] };
  author.books = [book];

  const root = {
    book: ({ id }) => (id === 'bk1' ? book : null),
  };

  // Traverse the domain relationship: book -> authors -> their books.
  const query = `
    {
      book(id: "bk1") {
        title
        authors {
          name
          books { title }
        }
      }
    }
  `;

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

สังเกตว่า query อ่านได้เหมือนประโยคที่พูดถึง domain — หนังสือ ผู้แต่งของหนังสือ และหนังสือเล่มอื่นของผู้แต่งคนนั้น ไม่มี join table ไม่มี foreign key มีแต่ความสัมพันธ์ที่คนสนใจจริง ๆ ความอ่านง่ายแบบนี้คือสิ่งที่คุณได้จากการออกแบบ schema ที่ดี

◈ ออกแบบสัญญา ไม่ใช่การจัดเก็บ

ก่อนเขียน type สักตัว ให้ถามก่อนว่า client อยากรู้อะไร และแนวคิดเหล่านั้นสัมพันธ์กันอย่างไร ตั้งชื่อ type ตามแนวคิดใน domain เปิดความสัมพันธ์ออกมาเป็น field แล้วปล่อยให้ resolver — ไม่ใช่ schema — จัดการเรื่องวิธีเก็บข้อมูล ถ้า schema สะท้อน database ตรง ๆ การตัดสินใจเรื่อง storage จะรั่วเข้าไปใน contract สาธารณะ ส่วน schema ที่สะท้อน domain จะนิ่ง แม้ storage ข้างใต้จะเปลี่ยนไปอย่างไรก็ตาม