การกำกับดูแลสคีมา GraphQL: ตรวจสอบ Breaking Changes ก่อนรีลีส

สรุปสั้น

GraphQL schema governance คือวินัยในการปล่อยเวอร์ชันที่ทำให้ schema ยังมีประโยชน์ขณะที่มันเปลี่ยนแปลง ก่อนปล่อยแต่ละครั้ง ให้จำแนกการแก้ไข schema ทดสอบ operation ตัวแทนของไคลเอนต์ เผยแพร่เส้นทางการเลิกใช้ และตรวจสอบเอกสาร พื้นที่ทำงานร่วมกันอย่าง Apidog รวมการออกแบบ คำขอ การทดสอบ เอกสาร และงาน mock ไว้ในที่เดียว

• มอง GraphQL schema เป็นสัญญาสาธารณะ ไม่ใช่รายละเอียดการทำงานภายใน
• ตรวจจับ breaking changes ก่อนไปถึงไคลเอนต์
• เพิ่มฟิลด์ทดแทนก่อนที่คุณจะเลิกใช้ฟิลด์เก่า
• ทดสอบ saved operations กับ schema ที่เป็นตัวเลือกและสัญญาการตอบกลับ
• บันทึกเจ้าของ การตัดสินใจรีวิว ผลกระทบต่อผู้บริโภค และวันลบ
• เผยแพร่ release notes ที่บอกทีมไคลเอนต์ว่าต้องเปลี่ยนอะไรและเมื่อไร

บทนำ

GraphQL schema governance ป้องกันไม่ให้การปล่อย API ทำให้แอปมือถือ เว็บไคลเอนต์ การเชื่อมต่อ และบริการภายในเสียโดยไม่แจ้งเตือน GraphQL ทำให้ query ของไคลเอนต์ยืดหยุ่น แต่ทุกฟิลด์ argument ค่า enum กฎ nullability และ input object ยังคงกลายเป็นส่วนหนึ่งของสัญญาเมื่อไคลเอนต์พึ่งพามัน

สัญญานั้นเปลี่ยนแปลงบ่อย ทีมผลิตภัณฑ์เปลี่ยนชื่อ displayName ทีม backend ทำให้ input ที่เคยเป็นทางเลือกกลายเป็นบังคับ บริการ billing ลบค่า enum หนึ่งค่า การแก้ไขแต่ละอย่างอาจดูไม่เป็นอันตรายใน schema editor แต่ทำให้ saved operation ใน production ใช้ไม่ได้

ข้อกำหนด GraphQL อธิบายระบบชนิด กฎการตรวจสอบ และข้อกังวลเรื่องวิวัฒนาการ schema ของ GraphQL มันให้ภาษากลางแก่ทีม ส่วน governance ให้กระบวนการปล่อย: ใครรีวิวการเปลี่ยนแปลง ทีมประเมินผลกระทบต่อไคลเอนต์อย่างไร ทดสอบอย่างไร และเลิกใช้ฟิลด์เก่าอย่างไรโดยไม่ทำให้เกิด outage ที่ไม่คาดคิด

บทความนี้เน้นการควบคุมการปล่อยมากกว่าบทนำ GraphQL หากทีมของคุณต้องการเวิร์กโฟลว์ระดับคำขอก่อน โปรดดู วิธีทดสอบ GraphQL APIs ใน Apidog ขั้นถัดไปคือทำให้การทดสอบเหล่านั้นเป็นส่วนหนึ่งของกระบวนการเปลี่ยนแปลง schema ที่ยั่งยืน

GraphQL schema governance คืออะไร?

GraphQL schema governance คือกระบวนการที่ทำซ้ำได้สำหรับการรีวิว ทดสอบ จัดทำเอกสาร และอนุมัติการเปลี่ยนแปลง schema ก่อนปล่อย มันระบุการแก้ไขที่ทำให้ไคลเอนต์เสีย กำหนดเส้นทางการย้ายที่ได้รับอนุมัติ และทำให้เจ้าของมองเห็นได้ เป้าหมายคือวิวัฒนาการ schema ที่คาดเดาได้: ไคลเอนต์มีเวลาและคำแนะนำในการย้ายก่อนสัญญาเก่าหายไป

Governance ไม่ได้หมายถึงการแช่แข็ง schema GraphQL API ที่healthy เปลี่ยนแปลงไปพร้อมผลิตภัณฑ์ กระบวนการทำให้มันเปลี่ยนแปลงอย่างปลอดภัย

นโยบาย governance ที่มีประโยชน์ตอบคำถามห้าข้อสำหรับทุก pull request หรือ release candidate:

1. อะไรเปลี่ยนใน schema?
2. การเปลี่ยนแปลงใดทำให้ operation ของไคลเอนต์ที่เคยถูกต้องล้มเหลวได้?
3. ใครเป็นเจ้าของฟิลด์ที่ได้รับผลกระทบและการย้ายไคลเอนต์?
4. saved operations และการตรวจสอบการตอบกลับใดพิสูจน์ความเข้ากันได้?
5. เมื่อไรจึงลบฟิลด์หรือค่า enum ที่เลิกใช้ได้?

คำถามเหล่านั้นเปลี่ยนคำขอที่คลุมเครือว่า “API review” ให้เป็นหลักฐานที่ผู้รีวิวตรวจสอบได้

ทำไม GraphQL ต้องมีกระบวนการปล่อยที่ชัดเจน

ไคลเอนต์ GraphQL ประกอบ selection set ของตัวเอง ไคลเอนต์สองรายสามารถเรียก query root เดียวกันขณะพึ่งพาฟิลด์ fragments ตัวแปร และ alias ที่ต่างกันโดยสิ้นเชิง Telemetry ของเซิร์ฟเวอร์ saved queries และความรู้ของทีมผู้บริโภคช่วยได้ทั้งหมด แต่ไม่มีสิ่งใดเพียงอย่างเดียวพิสูจน์ได้ว่าการแก้ไขปลอดภัย

การเปลี่ยนแปลงยังอาจผ่าน unit test ของเซิร์ฟเวอร์แต่ล้มเหลวที่ไคลเอนต์ตอน validation การลบฟิลด์ทำให้ทุก operation ที่เลือกฟิลด์นั้นไม่ถูกต้อง การเพิ่ม input ฟิลด์ที่บังคับอาจทำให้ operation ที่ละเว้นฟิลด์นั้นไม่ถูกต้อง การเปลี่ยน enum อาจทำให้ไคลเอนต์ที่ถูก generate หรือ switch branch แบบ exhaustive ไม่สามารถจัดการการตอบกลับจากเซิร์ฟเวอร์ได้ การเปลี่ยนชนิดฟิลด์ nullable เป็นรูปแบบอื่นอาจทำให้การ parse หรือสมมติฐาน UI เสีย

ความตึงเครียดแบบเดียวกันปรากฏในงาน API management แพลตฟอร์ม GraphQL API management ควรช่วยทีมให้การตัดสินใจเรื่องสัญญา เอกสาร และ validation อยู่ใกล้ API Governance ทำให้ความสามารถเหล่านั้นมีประโยชน์ระหว่างการปล่อย แทนที่จะเป็นหลังเกิดเหตุ

จำแนกการแก้ไข schema ก่อนโต้เถียงกัน

เริ่มทุกการเปลี่ยนแปลงด้วยการจำแนก ป้ายกำกับไม่จำเป็นต้องซับซ้อน แต่ต้องนำไปสู่เส้นทางการรีวิวที่ถูกต้อง

ตารางนี้เป็นจุดเริ่มต้น การเปลี่ยนแปลงที่คิดว่าเป็นการเพิ่มยังอาจสำคัญได้ ตัวอย่างเช่น ไคลเอนต์ที่ถูก generate หรือตัวตรวจสอบการตอบกลับที่เข้มงวดบางตัวถือว่าฟิลด์ที่ไม่รู้จักเป็นปัญหา การตั้งค่าresponse-validationของ Apidog อนุญาต additional object properties โดยค่าเริ่มต้น หากนโยบายของคุณต้องการตรวจสอบ properties ที่ไม่คาดคิด ให้ตั้ง additionalProperties เป็น Deny สำหรับ response schema ที่เกี่ยวข้อง หรือเปลี่ยนการตั้งค่าโปรเจกต์อย่างจงใจ

การเปลี่ยนแปลงที่ควรหยุดการปล่อยโดยค่าเริ่มต้น

การรีวิวควรต้องมีอนุมัติชัดเจนเมื่อมีสิ่งใดต่อไปนี้:

• ลบฟิลด์ argument input field mutation query interface implementation union member หรือค่า enum
• เปลี่ยนชื่อฟิลด์แทนการเพิ่มฟิลด์ทดแทนและเลิกใช้ชื่อเก่า
• ทำให้ input ที่เคยเป็นทางเลือกกลายเป็นบังคับ
• เปลี่ยนชนิดฟิลด์ ความคาดหวัง nullability รูปแบบ พฤติกรรมการอนุญาต พฤติกรรมการแบ่งหน้า หรือสัญญาข้อผิดพลาด
• ใช้ชื่อฟิลด์เดิมซ้ำเพื่อความหมายทางธุรกิจที่แตกต่าง
• เปลี่ยนค่าเริ่มต้นที่ไคลเอนต์ตั้งใจละเว้น

กฎง่ายๆ: ถ้า query ของไคลเอนต์หรือสมมติฐานฝั่งไคลเอนต์ทำงานเมื่อวานและอาจล้มเหลวพรุ่งนี้ ให้จำแนกว่า breaking จนกว่าหลักฐานจะบอกเป็นอย่างอื่น

ใช้ deprecation เป็นสัญญาการย้าย

Deprecation ได้ผลเมื่อมีเส้นทางเดินหน้าจริง “Deprecated” โดยไม่มีสิ่งทดแทน เจ้าของ กำหนดเวลา หรือบันทึกการย้าย เพียงแค่เลื่อน breaking change ออกไป

พิจารณาการทำความสะอาดชื่อลูกค้า อย่าเปลี่ยนชื่อฟิลด์ในที่:

# Avoid removing fullName in the same release.
type Customer {
 fullName: String!
}

เพิ่มสิ่งทดแทน อธิบายเหตุผล แล้วรองรับทั้งสองฟิลด์ตลอดช่วงเวลาที่ประกาศ:

type Customer {
 displayName: String!
 fullName: String! @deprecated(reason: "Use displayName. Removal planned after client migration.")
}

สิ่งทดแทนต้องการมากกว่าคำอธิบายใน schema เพิ่มในเอกสาร อัปเดตไคลเอนต์ first-party ระบุผู้บริโภคที่มีคุณค่าสูง และติดตามการนำไปใช้ ลบฟิลด์เก่าหลังจากเกณฑ์ออกจากการย้ายครบถ้วนแล้วเท่านั้น

สร้างเวิร์กโฟลว์ GraphQL schema governance

เวิร์กโฟลว์ที่ทำซ้ำได้มีจุดตรวจ ไม่ได้ขึ้นอยู่กับคนคนเดียวที่จำรายละเอียดไคลเอนต์ทุกอย่างระหว่างการปล่อยที่เร่งรีบ

1. กำหนดแหล่งความจริงและเจ้าของที่มีชื่อ

เก็บแหล่ง schema ที่อนุมัติหนึ่งแหล่ง และกำหนดเจ้าของสำหรับแต่ละพื้นที่ที่มีขอบเขต เช่น catalog, billing, identity หรือ fulfillment เจ้าของไม่จำเป็นต้องเขียน resolver ทุกตัว แต่ต้องตอบคำถามเรื่องสัญญาและอนุมัติการเปลี่ยนแปลงในพื้นที่นั้น

บันทึกรายละเอียดเหล่านี้พร้อมกับการเปลี่ยนแปลง schema:

• พื้นที่ schema และทีมเจ้าของ
• การจำแนกการเปลี่ยนแปลง
• ผู้บริโภคที่รู้ว่าใช้ฟิลด์หรือ operation ที่ได้รับผลกระทบ
• ฟิลด์ทดแทนหรือคำแนะนำการย้าย
• วันลบเร็วที่สุด
• การทดสอบที่พิสูจน์ว่า release candidate ทำงานได้

บันทึกนี้ป้องกันไม่ให้ฟิลด์กลายเป็นพื้นที่สาธารณะที่ถูกทิ้งร้าง

2. Diff schema ที่เป็นตัวเลือกและกำหนดความเสี่ยง

สร้างหรือรีวิว schema diff ระหว่าง release ปัจจุบันกับ candidate อย่าหยุดที่ diff แบบบรรทัดต่อบรรทัด แปลผลลัพธ์เป็นผลกระทบต่อไคลเอนต์

สำหรับแต่ละ type ที่เปลี่ยน ถามว่า query ที่มีอยู่ทำให้ไม่ถูกต้องได้หรือไม่ การตอบกลับ JSON ที่มีอยู่เปลี่ยนรูปร่างได้หรือไม่ และพฤติกรรมเปลี่ยนโดยไม่มีการเปลี่ยนในระบบชนิดหรือไม่ กฎ Auth เป็นตัวอย่างทั่วไป schema อาจเหมือนเดิมขณะที่ฟิลด์ที่เคยมองเห็นเริ่มส่ง authorization error หรือ null

ใช้บันทึกการเปลี่ยนแปลงสั้นๆ เช่นนี้:

change: remove Customer.fullName
type: breaking
owner: customer-platform
replacement: Customer.displayName
deprecated_since: 2026-08-21
planned_removal: 2026-11-21
known_consumers:
 - ios-storefront
 - partner-portal
release_checks:
 - saved-operation-suite
 - client-migration-confirmations
 - published-release-notes

วันที่เป็นเพียงตัวอย่าง นโยบายของคุณควรกำหนดช่วง deprecation ที่ตรงกับจังหวะการปล่อย ความเร็วในการอัปเดตไคลเอนต์ และข้อผูกพันตามสัญญา

3. ทดสอบ operation จริง ไม่ใช่แค่ syntax ของ schema

Schema อาจ parse ผ่านแต่ยังทำให้ไคลเอนต์เสียได้ ดูแลชุด operation ตัวแทนสำหรับผู้บริโภคหลักหรือ user journey แต่ละเส้น รวม fragments ตัวแปร การแบ่งหน้า ขอบเขตสิทธิ์ ข้อผิดพลาด และฟิลด์ทางเลือก

สำหรับ storefront ชุดทดสอบอาจรวม:

query ProductPage($sku: ID!, $first: Int!) {
 product(sku: $sku) {
 id
 displayName
 price {
 amount
 currency
 }
 relatedProducts(first: $first) {
 nodes {
 id
 displayName
 }
 }
 }
}

รัน operation กับสภาพแวดล้อม candidate ตรวจสอบ HTTP status, GraphQL errors, ค่าการตอบกลับที่จำเป็น ความคาดหวังชนิด และกฎธุรกิจที่สำคัญต่อไคลเอนต์ การตอบกลับที่มี HTTP 200 และอาร์เรย์ errors ไม่ใช่ GraphQL operation ที่สำเร็จสำหรับหลายกรณีการใช้งาน

ใช้ request fixtures ที่ครอบคลุมกรณีขอบจริง: รายการว่าง ฟิลด์ทางเลือกที่เป็น null ทรัพยากรที่ถูกลบ การปฏิเสธสิทธิ์ ความแตกต่างตาม locale และ cursor ที่เก่า saved operations กลายเป็นหลักฐานเบื้องหลังการตัดสินใจปล่อย

4. ทำให้เอกสารเป็นส่วนหนึ่งของประตูตรวจ

เอกสารต้องการวันรีวิวเดียวกับ schema ฟิลด์ที่มีอยู่แต่ขาดคำอธิบาย ตัวอย่าง หมายเหตุสิทธิ์ หรือคำแนะนำการย้าย ทำให้ทีมไคลเอนต์ต้องย้อนรอยเจตนา

สำหรับแต่ละฟิลด์หรือ input ที่ได้รับผลกระทบ ตรวจสอบ:

• คำอธิบายอธิบายความหมายทางธุรกิจแทนพฤติกรรม resolver หรือไม่?
• ความคาดหวังเรื่อง nullability และค่าเริ่มต้นชัดเจนหรือไม่?
• ฟิลด์ที่เลิกใช้ระบุสิ่งทดแทนหรือไม่?
• ตัวอย่างที่เกี่ยวข้องใช้ฟิลด์ใหม่หรือไม่?
• changelog อธิบายการดำเนินการ กลุ่มเป้าหมาย และวันลบหรือไม่?

นี่คือจุดที่ทีมป้องกันปัญหาทั่วไปของ GraphQL schema ที่ทำงานได้เฉพาะเมื่อมี introspection เอกสารอ้างอิงที่เผยแพร่และ release notes ต้องยืนได้ด้วยตัวเองสำหรับไคลเอนต์ภายนอกและสภาพแวดล้อมที่จำกัด

5. ปล่อย สังเกต และลบตามหลักฐาน

เผยแพร่การจำแนกการเปลี่ยนแปลงและบันทึกการย้ายก่อนกำหนดลบ ติดตามการย้ายไคลเอนต์ด้วย telemetry ที่รู้จัก schema เมื่อทำได้ การยืนยันจากพาร์ตเนอร์สำหรับผู้บริโภคภายนอก และหลักฐานความสำเร็จจากทีม first-party

เมื่อถึงวันสิ้นสุด ให้รันชุด saved operation อีกครั้ง หาก operation สำคัญยังใช้ฟิลด์ที่เลิกใช้ ให้เลื่อนการลบออกไป ฟิลด์เก่ามีต้นทุนน้อยกว่า client outage ที่หลีกเลี่ยงได้

ใช้ Apidog ทำให้การรีวิวทำซ้ำได้

Apidog ให้ทีม API มีพื้นที่ทำงานเดียวสำหรับการออกแบบ การดีบัก การทดสอบ เอกสาร และ mocks สำหรับกระบวนการ GraphQL governance เป้าหมายที่มีประโยชน์คือร่องรอยการรีวิวร่วมกัน ไม่ใช่เครื่องมือแยกสำหรับแต่ละขั้นตอนการปล่อย

ใน Apidog สร้าง GraphQL request ผ่าน Body > GraphQL จากนั้นใช้ Fetch Schema เพื่อโหลด schema editor GraphQL ใช้ schema ที่ดึงมาเพื่อแนะนำฟิลด์และชนิด และตรวจสอบ query กับ schema นั้น อ่านเอกสาร GraphQL request อย่างเป็นทางการก่อนกำหนดเวิร์กโฟลว์ของทีม

การตั้งค่าการปล่อยที่ใช้ได้จริงมีลักษณะดังนี้:

1. บันทึก query และ mutation ตัวแทนสำหรับแต่ละโฟลว์สำคัญ
2. วางตัวแปรเฉพาะสภาพแวดล้อมไว้นอก query เพื่อให้รูปร่าง operation คงที่
3. เพิ่ม assertions สำหรับ status, headers, รูปร่างการตอบกลับ JSON, ฟิลด์ที่จำเป็น, enums และพฤติกรรมข้อผิดพลาด
4. จัดกลุ่มการตรวจสอบเป็นชุด release suite สำหรับสภาพแวดล้อม candidate
5. รีวิวการตรวจสอบที่ล้มเหลวพร้อม schema diff และบันทึกการเปลี่ยนแปลงก่อนอนุมัติ
6. เผยแพร่เอกสารและบันทึกการย้ายจากสัญญา API ที่อนุมัติเดียวกัน

การตรวจสอบการตอบกลับตรวจ status, format และความสอดคล้องของ schema การตรวจสอบที่ระบุไว้รวมถึงฟิลด์ที่จำเป็น ชนิด nullability ค่า enum ช่วง และแพตเทิร์นสำหรับการตอบกลับ JSON และ XML ทำให้มีประโยชน์กับ body การตอบกลับ GraphQL เพราะการตอบกลับ GraphQL ใช้ JSON มันไม่ได้แทนที่เครื่องมือ GraphQL schema-diff หรือ consumer inventory ใช้ร่วมกันทั้งสอง

หากทีมของคุณเริ่มจาก request-level tests เครื่องมือทดสอบและ mocking GraphQL ช่วยวางกรอบชั้นการทดสอบได้ Governance เพิ่มบันทึกการปล่อย เจ้าของ และนโยบาย deprecation รอบการทดสอบเหล่านั้น

ดาวน์โหลด Apidog เมื่อคุณต้องการให้การออกแบบ request การตรวจสอบการตอบกลับ เอกสาร และเวิร์กโฟลว์ mock อยู่ในพื้นที่ทำงานเดียว เก็บนโยบาย governance ไว้ใน repository และใช้พื้นที่ทำงานเพื่อให้การรีวิวแต่ละ release มีหลักฐานการทดสอบที่เป็นรูปธรรม

เทคนิคขั้นสูงสำหรับ GraphQL APIs ขนาดใหญ่

กำหนดระดับชั้นผู้บริโภค

ไม่ใช่ทุกไคลเอนต์มีความเสี่ยงในการปล่อยเท่ากัน จำแนกผู้บริโภคตามผลกระทบและความเร็วในการอัปเกรด:

ระดับชั้นช่วยไม่ให้การทดลองภายในเล็กๆ สร้างภาระการปล่อยเท่ากับ payment flow และยังช่วยไม่ให้การเชื่อมต่อภายนอกที่สำคัญถูกปฏิบัติเหมือน query ที่ไม่ได้ติดตาม

ติดตามการเปลี่ยนแปลงพฤติกรรมนอก schema

Schema diff ตรวจจับการเปลี่ยนแปลงสัญญาได้ไม่ทั้งหมด เพิ่มคำถามรีวิวสำหรับ:

• การอนุญาตและการเข้าถึงระดับฟิลด์
• ลำดับการแบ่งหน้า อายุ cursor และขีดจำกัดขนาดหน้า
• พฤติกรรมการแคชและจังหวะการ invalidation
• ส่วนขยายข้อผิดพลาดและข้อความข้อผิดพลาดที่ผู้ใช้เห็น
• พฤติกรรมการจำกัดอัตราและคำแนะนำการลองใหม่
• ประสิทธิภาพ resolver ที่ทำให้ operation ที่ถูกต้องกลายเป็นไม่น่าเชื่อถือ

เขียนการทดสอบเจาะจงสำหรับการเปลี่ยนแปลงพฤติกรรมที่วางแผนแต่ละอย่าง ช่วยป้องกันไม่ให้ป้าย “ไม่มีการเปลี่ยนแปลง schema แบบ breaking” อย่างผิวเผินกลายเป็นผ่านการปล่อย

มองขอบเขต federation เป็นขอบเขตสัญญา

หากหลายทีมร่วมสร้าง subgraphs ทุก entity, key และฟิลด์ข้าม subgraph ที่ใช้ร่วมกันต้องมีเจ้าของชัดเจน ฟิลด์อาจดูเป็น local สำหรับทีมหนึ่งขณะที่อีก subgraph ขยายหรือบริโภคมัน

กำหนดให้มีรายการ subgraph ที่ได้รับผลกระทบในบันทึกการเปลี่ยนแปลง ทดสอบพฤติกรรม schema ที่ประกอบแล้วและ operation แบบ end-to-end ที่ข้ามขอบเขต การตรวจ schema local ที่สะอาดไม่ได้พิสูจน์ว่า composed graph ทำงานได้

กำหนดเส้นทางข้อยกเว้น

การลบแบบเร่งด่วนเกิดขึ้นเมื่อฟิลด์เปิดเผยข้อมูล สร้างปัญหาความปลอดภัย หรือก่อให้เกิดอันตรายด้านปฏิบัติการอย่างร้ายแรง Governance ต้องมีเส้นทางข้อยกเว้นเพื่อให้ทีมไม่ข้ามเอกสารและการทดสอบภายใต้ความกดดัน

บันทึกข้อยกเว้นควรระบุความเสี่ยง เจ้าของผู้อนุมัติ ผู้บริโภคที่ได้รับผลกระทบ การบรรเทา และแผนติดตามผล แจ้งผู้บริโภคโดยตรงเมื่อไม่สามารถใช้ช่วง deprecation ปกติได้ จากนั้นเพิ่ม regression test เพื่อไม่ให้ความผิดพลาดเดิมกลับมา

ทางเลือกและข้อจำกัด

Schema registry, federation gateway, ไคลเอนต์ที่ถูก generate หรือการตรวจ schema-diff ใน CI ล้วนช่วยได้ แต่ไม่มีสิ่งใดแทนที่กระบวนการทั้งหมด

เลือกสแตกที่เล็กที่สุดซึ่งสร้างหลักฐานเชื่อถือได้สำหรับ API ของคุณ หากทีมของคุณกำลังตัดสินใจว่า GraphQL เหมาะกับบริการใหม่หรือไม่ ให้เปรียบเทียบโมเดล query ที่ขับเคลื่อนโดยไคลเอนต์กับ REST และ gRPC ใน REST vs GraphQL vs gRPC การเลือกโปรโตคอลและ governance การปล่อยเป็นการตัดสินใจแยกกัน สัญญาสาธารณะทุกอันยังต้องมีทั้งสอง

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

แอปมือถือต้องเปลี่ยนชื่อฟิลด์โปรไฟล์

ทีมโปรไฟล์ต้องการแทนที่ fullName ด้วย displayName เพราะบัญชีองค์กรใช้โมเดลการตั้งชื่อที่ต่างออกไป เส้นทาง governance ไม่ใช่ commit เปลี่ยนชื่อแล้วปล่อย

เพิ่ม displayName เก็บ fullName ไว้พร้อมเหตุผล deprecation อัปเดต query ของมือถือ ทดสอบทั้งสองฟิลด์ระหว่างการเปลี่ยนผ่าน และรวบรวมข้อมูลการนำไปใช้ตามเวอร์ชันแอป ลบ fullName หลังจากเวอร์ชันแอปที่รองรับไม่พึ่งพามันอีกต่อไป หรือช่วงการสนับสนุนที่ประกาศไว้สิ้นสุดลง

mutation checkout มีข้อกำหนด input ใหม่

ทีม payment ต้องการให้ CheckoutInput.taxRegion กลายเป็นบังคับ เวอร์ชันแอปที่มีอยู่ละเว้นค่านั้น การทำให้ input บังคับทันทีอาจทำให้ operation checkout ที่ถูกต้องล้มเหลวตอน validation

ทำให้ input เป็นทางเลือกระหว่างการย้าย กำหนดพฤติกรรม fallback ของเซิร์ฟเวอร์ เผยแพร่ข้อกำหนดใหม่ อัปเดตไคลเอนต์ และเพิ่มกรณีทดสอบสำหรับรูปแบบคำขอเก่าและใหม่ หลังจากไคลเอนต์ย้ายแล้ว ให้กำหนดกฎบังคับใน release แบบ breaking ที่วางแผนไว้

พาร์ตเนอร์เห็นการเปลี่ยนแปลงฟิลด์ที่ไม่ได้บันทึก

พาร์ตเนอร์ parse ฟิลด์ตอบกลับเป็น string แต่ backend ต้องการคืนค่าเป็น object ที่มีโครงสร้าง แม้ไคลเอนต์ภายในย้ายแล้ว พาร์ตเนอร์อาจล้มเหลวขณะรัน

ทีมเจ้าของบันทึกพาร์ตเนอร์เป็นผู้บริโภคระดับ 1 เพิ่มฟิลด์ทดแทนแทนการเปลี่ยนฟิลด์เก่าในที่ ให้สภาพแวดล้อมทดสอบแก่พาร์ตเนอร์ และตรวจสอบ saved operation ของพาร์ตเนอร์ก่อนลบ เอกสารและการสื่อสารโดยตรงเป็นส่วนหนึ่งของหลักฐานการปล่อย

เริ่มด้วยเช็กลิสต์การปล่อยหนึ่งรายการ

เริ่มเล็กๆ เลือกพื้นที่ GraphQL ที่มีงานไคลเอนต์ active มากที่สุด และกำหนดให้มีบันทึกการเปลี่ยนแปลงสำหรับการแก้ไข schema ทุกครั้งในเดือนนี้ จำแนกการเปลี่ยนแปลง บันทึก operation ตัวแทน จัดทำเอกสาร deprecation และกำหนดผู้อนุมัติที่มีชื่อสำหรับการลบ

จากนั้นทำให้เช็กลิสต์เป็นนิสัยการปล่อย Apidog สามารถเก็บ requests, response validation, เอกสาร, mock scenarios และหลักฐานการทดสอบไว้ด้วยกัน ขณะที่ repository ของคุณยังเป็นแหล่งนโยบาย governance ผลลัพธ์คือ rollback ฉุกเฉินที่น้อยลงและความคาดหวังที่ชัดเจนขึ้นสำหรับผู้บริโภค API ทุกคน

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

อะไรถือเป็นการเปลี่ยนแปลง GraphQL schema แบบ breaking?

การเปลี่ยนแปลงเป็น breaking เมื่อ operation ของไคลเอนต์ที่ถูกต้องก่อนปล่อยอาจล้มเหลวหลังปล่อย การลบฟิลด์หรือ argument เป็นตัวอย่างชัดเจน การทำให้ input ที่เคยเป็นทางเลือกกลายเป็นบังคับ การเปลี่ยนชนิดโดยไม่ประเมินความเข้ากันได้ การลบค่า enum หรือการเปลี่ยนพฤติกรรมฟิลด์ก็อาจทำให้ไคลเอนต์เสียได้

การเพิ่มฟิลด์ GraphQL ปลอดภัยเสมอหรือไม่?

โดยปกติ การเพิ่มฟิลด์ทางเลือกไม่ทำให้ operation ที่มีอยู่ไม่ถูกต้อง แต่อาจส่งผลต่อไคลเอนต์ที่ปฏิเสธ properties ตอบกลับที่ไม่คาดคิดอย่างเคร่งครัด โค้ดที่ generate เอกสาร เวิร์กโฟลว์เอกสาร หรือเครื่องมือ schema จำแนกการเพิ่ม จัดทำเอกสาร และทดสอบผู้บริโภคที่ใช้ validation เข้มงวด

ฟิลด์ GraphQL ควรอยู่ในสถานะ deprecated นานเท่าไร?

กำหนดช่วงเวลาจากรอบการปล่อยไคลเอนต์ ข้อผูกพันการสนับสนุน และความเสี่ยงของผู้บริโภค แอปมือถือที่นำไปใช้ช้าต้องใช้เวลามากกว่าบริการภายในที่ deploy ทุกวัน เผยแพร่กำหนดเวลา ระบุผู้บริโภคสำคัญ และลบฟิลด์หลังจากหลักฐานการย้ายครบถ้วนแล้วเท่านั้น

GraphQL introspection แทนเอกสารได้หรือไม่?

ไม่ได้ Introspection ช่วยให้เครื่องมือค้นพบ schema แต่ไม่ได้แทนที่คำอธิบายที่ชัดเจน ตัวอย่าง หมายเหตุการอนุญาต changelogs และคำแนะนำการย้าย สภาพแวดล้อมภายนอกหรือที่ถูกล็อกดาวน์อาจจำกัด introspection ดังนั้นเอกสารอ้างอิงที่เผยแพร่ต้องอธิบายสัญญาด้วยตัวเอง

คุณทดสอบ GraphQL breaking changes ก่อน production อย่างไร?

รัน schema diff จากนั้นรัน saved representative queries และ mutations กับสภาพแวดล้อม candidate ตรวจสอบ GraphQL errors ข้อมูลที่จำเป็น ชนิด ค่า enum พฤติกรรม null สิทธิ์ และผลลัพธ์ทางธุรกิจ รวม operation ของไคลเอนต์ที่impactสูง ไม่ใช่แค่ smoke test ทั่วไป

การตรวจสอบการตอบกลับจับ GraphQL regression ได้ทั้งหมดหรือไม่?

ไม่ได้ มันจับสัญญาการตอบกลับที่บันทึกไว้ซึ่งคุณเลือกตรวจสอบ มันไม่ได้ระบุผู้บริโภคทุกคน เปรียบเทียบ GraphQL schema ทั้งหมด หรือตรวจจับการเปลี่ยนแปลงพฤติกรรมที่ไม่ได้บันทึกด้วยตัวเอง จับคู่ response validation กับ operation tests, schema review, ownership และกระบวนการ deprecation