กรณีการใช้งานสำหรับการกำหนดเวอร์ชันของ fields และ directives

กรุณาอ่านคู่มือ การพัฒนา schema ผ่าน field versioning ก่อน ซึ่งอธิบายฟีเจอร์ "field versioning" ใน Gato GraphQL

Gato GraphQL อนุญาตให้ fields และ directives รับ argument versionConstraint เพื่อเลือกเวอร์ชันที่ต้องการ (กล่าวคือ การ implementation) ของ field/directive นั้นๆ:

query GetPosts {
  posts(versionConstraint: "^1.0") {
    id
    title(versionConstraint: ">=2.1")
    excerpt @strUpperCase(versionConstraint: "~1.5.3")
  }
}Copy

field (หรือ directive) สามารถมี implementation เริ่มต้นได้เช่นกัน ซึ่งคือตัวที่ไม่มีเวอร์ชัน (และเป็นตัวที่ใช้งานเมื่อไม่ได้ระบุ versionConstraint ใน query)

เมื่อทำ introspection จะดึงข้อมูลเฉพาะของ fields และ directives เริ่มต้นเท่านั้น ผลลัพธ์คือ argument versionConstraint จะไม่ปรากฏเมื่อทำ introspection เนื่องจาก field หรือ directive เริ่มต้นไม่รองรับมัน

ด้วยเหตุนี้ เราต้องทราบล่วงหน้าเสมอว่า field หรือ directive มีสองเวอร์ชันขึ้นไปให้เลือก และต้องทราบหมายเลขเวอร์ชันเหล่านั้น ข้อมูลนี้โดยค่าเริ่มต้นจะไม่เปิดเผยต่อสาธารณะ

แล้ว versioning มีประโยชน์อย่างไร? ต่อไปนี้คือกรณีการใช้งานหลายประการ

​

การแก้ไขบั๊กอย่างรวดเร็วสำหรับผู้ใช้เฉพาะราย

สมมติว่าคุณมี GraphQL API ที่ deploy บนเว็บไซต์ของคุณ และผู้ใช้รายหนึ่งแจ้งว่า field ทำงานไม่ตามที่คาดไว้ แต่ปัญหานี้เกิดขึ้นเฉพาะกับผู้ใช้รายนี้เท่านั้น ไม่มีใครอื่นดูเหมือนจะประสบปัญหา

คุณระบุและแก้ไขปัญหาได้แล้ว แต่ต้องการให้แน่ใจว่ามันทำงานได้ก่อน deploy การเปลี่ยนแปลงให้ทุกคน คุณสามารถ deploy การเปลี่ยนแปลงภายใต้ field resolver ใหม่ที่มีเวอร์ชัน "1.0.1" และขอให้ผู้ใช้ที่มีปัญหาเปลี่ยน GraphQL query ให้ชี้ไปที่เวอร์ชันนี้ของ field:

{
  someBuggyField(versionConstraint: "1.0.1")
}Copy

หากบั๊กได้รับการแก้ไขจริงๆ จึงค่อย copy โค้ดไปยัง field resolver เริ่มต้น

​

ขอให้ผู้ใช้ที่เลือกทดสอบ release ที่กำลังจะมาถึง

หาก field หรือ directive มีการกำหนดเวอร์ชัน และไม่มี implementation เริ่มต้น (กล่าวคือ ไม่มีเวอร์ชัน) มันจะไม่ปรากฏในระหว่าง introspection เลย

{
  someField
    # This directive has no default implementation,
    # so it won't appear during introspection,
    # but it can still be added in the GraphQL query
    # when providing a constraint that satisfies it
    @someExperimentalDirective(versionConstraint: ">1.0")
}Copy

คุณสามารถ deploy field หรือ directive และมันจะไม่ปรากฏให้เห็นใน GraphQL API และขอให้ผู้ใช้ที่เลือกทดสอบ โดยพวกเขาต้องระบุ argument versionConstraint ที่สอดคล้องกันใน queries เพื่อใช้งานมัน

เมื่อได้รับการยอมรับแล้ว การกำหนดเวอร์ชันจะถูกลบออก และ field หรือ directive จะปรากฏผ่าน introspection และพร้อมใช้งานสำหรับทุกคน