GraphQL Formatter: จัดรูปแบบ ตรวจสอบ และ Minify Query แบบออนไลน์

ลอง copy GraphQL query จาก server log, request body ใน network tab หรือจากเครื่องที่ไม่มี GraphQL IDE ดูสิ สิ่งที่คุณได้กลับมามักเป็นบรรทัดเดียวยาวเหยียด ที่เหล่าวงเล็บปีกกา argument และ fragment ถูกอัดแน่นจนการหาวงเล็บที่ปิดไม่ครบเสมือนไล่หา bug ใน JavaScript แบบ minify ด้วยกล้องแว่นขยาย นี่คือปัญหาที่ GraphQL Formatter ซึ่งใช้งานฟรีถูกสร้างขึ้นมาแก้โดยตรง

เครื่องมือนี้ทำงานทั้งหมดในเบราว์เซอร์ของคุณ เพียงวาง query, mutation, subscription หรือ SDL schema ลงไป ตัวเครื่องมือจะ parse เอกสาร จัดรูปแบบใหม่ด้วย indentation ตามที่คุณเลือก ตรวจสอบ syntax พร้อมรายงานตำแหน่ง error ที่แม่นยำ และยัง minify กลับเป็นรูปแบบที่กระชับที่สุดสำหรับการส่งข้อมูลได้อีกด้วย ข้อมูลทุกอย่างไม่ถูกส่งขึ้น server ซึ่งสำคัญมากเมื่อเอกสารที่คุณกำลังดูมีชื่อ field ภายในองค์กร, API key ใน variable หรือข้อมูลลูกค้าประปนอยู่

บทความนี้จะพาไปดูว่าเครื่องมือทำอะไรได้บ้าง ใช้งานอย่างไร และทำไมการจัดรูปแบบกับ validate GraphQL document ก่อนนำกลับไปใส่ใน production code, pull request หรือ bug report จึงคุ้มค่ากับเวลาเพียงไม่กี่วินาที

ทำไมต้องใช้ GraphQL Formatter?

• อ่านเอกสารบรรทัดเดียวได้ทันที query ที่ copy มาจาก log, คำสั่ง curl หรือ client bundle แทบทุกตัวถูก minify ไว้แล้ว เครื่องมือจะสร้างเอกสารใหม่ทั้งหมดด้วยย่อหน้าที่สม่ำเสมอ ทำให้เห็นโครงสร้าง selection set ที่ซ้อนกันได้ในแวบเดียว
• Validate syntax จริงพร้อมตำแหน่ง error การใส่ comma เกิน วงเล็บไม่สมดุล หรือ argument วางผิดที่ ไม่ใช่แค่ดูไม่สวย แต่ parser จะรายงาน error พร้อมตำแหน่งบรรทัดและคอลัมน์ ให้คุณแก้ได้ก่อนที่ query จะไปถึง server
• ปรับ indentation ได้ เลือกความกว้างย่อหน้าให้ตรงกับ convention ของโปรเจกต์ ไม่ว่าจะเป็นสองช่องว่าง สี่ช่องว่าง หรือค่าอื่น ๆ เพื่อให้ output วางลงโค้ดได้เลยโดยไม่ต้องจัดย่อหน้ามือ
• โหมด minify สำหรับการส่งข้อมูลแบบกระชับ ตัดทุกตัวอักษรที่ไม่จำเป็นออกจากเอกสารที่ถูกต้อง เพื่อย่อขนาด request body สำหรับ mobile client, persisted query หรือ log ที่ต้องสั้น
• ใช้กับ schema ได้ด้วย parser ตัวเดียวกันรองรับเอกสาร SDL schema ทั้ง type, input, interface, enum และ directive ไม่ใช่แค่ operation ที่รันได้เท่านั้น
• เป็นส่วนตัวและรวดเร็ว การ parse และ format ทั้งหมดทำงานฝั่ง client ด้วย JavaScript ไม่มีการอัปโหลด ไม่มีการสมัครบัญชี ไม่มีคิวรอ จึงวางเอกสารที่มีข้อมูลอ่อนไหวได้อย่างมั่นใจ

ฟีเจอร์หลัก

มีรายละเอียดที่น่าสนใจอยู่บ้าง เครื่องมือจะ parse เอกสารก่อนแตะต้องมันเสมอ ทำให้การจัดรูปแบบและการ validate เกิดขึ้นในรอบเดียว คุณจะไม่ได้ output ที่เสียหายแบบเงียบ ๆ ส่วนตัว minifier ถูกออกแบบให้ระมัดระวัง โดยตัดเฉพาะช่องว่างที่ข้อกำหนดของ GraphQL ไม่ได้บังคับ ผลลัพธ์จึงเหมือนต้นฉบับในเชิงความหมายทุกประการ และเนื่องจากเครื่องมือนี้ไม่เก็บสถานะ คุณวาง จัดรูปแบบ copy แล้วไปต่อได้ในไม่กี่วินาที

วิธีการใช้งาน

1. เปิดเครื่องมือ เข้าไปที่หน้า GraphQL Formatter โหลดทันทีและใช้ได้ทั้งบนเดสก์ท็อปและเบราว์เซอร์มือถือ
2. วางเอกสารของคุณ วาง query แบบ minify จาก log, terminal หรือไฟล์ซอร์สโค้ดลงใน input editor วางได้ทั้ง operation และ SDL schema definition
3. เลือก indentation เลือกความกว้างย่อหน้าให้ตรงกับ codebase ของคุณ เพื่อให้ output คัดลอกเข้าโปรเจกต์ได้ทันที
4. จัดรูปแบบและ validate สั่ง format เพื่อ pretty-print เอกสาร ถ้า parser เจอ syntax error ให้อ่านตำแหน่งบรรทัดและคอลัมน์ที่รายงาน แก้ไขเอกสารแล้วรันใหม่จนกว่า output จะสะอาด
5. คัดลอกผลลัพธ์ copy เอกสารแบบจัดรูปแบบแล้วไปใช้ใน code review หรือเอกสารประกอบ หรือสลับไปโหมด minify ก่อนเมื่อต้องการรูปแบบที่กระชับที่สุดสำหรับ transport หรือ logging

ทำไมต้องจัดรูปแบบ Query ด้วย

ความอ่านง่ายคือจุดขายของภาษา query ตัวนี้ GraphQL ถูกออกแบบให้ request อ่านเหมือนรูปร่างของข้อมูลที่มันคืนกลับมา แต่ประโยชน์นี้จะเกิดขึ้นจริงก็ต่อเมื่อเอกสารถูกจัดวางอย่างเหมาะสม คือ field ละหนึ่งบรรทัด selection set ย่อหน้าไล่ระดับใต้ parent และ argument อยู่ตรงที่คุณคาดหวัง ใน code review query ที่จัดรูปแบบแล้วช่วยให้ reviewer เห็นว่า field ไหนถูกเพิ่มหรือลบได้ในไม่กี่วินาที ใน diff แต่ละ field ที่เปลี่ยนจะอยู่บนบรรทัดของตัวเอง ทำให้ pull request เล็กและ review ง่าย แทนที่จะเห็น mega-line ที่ถูกเขียนใหม่ทั้งบรรทัด

Validation ช่วยจับ error ก่อน runtime จะจับแทนคุณ query ที่วงเล็บไม่สมดุลหรือขาด comma จะ fail ตอน parse บน server พร้อมข้อความที่มักคลุมเครือและเสีย round trip ไปฟรี ๆ เครื่องมือนี้ validate syntax ในเครื่องของคุณและรายงานบรรทัดกับคอลัมน์ของปัญหาอย่างเป๊ะ ทำให้ typo ที่น่าจะแลกมาด้วยรอบ deploy หนึ่งรอบ กลายเป็นเรื่องที่แก้เสร็จในไม่กี่วินาที

Minification สำคัญในที่ที่ทุกไบต์มีค่า mobile client บนเครือข่ายมือถือต้องจ่ายทุกกิโลไบต์ของ request body ทั้งเรื่อง latency และแบตเตอรี่ การตัดช่องว่างที่ไม่มีผลออกจาก query ขนาดใหญ่มักประหยัดขนาดได้ไม่น้อยโดยความหมายไม่เปลี่ยนเลย เทคนิคเดียวกันยังทำให้ server log อ่านง่ายขึ้น เพราะ operation แบบ minify พอดีหนึ่งบรรทัดแทนที่จะไหลยาวยี่สิบบรรทัด

Schema ก็สมควรได้รับการดูแลเช่นกัน เอกสาร SDL ทั้ง type definition, input, enum และ interface ถูกทำร้ายด้วยการ copy-paste เหมือนกันทุกประการ schema ที่จัดรูปแบบแล้วหา field ง่ายกว่ามากเวลาคุณกำลังเช็กว่า field รับ input type หรือ enum และเลย์เอาต์ที่สม่ำเสมอทำให้การ review schema ใน pull request เร็วขึ้นชัดเจน

ลองดูความต่างในทางปฏิบัติ query ในรูปที่มักได้รับมา:

query OrderHistory($id: ID!) {
  user(id: $id) {
    name
    email
    orders(first: 10) {
      createdAt
      total
      items {
        product {
          name
          price
        }
        quantity
      }
    }
  }
}

และ query เดียวกันหลังจัดรูปแบบ:

query OrderHistory($id: ID!) {
  user(id: $id) {
    name
    email
    orders(first: 10) {
      createdAt
      total
      items {
        product {
          name
          price
        }
        quantity
      }
    }
  }
}

ความหมายเหมือนเดิมทุกอย่าง แต่ประสบการณ์การอ่านต่างกันคนละเรื่อง

กรณีการใช้งานจริง

ดีบัก API จาก Log

เมื่อ GraphQL operation ล้มเหลวบน production สิ่งแรกที่คุณได้มักเป็น request body จาก log การวางเอกสารบรรทัดเดียวนั้นลงใน formatter ทำให้เห็นโครงสร้างทันที และการ validate หนึ่งรอบบอกคุณได้ว่าความล้มเหลวเป็นปัญหา syntax ในตัว query เองหรือเกิดจากอย่างอื่น นี่คือวิธีเร็วที่สุดที่จะเปลี่ยน log บรรทัดเดียวที่อ่านไม่ออกให้เป็น request ที่อ่านเข้าใจได้

Diff ใน Code Review

ก่อน commit query ลง repository ให้ format มันก่อน reviewer จะเห็นการเปลี่ยนแปลงระดับ field บนบรรทัดของมันเอง และเครื่องมือ diff จะไฮไลต์สิ่งที่ขยับได้แม่นยำ การแก้วงเล็บหนึ่งตัวที่เคยทำให้บรรทัดยาวสี่สิบตัวอักษรถูกเขียนใหม่ทั้งบรรทัด ตอนนี้แตะต้องแค่บรรทัดเดียว

ลดขนาด Persisted Query

ทีมที่ส่ง persisted query หรือ query ที่ลงทะเบียนล่วงหน้า มักเก็บมันเป็นไฟล์หรือแถวในฐานข้อมูล การ minify เอกสารเหล่านี้ก่อนเก็บช่วยลดขนาด artifact และ payload ที่เล็กลงตอน runtime ย่อมดีต่อ client บนเครือข่ายจำกัด โดยเฉพาะแอปมือถือที่ส่ง query เต็มรูปแบบทุกครั้งที่โหลดหน้าจอ

เอกสาร Schema

การจัดรูปแบบ SDL schema คือรูปแบบเอกสารที่ถูกที่สุด ไฟล์ schema ที่ย่อหน้าสวยงามทำหน้าที่เป็นคู่มืออ้างอิงที่อ่านได้สำหรับ frontend developer ที่กำลังสำรวจ API และทำให้ schema diff ที่หลีกเลี่ยงไม่ได้ในการ review ตามได้ง่ายขึ้น

แนวปฏิบัติที่ดีที่สุด

• Format ใน CI ไม่ใช่ด้วยมือ เพิ่ม formatting check เข้าไปป์ไลน์เพื่อให้ query และ schema ที่ commit ทุกตัวมีสไตล์สม่ำเสมอ และ reviewer ไม่ต้องเถียงกันเรื่องช่องว่างอีก
• Minify เฉพาะตอน transport เก็บเอกสารที่อ่านง่ายและจัดรูปแบบแล้วไว้ใน repository แล้ว minify ตอน build หรือก่อนส่งเท่านั้น อย่า commit operation แบบ minify เป็น source of truth
• อย่าลืม format fragment ด้วย fragment เป็นเอกสารในตัวเอง ส่งผ่านการจัดรูปแบบชุดเดียวกันเพื่อให้ inline fragment และ named fragment อ่านตามได้เสมอ
• Validate ก่อนส่ง รัน syntax check ก่อนวาง query ที่แก้มือลงในโค้ดหรือ dashboard การเจอวงเล็บวางผิดที่ในเครื่องถูกกว่า request ที่ fail ใน staging เสมอ
• ใช้ indentation แบบเดียวกันทั้งทีม ตกลงความกว้างย่อหน้าเดียวสำหรับไฟล์ GraphQL ทุกไฟล์ เพื่อให้ output ที่จัดแล้วกลืนไปกับไฟล์เดิมโดยไม่เกิด re-indent ที่สร้าง noise
• ถือว่า output แบบ minify เป็นของใช้ชั่วคราว เพราะการ minify ไม่มีการสูญเสีย คุณสร้างมันใหม่ได้เสมอ อย่าเก็บรูปแบบกระชับไว้ในที่ที่ควรมีแต่รูปแบบที่อ่านง่าย

เริ่มใช้งาน GraphQL Formatter วันนี้

ถ้าคุณเคยหรี่ตาอ่าน query บรรทัดเดียวใน log หรือเคยส่ง typo ที่การ validate สองวินาทีจะจับได้ GraphQL Formatter สมควรอยู่ใน bookmarks bar ของคุณ วางเอกสาร เลือก indentation validate syntax แล้ว copy output ที่สะอาด ทั้งหมดในเบราว์เซอร์โดยไม่มีข้อมูลใดถูกส่งไป server ใด ๆ และเมื่อต้องการดู response payload ที่ query เหล่านี้คืนมา ให้จับคู่กับ JSON Formatter ได้เลย

เครื่องมือที่เกี่ยวข้องที่คุณอาจสนใจ:

• JSON Formatter — pretty-print และ validate JSON response ที่ query ของคุณคืนมา
• XML Formatter — จัดรูปแบบและตรวจสอบเอกสารและ config ภาษา XML
• SQL Formatter — pretty-print SQL query ด้วยความใส่ใจเท่าที่คุณให้ GraphQL

ขอให้สนุกกับการจัดรูปแบบ query ครับ

คำถามที่พบบ่อย

ถ: GraphQL Formatter ใช้ฟรีหรือไม่? ตอบ: ใช่ครับ เครื่องมือใช้ฟรีทั้งหมด ไม่ต้องสมัครบัญชี และไม่มีขีดจำกัดการใช้งาน

ถ: query ของฉันถูกอัปโหลดไปที่ server หรือเปล่า? ตอบ: ไม่ครับ การ parse, จัดรูปแบบ, validate และ minify ทั้งหมดเกิดขึ้นในเบราว์เซอร์ของคุณ เอกสารไม่เคยออกจากเครื่อง

ถ: จัดรูปแบบ schema ได้ไหม หรือทำได้แค่ query? ตอบ: ได้ครับ เครื่องมือรองรับเอกสาร SDL ทั้ง type definition, input, interface, enum และ directive ตลอดจน query, mutation และ subscription

ถ: การ minify query เปลี่ยนพฤติกรรมของมันหรือไม่? ตอบ: ไม่เปลี่ยนครับ การ minify ตัดเฉพาะช่องว่างที่ข้อกำหนดของ GraphQL ไม่ได้บังคับ เอกสารที่ minify แล้วจึงเหมือนต้นฉบับในเชิงความหมายทุกประการ

ถ: ตำแหน่ง error ในข้อความ validation หมายความว่าอะไร? ตอบ: parser จะรายงานบรรทัดและคอลัมน์ที่ตรวจพบปัญหา syntax เช่น วงเล็บไม่สมดุลหรือ comma วางผิดที่ เพื่อให้คุณกระโดดไปแก้จุดนั้นได้ทันที