สรุปโดยย่อ (TL;DR)
แนวทาง design-first หมายถึงการเขียนข้อกำหนด API ของคุณก่อนโค้ดการนำไปใช้งาน – และข้อกำหนดนี้จะขับเคลื่อนทุกสิ่งตามมา: mock, เอกสาร, การทดสอบ และ client stub การเลือกแพลตฟอร์มที่รองรับเวิร์กโฟลว์นี้แบบครบวงจรจะช่วยขจัดความขัดแย้งที่เกิดขึ้นตลอดเวลาในการรักษาโค้ดและเอกสารให้สอดคล้องกัน บทความนี้จะอธิบายแนวทาง design-first และประเมินว่าเครื่องมือที่ดีควรเป็นอย่างไร โดยมี Apidog เป็นแพลตฟอร์ม design-first ที่สมบูรณ์แบบ
Apidogทดลองใช้ Apidog ฟรี
บทนำ
นักพัฒนาส่วนใหญ่เรียนรู้ที่จะสร้าง API แบบ code-first คุณเขียนเส้นทาง, เพิ่ม annotation, รัน generator และได้เอกสารประกอบ มันทำงานได้ดี จนกระทั่งมันไม่ทำงานอีกต่อไป
เอกสารเริ่มคลาดเคลื่อน Annotation ล้าสมัย วิศวกรใหม่เปลี่ยนรูปแบบการตอบกลับ แต่ลืมอัปเดต decorator หกเดือนต่อมา เอกสารบอกว่า API ส่งคืนอาร์เรย์ของสตริง แต่การตอบกลับจริงส่งคืนอาร์เรย์ของอ็อบเจกต์ที่มีฟิลด์ value
แนวทาง design-first พลิกผันสิ่งนี้ ข้อกำหนด (spec) คือแหล่งความจริง โค้ด, เอกสาร และ mock ทั้งหมดถูกสร้างขึ้นจากมัน เมื่อข้อกำหนดเปลี่ยน ทุกอย่างก็เปลี่ยนไปพร้อมกัน – เพราะทุกอย่างถูกสร้างขึ้นจากมัน
นี่ไม่ใช่ความแตกต่างทางทฤษฎี ทีมที่นำ design-first มาใช้รายงานว่าเกิดความประหลาดใจในการรวมระบบน้อยลง, การพัฒนาส่วนหน้าเร็วขึ้น (เพราะ mock มีให้ใช้งานตั้งแต่วันแรก) และเอกสารที่ถูกต้องแม่นยำเพราะไม่เคยเป็นเพียงสิ่งประดิษฐ์รอง
แต่ design-first ต้องใช้เครื่องมือที่ทำให้การเขียนข้อกำหนดเร็วพอที่จะใช้งานได้จริง หากการกำหนด endpoint ในเครื่องมือข้อกำหนดของคุณใช้เวลา 20 นาที และการเขียน route handler ใช้เวลา 5 นาที จะไม่มีใครใช้เครื่องมือข้อกำหนด แพลตฟอร์มต้องทำให้ design-first เร็วกว่า code-first ไม่ใช่ช้ากว่า
ความหมายของ design-first ในทางปฏิบัติ
Design-first คือเวิร์กโฟลว์ ไม่ใช่เทคโนโลยี นี่คือสิ่งที่ดูเหมือนในแต่ละขั้นตอนของการพัฒนา API:
ก่อนเขียนโค้ดใดๆ
การออกแบบ API ถูกกำหนดเป็น OpenAPI spec ซึ่งรวมถึง:
- เส้นทาง endpoint ทั้งหมดและเมธอด HTTP
- คำจำกัดความของพารามิเตอร์คำขอ (path, query, header)
- สกีมาของเนื้อหาคำขอสำหรับ endpoint ประเภท POST/PUT/PATCH
- สกีมาการตอบกลับสำหรับรหัสสถานะทั้งหมด (200, 400, 401, 422, 500)
- ข้อกำหนดการยืนยันตัวตน
- คำอธิบายฟิลด์และตัวอย่าง
การทบทวนการออกแบบนี้คือจุดที่การตัดสินใจที่สำคัญส่วนใหญ่เกิดขึ้น: การตั้งชื่อ, โครงสร้างข้อมูล, รูปแบบการจัดการข้อผิดพลาด
ระหว่างการพัฒนา
ข้อกำหนด (spec) จะถูกเผยแพร่ไปยัง mock server วิศวกรส่วนหน้าจะสร้างโดยอ้างอิงจาก mock วิศวกรส่วนหลังจะนำไปใช้งานตามข้อกำหนด โดยถือว่าเป็นเอกสารความต้องการของพวกเขา ทั้งสองทีมทำงานคู่ขนานกันโดยไม่ขัดขวางซึ่งกันและกัน
หลังจากการนำไปใช้งาน
การทดสอบอัตโนมัติจะตรวจสอบว่าการนำไปใช้งานจริงตรงกับข้อกำหนดหรือไม่ การเบี่ยงเบนใดๆ จากสัญญาจะทำให้การทดสอบล้มเหลว
เมื่อความต้องการเปลี่ยนแปลง
ข้อกำหนด (spec) จะถูกอัปเดตก่อน ทั้งสองทีมจะทบทวนการเปลี่ยนแปลง Mock จะอัปเดตโดยอัตโนมัติ การทดสอบจะแจ้งเตือนการนำไปใช้งานใดๆ ที่ไม่เป็นไปตามข้อกำหนดที่อัปเดต
แพลตฟอร์ม design-first ต้องการอะไรบ้าง
ไม่ใช่ทุกเครื่องมือ API ที่รองรับเวิร์กโฟลว์ design-first นี่คือสิ่งที่แยกแยะเครื่องมือที่รองรับออกจากเครื่องมือที่ไม่รองรับ
โปรแกรมแก้ไข API แบบภาพ
YAML ดิบเป็นสื่อกลางในการออกแบบที่ไม่ดีนัก โปรแกรมแก้ไขแบบภาพช่วยให้คุณมุ่งเน้นไปที่โครงสร้างและความหมายของ API โดยไม่ต้องกังวลกับการเยื้อง YAML โปรแกรมแก้ไขควรกำเนิด OpenAPI ที่ถูกต้อง, รองรับการนำสกีมากลับมาใช้ใหม่ (components) และตรวจสอบความถูกต้องแบบเรียลไทม์
การตรวจสอบ OpenAPI
ข้อกำหนด (spec) ควรเป็น OpenAPI ที่ถูกต้องก่อนที่จะนำไปใช้ทำสิ่งใดๆ การตรวจสอบความถูกต้องแบบอินไลน์จะตรวจจับข้อผิดพลาดระหว่างการแก้ไข แทนที่จะเป็นช่วงสร้างโค้ดหรือสร้าง mock
การสร้าง mock อัตโนมัติจากข้อกำหนด
เขียนข้อกำหนด (spec) แล้วได้ mock ไม่มีขั้นตอนเพิ่มเติม Mock ควรส่งคืนข้อมูลที่เคารพประเภทฟิลด์, รูปแบบ และข้อจำกัดจากสกีมา นี่คือสิ่งที่ทำให้การพัฒนาแบบขนานเป็นไปได้ในทางปฏิบัติ
การแสดงตัวอย่างเอกสารพร้อมตัวอย่างที่สมจริง
ข้อกำหนด (spec) ควรถ่ายทอดออกมาเป็นเอกสารที่อ่านง่าย ซึ่งคุณสามารถแบ่งปันกับผู้มีส่วนได้ส่วนเสียในระหว่างขั้นตอนการออกแบบ สมาชิกในทีมที่ไม่ใช่สายเทคนิคควรอ่านและให้ข้อเสนอแนะได้
เวิร์กโฟลว์การตรวจสอบของทีม
Design-first ปฏิบัติกับการเปลี่ยนแปลงข้อกำหนด (spec) เหมือนกับการเปลี่ยนแปลงโค้ด: มีคนเสนอการเปลี่ยนแปลง, คนอื่นๆ ตรวจสอบ, และได้รับการอนุมัติหรือแก้ไข แพลตฟอร์มต้องมีการแสดงความคิดเห็นแบบ async และการติดตามการเปลี่ยนแปลง
ส่งออกเป็น OpenAPI มาตรฐาน
ข้อกำหนด (spec) ต้องสามารถพกพาได้ คุณควรจะสามารถส่งออกเป็น OpenAPI มาตรฐาน และใช้งานร่วมกับเครื่องมืออื่นๆ ได้: code generator, API gateway, test framework
Apidog ในฐานะแพลตฟอร์ม design-first
สถาปัตยกรรมของ Apidog สร้างขึ้นโดยมีข้อกำหนด (spec) เป็นหลัก แท็บออกแบบ, mock server, test runner และเอกสารประกอบ ทั้งหมดเชื่อมต่อกับคำจำกัดความ API พื้นฐานเดียวกัน
โปรแกรมแก้ไข OpenAPI แบบภาพ
อินเทอร์เฟซการออกแบบของ Apidog ใช้การแก้ไขแบบฟอร์ม แต่ละ endpoint เป็นฟอร์มที่มีโครงสร้าง: path, method, parameters, request body, responses ฟิลด์ Schema ถูกกำหนดด้วยตัวเลือกประเภท, ตัวแก้ไขคำอธิบาย, กฎการตรวจสอบความถูกต้อง และ mock annotation
คุณไม่จำเป็นต้องเขียน YAML เว้นแต่คุณต้องการ Apidog มีมุมมองดิบที่แสดงการแสดงผล YAML หรือ JSON ของข้อกำหนด และให้คุณแก้ไขได้โดยตรงหากคุณต้องการ การเปลี่ยนแปลงในมุมมองแบบภาพจะซิงค์กับมุมมองดิบและในทางกลับกัน
Schema components เป็นองค์ประกอบหลัก กำหนดสกีมา UserProfile ในส่วน components อ้างอิงด้วย $ref ใน endpoint ใดๆ เปลี่ยนสกีมาเพียงครั้งเดียว แล้วทุก endpoint ที่อ้างอิงถึงก็จะสะท้อนการเปลี่ยนแปลงนั้น
การแสดงตัวอย่างเอกสารแบบเรียลไทม์
เมื่อคุณออกแบบ endpoint มุมมองเอกสารจะอัปเดตแบบเรียลไทม์ คุณสามารถดูตัวอย่างว่า endpoint จะปรากฏในเอกสารที่เผยแพร่อย่างไรโดยไม่ต้องออกจากอินเทอร์เฟซการออกแบบ การแสดงตัวอย่างจะแสดงคำอธิบายที่เรนเดอร์, ตารางสกีมาพร้อมประเภทฟิลด์และข้อจำกัด, และตัวอย่างการตอบกลับ
แชร์ลิงก์เอกสารกับผู้จัดการผลิตภัณฑ์หรือหัวหน้าทีมส่วนหน้าในระหว่างขั้นตอนการออกแบบเพื่อตรวจสอบ พวกเขาไม่จำเป็นต้องติดตั้งอะไรเลย
Smart Mock: จากข้อกำหนดสู่ mock ที่ใช้งานได้จริง
เมื่อคุณบันทึก endpoint ใหม่ใน Apidog’s designer, mock server ก็พร้อมใช้งานทันที URL ของ mock จะปรากฏในอินเทอร์เฟซ Mock จะสร้างข้อมูลการตอบกลับตามสกีมาของคุณ:
- ฟิลด์สตริงที่มี
format: emailจะส่งคืนที่อยู่อีเมลที่ถูกต้อง - ฟิลด์จำนวนเต็มที่มี
minimumและmaximumจะส่งคืนค่าที่อยู่ในช่วง - ฟิลด์ Enum จะส่งคืนค่า enum ที่สุ่มเลือก
- อ็อบเจกต์และอาร์เรย์ที่ซ้อนกันจะปฏิบัติตามโครงสร้างสกีมาที่ซ้อนกัน
- คอมโพเนนต์
$refจะถูกแก้ไขและ mock ได้อย่างถูกต้อง
คุณยังสามารถตั้งค่ากฎ mock แบบกำหนดเองสำหรับสถานการณ์เฉพาะได้: ส่งคืน 404 เมื่อพารามิเตอร์ path เป็น 0 หรือส่งคืน payload ที่เฉพาะเจาะจงสำหรับค่าพารามิเตอร์ query ที่เฉพาะเจาะจง
การตรวจสอบของทีมและการติดตามการเปลี่ยนแปลง
การเปลี่ยนแปลงข้อกำหนด API ใน Apidog สามารถมองเห็นได้โดยสมาชิกในพื้นที่ทำงานทุกคน สามารถเพิ่มความคิดเห็นไปยัง endpoint หรือฟิลด์เฉพาะได้ ประวัติการเปลี่ยนแปลงจะติดตามว่าใครเปลี่ยนอะไรและเมื่อไหร่
สำหรับเวิร์กโฟลว์ design-first นี่หมายความว่าการเปลี่ยนแปลงข้อกำหนด (spec) จะผ่านวัฒนธรรมการตรวจสอบแบบเดียวกับการเปลี่ยนแปลงโค้ด โดยไม่จำเป็นต้องใช้เครื่องมือหรือกระบวนการแยกต่างหาก
Design-first เทียบกับ Code-first: ข้อแลกเปลี่ยนที่แท้จริง
Design-first ไม่ได้เหนือกว่าโดยสมบูรณ์ นี่คือการเปรียบเทียบที่ตรงไปตรงมา
ข้อดีของ Design-first:
- ส่วนหน้าและส่วนหลังสามารถทำงานแบบคู่ขนานได้ (ประโยชน์ด้านความเร็วที่สำคัญ)
- เอกสารมีความถูกต้องแม่นยำเพราะเป็นแหล่งที่มา ไม่ใช่สิ่งที่ได้มา
- ปัญหาการรวมระบบจะปรากฏขึ้นแต่เนิ่นๆ ในระหว่างการตรวจสอบการออกแบบ ไม่ใช่ในภายหลังในระหว่างการรวมระบบ
- สัญญา API มีความชัดเจนและตรวจสอบได้
- การเปลี่ยนแปลง API จะผ่านกระบวนการตรวจสอบโดยค่าเริ่มต้น
ข้อเสียของ Design-first:
- ต้องใช้เวลาในการกำหนดข้อกำหนดก่อนที่จะเขียนโค้ด
- เครื่องมือสำหรับข้อกำหนดมีช่วงการเรียนรู้
- ต้องมีวินัยในการรักษาการนำไปใช้งานให้สอดคล้องกับข้อกำหนด
- การกำหนดข้อกำหนดมากเกินไปตั้งแต่แรกอาจทำให้คุณติดอยู่กับการตัดสินใจก่อนที่จะเข้าใจโดเมนอย่างถ่องแท้
ข้อดีของ Code-first:
- การพัฒนาเริ่มต้นที่เร็วขึ้นสำหรับโปรเจกต์ขนาดเล็กและเชิงทดลอง
- กระบวนการน้อยลงสำหรับนักพัฒนาเดี่ยวที่ทำงานซ้ำอย่างรวดเร็ว
- ไม่มีเครื่องมือข้อกำหนดให้เรียนรู้
ข้อเสียของ Code-first:
- เอกสารมักจะเป็นสิ่งประดิษฐ์รองและมีแนวโน้มที่จะคลาดเคลื่อน
- ส่วนหน้าต้องรอส่วนหลังก่อนจึงจะเริ่มงานรวมระบบได้
- สัญญาเป็นแบบนัย ทำให้การเปลี่ยนแปลงที่กระทบต่อระบบตรวจจับได้ยากขึ้น
- การปรับโครงสร้าง API ใหม่ต้องมีการอัปเดตเอกสารด้วยตนเอง
สำหรับทีมที่มีวิศวกรมากกว่าหนึ่งคนทำงานเกี่ยวกับ API โดยทั่วไปแล้ว design-first จะให้ผลลัพธ์ที่ดีกว่า วินัยของ spec-first จะให้ผลตอบแทนมากที่สุดในฟีเจอร์ที่ต้องมีการประสานงานระหว่างส่วนหน้าและส่วนหลังเป็นอย่างมาก
เครื่องมือที่รองรับเวิร์กโฟลว์ design-first
Apidog
แพลตฟอร์ม design-first ที่สมบูรณ์แบบ: โปรแกรมแก้ไขแบบภาพ, การสร้าง mock ทันที, เอกสาร, การทดสอบ และการตรวจสอบของทีมในเครื่องมือเดียว รุ่นฟรีครอบคลุมคุณสมบัติครบถ้วน การสร้าง mock ที่ทรงพลังเป็นจุดเด่นที่แท้จริง
Stoplight Studio
โปรแกรมแก้ไข OpenAPI ที่ดีที่สุดพร้อม Spectral linting สำหรับการบังคับใช้สไตล์ ไม่มี mock server หรือ test runner ในตัว เหมาะสำหรับองค์กรที่ต้องการเครื่องมือกำกับดูแล มีราคาแพงสำหรับทีมขนาดเล็ก
SwaggerHub
แพลตฟอร์มการแก้ไขและการทำงานร่วมกันของ OpenAPI ที่เติบโตเต็มที่ ใช้กันอย่างแพร่หลายในองค์กร มีความสามารถในการ mock ที่จำกัด ไม่มีการทดสอบ เหมาะสำหรับองค์กรที่เน้นข้อกำหนดซึ่งอยู่ในระบบนิเวศ Swagger อยู่แล้ว
Postman (พร้อม API Builder)
Postman มีแท็บออกแบบ API ที่สร้าง OpenAPI specs แต่เวิร์กโฟลว์การออกแบบและการจัดการ Collection รู้สึกไม่เชื่อมโยงกัน Mock server ต้องตั้งค่าด้วยตนเองจาก Collection แทนที่จะสร้างอัตโนมัติจาก spec เหมาะสำหรับทีมที่ใช้ code-first ที่ต้องการเครื่องมือสร้างเอกสารบางอย่าง
Insomnia (พร้อมโหมดเอกสาร)
Insomnia รองรับการแก้ไข OpenAPI spec และมี mock พื้นฐาน ไม่สมบูรณ์เท่าเครื่องมือ design-first โดยเฉพาะ เหมาะสำหรับนักพัฒนาเดี่ยวที่ต้องการตัวเลือกที่ใช้งานง่าย
การตั้งค่าเวิร์กโฟลว์ design-first ใน Apidog
ขั้นตอนที่ 1: เริ่มต้นด้วยข้อกำหนด ไม่ใช่ Collectionสร้างโปรเจกต์ใหม่และเปิดแท็บออกแบบ ต้านทานความอยากที่จะเริ่มใน request builder กำหนดอย่างน้อย path ของ endpoint, method และ response schema ก่อนที่คุณจะส่งคำขอแม้แต่ครั้งเดียว
ขั้นตอนที่ 2: กำหนด Shared Component ก่อนก่อนเพิ่ม endpoint ให้กำหนดสกีมาที่จะนำกลับมาใช้ใหม่: รูปแบบการตอบกลับข้อผิดพลาด, pagination wrapper, ฟิลด์ entity ทั่วไป สิ่งนี้ช่วยป้องกันความไม่สอดคล้องกันในภายหลัง
ขั้นตอนที่ 3: รับ URL ของ mock แต่เนิ่นๆคัดลอก URL ของ mock ทันทีที่บันทึก endpoint แชร์ให้กับวิศวกรส่วนหน้า พวกเขาสามารถเริ่มสร้างโดยอ้างอิงจากมันได้ทันที
ขั้นตอนที่ 4: ตรวจสอบเอกสารก่อนเขียนโค้ดดูตัวอย่างเอกสารที่สร้างขึ้น หากคำอธิบายฟิลด์ไม่ชัดเจนในเอกสาร มันก็จะไม่ชัดเจนสำหรับทุกคนที่อ่านโค้ด แก้ไขในข้อกำหนด
ขั้นตอนที่ 5: ล็อกข้อกำหนดก่อนเริ่มนำไปใช้งานเมื่อการตรวจสอบการออกแบบเสร็จสิ้นและแก้ไขความคิดเห็นแล้ว ให้ถือว่าข้อกำหนดนั้นถูกล็อกสำหรับสปรินต์นั้น การเปลี่ยนแปลงการนำไปใช้งานที่ต้องมีการอัปเดตข้อกำหนดควรผ่านกระบวนการตรวจสอบ ไม่ใช่ทำอย่างเงียบๆ
ขั้นตอนที่ 6: รันการทดสอบการตรวจสอบ Schema ใน CIตั้งค่าชุดทดสอบของ Apidog เพื่อตรวจสอบ response schemas ในทุกการรัน CI นี่คือมาตรการป้องกันอัตโนมัติที่ช่วยให้การนำไปใช้งานและข้อกำหนดสอดคล้องกัน
คำถามที่พบบ่อย
Design-first ใช้ได้กับ REST API เท่านั้นหรือไม่?ไม่ หลักการ design-first ใช้ได้กับโปรโตคอลใดๆ ที่คุณสามารถกำหนดสัญญาได้: GraphQL แบบ schema-first, gRPC ด้วย protobuf, AsyncAPI สำหรับระบบที่ขับเคลื่อนด้วยเหตุการณ์ Apidog รองรับการออกแบบ REST และ GraphQL สำหรับ gRPC ไฟล์ proto มีวัตถุประสงค์แบบ contract-first เช่นเดียวกัน
เราจำเป็นต้องกำหนดทุก endpoint ก่อนเริ่มพัฒนาหรือไม่?ไม่ คุณสามารถนำ design-first มาใช้ในระดับฟีเจอร์ได้: กำหนดข้อกำหนดสำหรับฟีเจอร์ที่คุณกำลังจะสร้างก่อนเขียนโค้ด แม้ว่าส่วนอื่นๆ ของโค้ดเบสจะเป็นแบบ code-first ก็ตาม การนำไปใช้แบบค่อยเป็นค่อยไปได้ผลดี
Design-first ทำงานร่วมกับ agile sprints อย่างไร?การประชุมออกแบบในช่วงเริ่มต้นสปรินต์จะกำหนดสัญญา API สำหรับฟีเจอร์ของสปรินต์นั้น ส่วนหน้าและส่วนหลังทำงานแบบคู่ขนานกันในระหว่างสปรินต์ การตรวจสอบข้อกำหนดจะกลายเป็นส่วนหนึ่งของการวางแผนสปรินต์
จะเกิดอะไรขึ้นหากการนำไปใช้งานต้องเบี่ยงเบนจากข้อกำหนดเดิม?มันเกิดขึ้นได้ กระบวนการที่ถูกต้องคือการอัปเดตข้อกำหนดก่อน, ได้รับความเห็นชอบจากผู้มีส่วนได้ส่วนเสีย (โดยเฉพาะส่วนหน้า), จากนั้นจึงอัปเดตการนำไปใช้งาน สิ่งนี้ทำให้ข้อกำหนดเป็นแหล่งความจริงแทนที่จะเป็นการนำไปใช้งาน
เราสามารถสร้าง server stub จากการส่งออก OpenAPI ของ Apidog ได้หรือไม่?ได้ คุณสามารถส่งออกข้อกำหนดจาก Apidog เป็น OpenAPI 3.x จากนั้นใช้ code generator มาตรฐานใดๆ เพื่อสร้าง server stub openapi-generator รองรับภาษาและเฟรมเวิร์กเซิร์ฟเวอร์กว่า 50 รายการ
เราจัดการการกำหนดเวอร์ชันของข้อกำหนดอย่างไร?Apidog รักษาประวัติการเปลี่ยนแปลงภายในโปรเจกต์ สำหรับการเปลี่ยนแปลงเวอร์ชันหลักที่ยังคงใช้งานคู่ขนานกัน (v1 และ v2 ทั้งคู่ยังคงใช้งานได้) การแยกโปรเจกต์หรือ branches จะทำงานได้ดี
Design-first ต้องมีการลงทุนเล็กน้อยในวินัยล่วงหน้า และให้ผลตอบแทนอย่างมีนัยสำคัญในการลดค่าใช้จ่ายในการรวมระบบ แพลตฟอร์มที่คุณเลือกควรกำหนดให้การลงทุนล่วงหน้านั้นต่ำที่สุดเท่าที่จะทำได้ หากการเขียนข้อกำหนดเป็นเรื่องยาก ทีมก็จะละทิ้งมัน โปรแกรมแก้ไขแบบภาพ, การสร้าง mock ทันที และการแสดงตัวอย่างเอกสารของ Apidog ทำให้ design-first เป็นเส้นทางที่ง่ายที่สุดแทนที่จะเป็นเส้นทางที่ต้องอาศัยคุณธรรมมากที่สุด