C# Academy · บทเรียน

กลยุทธ์การกำหนดเวอร์ชัน API

กำหนดเวอร์ชันผ่าน URL ส่วนหัว และสตริงคำค้น

กลยุทธ์การกำหนดเวอร์ชัน API เป็นบทเรียน C# Academy ฟรีบน CoddyKit นี่คือบทเรียนที่ 1 จากทั้งหมด 4 บทเรียน คุณสามารถอ่านบทเรียนทั้งหมดด้านล่างฟรี — จากนั้นลองปฏิบัติด้วยตัวคุณเองในเบราว์เซอร์พร้อมตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 24/7 บทเรียนนี้เป็นส่วนหนึ่งของเส้นทางการเรียน C# Academy และความก้าวหน้าของคุณจะซิงค์ข้ามเว็บและแอป CoddyKit คอร์ส C# Academy มีบทเรียนทั้งหมด 4 บทเรียน

เหตุใดจึงต้องทำเวอร์ชันให้ API

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

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

การทำเวอร์ชันในเส้นทางที่อยู่

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

GET /api/v1/products
GET /api/v2/products

การทำเวอร์ชันด้วยพารามิเตอร์คำค้น

เวอร์ชันจะส่งไปเป็นพารามิเตอร์คำค้น ที่อยู่ยังคงเดิม และหากไม่มีพารามิเตอร์ ก็สามารถใช้เวอร์ชันล่าสุดหรือเวอร์ชันที่กำหนดตายตัวเป็นค่าเริ่มต้นได้

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

การทำเวอร์ชันด้วยส่วนหัว

ส่วนหัวคำขอแบบกำหนดเองจะเก็บเวอร์ชันไว้ ทำให้ที่อยู่ดูสะอาดเรียบร้อย ข้อเสียคือจะไม่ปรากฏในแถบที่อยู่ของเบราว์เซอร์ และทดสอบด้วยตนเองได้ยากกว่า

GET /api/products
X-Api-Version: 2.0

การทำเวอร์ชันด้วยชนิดสื่อ

เรียกอีกอย่างว่าการเจรจาเนื้อหา เวอร์ชันจะฝังอยู่ในชนิดสื่อของส่วนหัว Accept วิธีนี้สอดคล้องกับหลักสถาปัตยกรรมเว็บมากที่สุด แต่ค้นพบได้ยากที่สุด

GET /api/products
Accept: application/json;v=2.0

การเปรียบเทียบกลยุทธ์

แต่ละกลยุทธ์แลกความง่ายในการค้นพบกับความเรียบร้อยของที่อยู่:

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

// Many teams pick URL path for public APIs

การทำเวอร์ชันเชิงความหมายของ API

เวอร์ชันของ API มักใช้เวอร์ชันหลักเท่านั้น (v1, v2) ควรสงวนเวอร์ชันย่อยไว้สำหรับการเปลี่ยนแปลงที่เพิ่มความสามารถและไม่ทำให้เข้ากันไม่ได้ ซึ่งไคลเอ็นต์เก่าสามารถเพิกเฉยได้

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

การเลิกใช้งาน

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

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

เวอร์ชันเริ่มต้น

กำหนดว่าจะเกิดอะไรขึ้นเมื่อไคลเอ็นต์ไม่ส่งเวอร์ชันมา ตัวเลือกที่พบบ่อยคือ ถือว่าเป็นเวอร์ชันล่าสุด ถือว่าเป็น v1 หรือปฏิเสธคำขอ การระบุให้ชัดเจนช่วยหลีกเลี่ยงความประหลาดใจ

// Strategy: unversioned request -> treat as v1.0

การทำเวอร์ชันให้ถูกส่วน

ทำเวอร์ชันให้กับสัญญาการใช้งาน (เส้นทาง รูปแบบคำขอ/การตอบกลับ) ไม่ใช่รายละเอียดการทำงานภายใน ปลายทาง v2 สามารถใช้ตรรกะทางธุรกิจส่วนใหญ่ร่วมกับ v1 ได้

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

การผสมกลยุทธ์

ไลบรารีการทำเวอร์ชันของ ASP.NET Core สามารถอ่านเวอร์ชันจากหลายแหล่งพร้อมกัน ทำให้ไคลเอ็นต์เลือกวิธีที่สะดวกได้ คุณจะกำหนดค่าส่วนนี้ในหัวข้อถัดไป

// Accept version from URL OR header OR query

ตรวจสอบความเข้าใจ

ตรวจสอบความเข้าใจเกี่ยวกับกลยุทธ์การทำเวอร์ชัน

สรุปทบทวน

คุณได้สำรวจกลยุทธ์การทำเวอร์ชันของ API:

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

ถัดไป: การกำหนดค่า Asp.Versioning ใน ASP.NET Core

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

บทเรียน “กลยุทธ์การกำหนดเวอร์ชัน API” ฟรีหรือไม่

ใช่ — ข้อความเต็มของ “กลยุทธ์การกำหนดเวอร์ชัน API” ฟรีให้อ่านที่นี่บนเว็บ เพื่อปฏิบัติแบบโต้ตอบ (ตัวแก้ไขโค้ดในตัวและติวเตอร์ AI ตลอด 24/7) และปลดล็อคส่วนที่เหลือของคอร์ส C# Academy ให้อัปเกรดเป็น CoddyKit PRO คอร์ส C# Academy มีบทเรียนทั้งหมด 4 บทเรียน

คุณจะเรียนรู้อะไรในบทเรียน “กลยุทธ์การกำหนดเวอร์ชัน API”

กำหนดเวอร์ชันผ่าน URL ส่วนหัว และสตริงคำค้น คุณปฏิบัติ C# Academy ด้วยโค้ดที่ใช้งานได้จริงที่คุณเรียกใช้โดยตรงในเบราว์เซอร์ และติวเตอร์ AI ตลอด 24/7 ตอบคำถามของคุณขณะที่คุณไปผ่านบทเรียน

คุณต้องมีประสบการณ์ก่อนที่จะเริ่มเรียน C# Academy หรือไม่

ไม่จำเป็นต้องมีประสบการณ์มาก่อน C# Academy บน CoddyKit ออกแบบมาสำหรับผู้เริ่มต้นไปจนถึงผู้เรียนขั้นสูง คุณสามารถเริ่มต้นที่นี่หรือเริ่มจากตัวแรกและเรียนด้วยความเร็วของคุณเอง นี่คือบทเรียนที่ 1 จากทั้งหมด 4 บทเรียน

บทเรียน “กลยุทธ์การกำหนดเวอร์ชัน API” ใช้เวลานานแค่ไหน

บทเรียน CoddyKit ส่วนใหญ่ใช้เวลาประมาณ 5–10 นาที แต่ละบทเรียนจึงสั้นและเป็นแบบโต้ตอบ คุณสามารถก้าวหน้าอย่างต่อเนื่องและกลับมาเรียนต่อจากตรงที่เพิ่งหยุดบนเว็บและแอปได้เลย

ฉันเขียนและรันโค้ดในบทเรียน C# Academy นี้ได้ไหม

ได้ บทเรียน C# Academy ทุกบทมีตัวแก้ไขโค้ดในตัว คุณจึงเขียนและรันโค้ดจริงได้เลยในเบราว์เซอร์ และได้รับข้อเสนอแนะจาก AI ในทันที — ไม่ต้องติดตั้งในเครื่องของคุณ

บทเรียนทั้งหมดในหลักสูตรนี้

← กลับไปที่ C# Academy