คู่มือ JSON to GraphQL Schema: แปลง JSON Sample เป็น GraphQL SDL Types อัตโนมัติในไม่กี่วินาที

ถ้าคุณเคยพัฒนา GraphQL API มาก่อน คงคุ้นเคยกับสถานการณ์นี้ดี: คุณมีข้อมูล JSON จาก REST API เดิม จาก database หรือจากบริการ third-party และต้องนั่งเขียน GraphQL Schema Definition Language (SDL) ให้ตรงตามโครงสร้างข้อมูลนั้นทีละ field ทีละ type งานนี้ทั้งน่าเบื่อและเสี่ยงต่อความผิดพลาด โดยเฉพาะเมื่อ JSON ของคุณมี nested object ลึกหลายชั้น หรือมี array ขนาดใหญ่ที่ต้องมานั่งเดาว่าแต่ละ element ควรมี type อะไร

นี่คือเหตุผลที่เครื่องมือ JSON to GraphQL Schema Converter ถูกสร้างขึ้นมา เครื่องมือนี้ช่วยให้คุณวาง JSON sample ใดก็ได้ แล้วได้ GraphQL SDL types กลับมาทันที ด้วย type inference อัจฉริยะที่จัดการทุกอย่างให้ตั้งแต่ scalar mapping ไปจนถึงการสร้าง type แยกสำหรับ nested object และ array of objects ทุกอย่างทำงานแบบ client-side ใน browser ของคุณ ไม่มีข้อมูลใด ๆ ถูกส่งออกไปยัง server ทั้งสิ้น

ในคู่มือนี้ เราจะพาคุณไปดูวิธีใช้งานตั้งแต่ขั้นพื้นฐาน เข้าใจหลักการทำงานของ type inference ว่า JSON แต่ละค่าถูก map เป็น GraphQL type อย่างไร พร้อม use cases ในทางปฏิบัติและ best practices ที่จะทำให้ schema ของคุณพร้อมใช้จริงใน production

ทำไมต้องใช้ JSON to GraphQL Schema Converter?

• ประหยัดเวลาได้มหาศาล — แทนที่จะนั่งเขียน type User { ... } ทีละ field ด้วยมือ คุณแค่วาง JSON sample ลงไป ก็ได้ SDL ครบทุก type ภายในไม่กี่วินาที
• ลด human error — การเขียน schema ด้วยมือเสี่ยงต่อ typo, ลืม non-null marker (!), หรือสะกดชื่อ field ไม่ตรงกับข้อมูลจริง การแปลงอัตโนมัติช่วยตัดปัญหาเหล่านี้ออกไป
• Type inference ที่เข้าใจ JSON จริง — เครื่องมือแยกความแตกต่างระหว่างจำนวนเต็มกับทศนิยม, ตรวจจับ boolean, และจัดการค่า mixed หรือ null ได้อย่างชาญฉลาด
• รองรับโครงสร้างซับซ้อน — nested object และ array of objects ถูกแปลงเป็น named type แยกให้อัตโนมัติ พร้อมตั้งชื่อแบบ PascalCase และ singularize ชื่อ array ให้เรียบร้อย
• ปรับแต่งได้ตามสไตล์ทีม — ไม่ว่าจะ map id เป็น ID scalar, ทำให้ทุก field เป็น nullable, หรือตั้งชื่อ root type เอง ทุกอย่างทำได้ผ่าน option เพียงไม่กี่คลิก
• ปลอดภัย 100% — การแปลงทั้งหมดเกิดขึ้นใน browser ข้อมูล JSON ของคุณไม่ถูกส่งไปไหน เหมาะมากสำหรับข้อมูล production ที่มีความละเอียดอ่อน

ฟีเจอร์เด่น

รายละเอียดเพิ่มเติมที่ควรรู้:

• Smart naming — ชื่อ type ทุกตัวถูกแปลงเป็น PascalCase และตัวอักษรที่ไม่ถูกต้องตามกฎการตั้งชื่อ GraphQL จะถูก sanitize ออก ทำให้ SDL ที่ได้ valid เสมอ
• รองรับทั้ง object และ array ที่ root — ไม่ว่า JSON ของคุณจะเริ่มด้วย object หรือ array ก็วางแล้วแปลงได้ทันที
• Copy-to-clipboard ในคลิกเดียว — ได้ SDL ครบแล้วกด copy ไปวางในโปรเจ็กต์ได้เลย ไม่ต้อง select ข้อความเองให้เสียเวลา

วิธีใช้งาน

ขั้นตอนที่ 1: วาง JSON sample

เปิดหน้าเครื่องมือ JSON to GraphQL Schema Converter แล้ววาง JSON ตัวอย่างลงในช่องด้านซ้าย จะเป็น object หรือ array ก็ได้ เครื่องมือจะแปลงให้อัตโนมัติทันทีที่คุณพิมพ์ ตัวอย่างเช่น:

{
  "id": "u_12345",
  "name": "Somchai",
  "age": 30,
  "score": 4.75,
  "isActive": true,
  "address": {
    "city": "Bangkok",
    "zipcode": "10110"
  },
  "posts": [
    {
      "id": "p_001",
      "title": "Hello GraphQL",
      "views": 1200
    }
  ],
  "tags": ["dev", "graphql"]
}

ขั้นตอนที่ 2: ตั้งชื่อ root type

ระบุชื่อของ type แรกให้ตรงกับ domain entity ของคุณ เช่น User, Product, BlogPost ค่าเริ่มต้นคือ User แต่การตั้งชื่อให้สื่อความหมายจริงจะช่วยให้ schema อ่านง่ายขึ้นมาก

ขั้นตอนที่ 3: เปิด ID mapping

ถ้า JSON ของคุณมี field ชื่อ id ที่ทำหน้าที่เป็น unique identifier ให้เปิด option map id เป็น ID scalar เพื่อให้ schema สื่อความหมายถูกต้องตามหลัก GraphQL

ขั้นตอนที่ 4: ปรับ nullability

ค่าเริ่มต้นเครื่องมือจะถือว่าทุก field เป็น non-null (มี ! ต่อท้าย) เพราะ infer จาก sample ที่มีค่าครบ แต่ถ้าข้อมูลจริงของคุณมี field ที่อาจเป็น null ได้ ให้เปิด option "all fields nullable" เพื่อตัด ! ออกทั้งหมด แล้วค่อยไปเติมคืนเฉพาะ field ที่มั่นใจจริง ๆ

ขั้นตอนที่ 5: Copy SDL ไปใช้งาน

ตรวจสอบผลลัพธ์ในช่องด้านขวา เมื่อพอใจแล้วกดปุ่ม copy เพื่อนำ SDL ไปวางในไฟล์ .graphql ของโปรเจ็กต์ หรือใช้เป็น input ให้เครื่องมืออื่น ๆ ต่อได้เลย จากผลลัพธ์ของ JSON ตัวอย่างข้างต้น คุณจะได้:

type User {
  id: ID!
  name: String!
  age: Int!
  score: Float!
  isActive: Boolean!
  address: Address!
  posts: [Post!]!
  tags: [String!]!
}

type Address {
  city: String!
  zipcode: String!
}

type Post {
  id: ID!
  title: String!
  views: Int!
}

เข้าใจ GraphQL Type Inference

หัวใจของเครื่องมือนี้อยู่ที่ type inference คือการวิเคราะห์ค่าใน JSON แล้ว map ไปเป็น GraphQL scalar type ตามกฎนี้:

Nested object กลายเป็น named type — เมื่อเครื่องมือพบ object ซ้อนอยู่ภายใน เช่น address มันจะไม่ inline โครงสร้างนั้น แต่จะสร้าง type ใหม่ชื่อ Address (แปลงเป็น PascalCase อัตโนมัติ) แล้วอ้างอิงจาก type แม่ วิธีนี้สอดคล้องกับ best practice ของ GraphQL ที่นิยมสร้าง type แยกเพื่อ reuse แทนการซ้อนโครงสร้างซ้ำ ๆ

Array ถูก singularize — array of objects อย่าง posts จะถูกแปลงเป็น list type [Post!]! พร้อม singularize ชื่อ key จากพหูพจน์เป็นเอกพจน์ (posts → Post) ส่วน array ของ scalar เช่น tags จะได้ [String!]! สังเกตว่าทั้ง element และตัว list เองถูก mark เป็น non-null ให้ด้วย

ทำไม id → ID ถึงสำคัญ — ใน GraphQL นั้น ID เป็น scalar พิเศษที่สื่อว่า "นี่คือ identifier" แม้ตอน serialize ออกมาจะเป็น String เหมือนกัน แต่ในเชิงความหมายมันบอกเครื่องมือต่าง ๆ ว่าค่านี้ใช้ระบุตัวตนของ object ได้ เช่น Apollo Client ใช้ field ID ในการทำ cache normalization และ refetching การใช้ ID แทน String จึงทำให้ schema ของคุณสื่อความหมายดีกว่า และ tooling ทำงานได้ฉลาดขึ้น

Nullability กับเครื่องหมาย ! — GraphQL ถือว่าทุก field เป็น nullable โดยเว้นแต่จะเติม ! กำกับ เครื่องมือนี้ infer จาก sample ที่มีข้อมูลครบ จึง mark ทุก field เป็น non-null ไว้ก่อน แต่ในโลกความเป็นจริง field ที่ไม่เคยเป็น null ใน sample อาจเป็น null ในข้อมูล production ก็ได้ ดังนั้นอย่าลืมทบทวน nullability ทุกครั้งก่อนนำ schema ไปใช้จริง

use cases ในทางปฏิบัติ

Prototype GraphQL API จาก REST response

เมื่อต้อง prototype GraphQL layer ทับ REST API เดิมอย่างรวดเร็ว เพียง copy response จริงจาก REST endpoint มาวางในเครื่องมือ คุณก็จะได้ชุด type ครบถ้วนเป็นจุดเริ่มต้นสำหรับ schema stitching หรือ federation โดยไม่ต้องเขียนเองแม้แต่บรรทัดเดียว เหมาะมากสำหรับการ demo หรือ proof of concept ที่ต้องทำให้เสร็จภายในวันเดียว

สร้าง types สำหรับ GraphQL Code Generator

โปรเจ็กต์ที่ใช้ GraphQL Code Generator ต้องการ SDL schema เป็น input เพื่อ generate TypeScript types ต่อไป แทนที่จะเขียน schema จากศูนย์ ให้เริ่มจาก JSON sample จริงแล้วปรับแต่งต่อ คุณจะได้ workflow ที่ type-safe ตั้งแต่ข้อมูลจริงยาวไปจนถึง frontend code

Migrate JSON API เดิมไป GraphQL

สำหรับทีมที่ต้อง migrate ระบบเดิมแบบค่อยเป็นค่อยไป เครื่องมือนี้ช่วย "reverse engineer" โครงสร้างข้อมูลเดิมให้กลายเป็น SDL types ทำให้คุณเปรียบเทียบโครงสร้างเก่า-ใหม่เคียงข้างกัน และวางแผน migration อย่างเป็นระบบว่า type ไหนควรคงไว้ Type ไหนควรรวมหรือแยกใหม่

ใช้เรียนรู้ SDL syntax

ถ้าคุณเพิ่งเริ่มเรียน GraphQL ลองวาง JSON ที่คุ้นเคยแล้วดูว่ามันกลายเป็น SDL อย่างไร คุณจะเข้าใจ syntax ของ type definition, list type อย่าง [Post!]!, และความหมายของ ! ได้เร็วกว่าการอ่าน documentation เพียงอย่างเดียว เพราะเห็นจากข้อมูลจริงของตัวเอง

Best Practices

• ใช้ sample ที่มี representative data — JSON ที่วางควรมี field ครบและค่าใกล้เคียงความจริง ถ้า field ไหนอาจเป็น null ได้ ควรมี sample ที่ค่าเป็น null ปนอยู่ด้วย เพื่อให้ inference แม่นยำขึ้น
• ตรวจ nullability ที่ infer มาเสมอ — เครื่องมือ infer ได้จากสิ่งที่เห็นเท่านั้น field ที่ไม่เคย null ใน sample อาจ null ในข้อมูลจริง ทบทวนทุก ! ก่อนใช้ production
• ตั้งชื่อ root type ตาม domain entity — ใช้ชื่อที่ตรงกับธุรกิจจริง เช่น Product, Order, Article แทนค่าเริ่มต้น User เพื่อให้ schema อ่านง่ายและตรงกับภาษาของทีม
• ตรวจ ID fields ให้ครบ — นอกจาก field ชื่อ id แล้ว domain ของคุณอาจมี identifier อื่น เช่น userId, orderId ตรวจและปรับเป็น ID ด้วยตัวเองตามความเหมาะสม
• ทดสอบ edge cases — ลอง JSON ที่มี array ว่าง, ค่า mixed, หรือ nesting ลึก ๆ เพื่อยืนยันว่า SDL ที่รองรับกรณีเหล่านี้ได้ถูกต้อง
• เก็บ sample ให้เล็กและโฟกัส — แทนที่จะวาง response ใหญ่ที่มีเป็นร้อย field ให้แยกแปลงทีละ entity เล็ก ๆ จะได้ตรวจทานง่ายและ schema ออกมาสะอาดกว่า

เริ่มแปลงวันนี้

การสร้าง GraphQL schema ไม่จำเป็นต้องเริ่มจาก editor ว่าง ๆ อีกต่อไป ด้วยเครื่องมือ JSON to GraphQL Schema Converter คุณเปลี่ยนข้อมูลจริงให้กลายเป็น SDL ที่ valid ได้ภายในไม่กี่วินาที ไม่ว่าจะกำลัง prototype API ใหม่, migrate ระบบเดิม, หรือเพิ่งเริ่มเรียน GraphQL เครื่องมือนี้คือจุดเริ่มต้นที่ช่วยให้คุณทำงานเร็วขึ้นและผิดพลาดน้อยลง

ลองเลยตอนนี้: เปิดเครื่องมือ วาง JSON จาก API response ล่าสุดของคุณ แล้วดู type inference ทำงานให้เห็นกับตา — schema ที่เคยใช้เวลาเขียนครึ่งชั่วโมง อาจเสร็จได้ในไม่ถึงนาที

เครื่องมือที่เกี่ยวข้อง

• GraphQL Formatter — จัดรูปแบบ GraphQL query และ SDL ให้อ่านง่าย เป็นระเบียบ
• GraphQL to TypeScript Converter — แปลง GraphQL schema เป็น TypeScript types พร้อม type safety เต็มรูปแบบ
• JSON Schema Generator — สร้าง JSON Schema จาก JSON sample สำหรับ validate โครงสร้างข้อมูล

ขอให้สนุกกับการสร้าง schema!