Bruno Request First Design First Tool

Bruno เป็นแบบ request-first ใช่หรือไม่? ใช่ Bruno ถูกสร้างขึ้นมาเพื่อการสร้าง จัดระเบียบ และส่งคำขอ HTTP คุณสร้างคอลเลกชัน เพิ่มคำขอ เขียนคำขอเหล่านั้นลงในไฟล์ .bru ของมัน รันมัน และจัดการเวอร์ชันทั้งหมดใน Git โมเดลนี้รวดเร็ว เป็นมิตรกับ Git และเป็นความสุขอย่างแท้จริงเมื่อคุณสำรวจ API ที่มีอยู่แล้ว

แต่ “request-first” และ “design-first” ตอบคำถามที่แตกต่างกัน Request-first ถามว่า: ฉันจะเรียกใช้ endpoint นี้ได้อย่างไร? Design-first ถามว่า: endpoint นี้ควรเป็นอย่างไร ก่อนที่ใครจะเขียนโค้ดเพื่อให้บริการมัน? ช่องว่างระหว่างสองคำถามนี้คือจุดที่ทีมที่กำลังสร้าง API ใหม่หรือ API ที่ใช้ร่วมกันเริ่มประสบปัญหา บทความนี้จะอธิบายข้อดีข้อเสียระหว่าง Bruno แบบ request-first กับ design-first อย่างตรงไปตรงมา จากนั้นจะแสดงให้เห็นว่าเวิร์กโฟลว์แบบ design-first ที่เป็น OpenAPI-native มีความสำคัญอย่างไร

Request-first เทียบกับ Design-first แบบรวดเร็ว

ทั้งสองแนวทางไม่ใช่คู่แข่งกันมากเท่ากับจุดเริ่มต้นที่แตกต่างกัน นี่คือฉบับย่อ

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

โมเดล request-first ของ Bruno

Bruno ทำงานได้ดี และควรระบุให้ชัดเจนว่างานนั้นคืออะไร มันจัดเก็บคำขอในรูปแบบไฟล์ .bru ข้อความธรรมดาในโฟลเดอร์ที่คุณเป็นเจ้าของ ไม่มีบัญชีคลาวด์ภาคบังคับ ไม่มีการซิงค์ที่เป็นกรรมสิทธิ์ ไม่มีการส่งข้อมูลทางไกลเบื้องหลังที่คุณต้องเลือกไม่ใช้ สำหรับนักพัฒนาที่ต้องการให้ไคลเอนต์ API ของพวกเขาทำงานเหมือนส่วนอื่นๆ ของ codebase ของพวกเขา นี่คือข้อได้เปรียบที่แท้จริง และเป็นหัวใจของ เวิร์กโฟลว์ API ที่เป็นแบบ Git-native ที่หลายทีมนำมาใช้

จุดที่ Bruno โดดเด่น:

• สำรวจ API ที่มีอยู่ ชี้ไปยังบริการที่กำลังทำงาน ส่งคำขอ ตรวจสอบการตอบกลับ ทำซ้ำ วงจรการตอบสนองนั้นกระชับ
• เป็นแบบ local-first และเป็นมิตรกับ Git ส่วนต่างสามารถอ่านได้ การผสานรวมทำได้ดี และประวัติคำขอของคุณอยู่ใน PR เดียวกันกับโค้ดของคุณ
• การเขียนสคริปต์และการทดสอบ สคริปต์ก่อนและหลังคำขอ การยืนยัน (assertions) และตัวแปรสภาพแวดล้อมครอบคลุมการทดสอบประจำวันที่วิศวกรส่วนใหญ่ต้องการ
• ไม่มีการผูกขาด รูปแบบเปิดและไฟล์เป็นของคุณ

หากงานของคุณคือการ บริโภค และ ตรวจสอบ API ที่มีอยู่แล้ว request-first มักจะเป็นเส้นทางที่ตรงที่สุด เราเคยกล่าวถึงเรื่องนี้มาก่อนแล้วเมื่อเปรียบเทียบกับแพลตฟอร์มที่กว้างกว่าใน การวิเคราะห์ทางเลือกของ Bruno นี้

ต้นทุนของการไม่มีชั้นการออกแบบหรือสัญญา

ข้อเสียจะปรากฏขึ้นเมื่อ API ยังไม่มีอยู่ หรือเมื่อมีมากกว่าหนึ่งทีมต้องเห็นพ้องต้องกันว่า API นั้นควรมีหน้าตาเป็นอย่างไร

ไม่มีเครื่องมือออกแบบด้วยภาพ เครื่องมือแบบ request-first แสดง endpoint ในรูปแบบคำขอ ไม่ใช่ในรูปแบบของโมเดลทรัพยากร สคีมา และการตอบกลับ ไม่มีพื้นที่ที่วิศวกรผลิตภัณฑ์ หัวหน้าทีมแบ็กเอนด์ และนักพัฒนาฟรอนต์เอนด์สามารถดูรูปร่างทรัพยากรเดียวกันและตกลงกันได้ก่อนที่ใครจะเขียนตัวจัดการ การออกแบบในรูปแบบคำขอหมายถึงการออกแบบในรูปแบบตัวอย่าง และตัวอย่างไม่ได้บังคับใช้โครงสร้าง

ความคลาดเคลื่อนของสัญญา เมื่อคอลเลกชัน เป็น แหล่งข้อมูลหลัก มันจะสะท้อนเฉพาะสิ่งที่เคยถูกเรียกใช้แล้วเท่านั้น API จริงอาจเปลี่ยนแปลง เพิ่มฟิลด์ เลิกใช้พารามิเตอร์ กระชับการตรวจสอบความถูกต้อง และคอลเลกชันก็จะค่อยๆ ล้าหลังไปเรื่อยๆ จนกว่าการทดสอบจะล้มเหลว เวิร์กโฟลว์ที่เน้น spec จะกลับแนวคิดนี้: สัญญาคือข้อมูลอ้างอิง และการนำไปใช้จะถูกตรวจสอบกับมัน

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

ทั้งหมดนี้ไม่ได้ทำให้ Bruno เป็นเครื่องมือที่แย่ มันแค่ทำให้ Bruno เป็นเครื่องมือแบบ request-first ที่ถูกใช้ในงานที่ไม่ใช่จุดประสงค์หลักของ request-first

เมื่อ design-first ได้เปรียบ

Design-first ได้ผลลัพธ์ที่ดีในสามสถานการณ์เป็นพิเศษ:

• API ใหม่หมดจด (Greenfield APIs) เมื่อยังไม่มีอะไรอยู่ Spec คือ การออกแบบ คุณกำหนดทรัพยากร สคีมา และรูปร่างของข้อผิดพลาดเพียงครั้งเดียว จากนั้นสร้าง server stub, mock และเอกสารจากสัญญาเดียว แทนที่จะต้องย้อนรอยสร้างจากคำขอในภายหลัง
• สัญญาสำหรับหลายทีม เมื่อทีมแบ็กเอนด์และทีมไคลเอนต์ตั้งแต่หนึ่งทีมขึ้นไปต้องตกลงกัน OpenAPI spec คือข้อตกลง ทีมฟรอนต์เอนด์สามารถสร้างโดยอ้างอิงจาก mock ได้ทันทีที่สัญญาได้รับการอนุมัติ ควบคู่ไปกับการนำแบ็กเอนด์ไปใช้ แทนที่จะต้องรอ endpoint จริง
• API สาธารณะ เมื่อนักพัฒนาภายนอกต้องพึ่งพาคุณ ความเสถียรและเอกสารที่ชัดเจนคือผลิตภัณฑ์ สัญญาที่ดูแลรักษาอย่างดีจะให้เอกสารอ้างอิงที่สร้างขึ้น, วินัยในการจัดการเวอร์ชัน และวิธีสื่อสารการเปลี่ยนแปลงที่ส่งผลกระทบได้อย่างรอบคอบ

ประเด็นร่วมกันคือ: design-first ได้เปรียบเมื่อ API เป็นอินเทอร์เฟซที่ใช้ร่วมกันซึ่งต้องการข้อตกลง ก่อน การเขียนโค้ด ไม่ใช่แค่บริการที่คุณทดลองใช้ หลังจาก ที่มันถูกเผยแพร่ไปแล้ว

Apidog design-first พร้อมโหมด Spec-First

Apidog ถูกสร้างขึ้นโดยใช้แนวคิด design-first และประเด็นสำคัญในที่นี้คือคุณไม่จำเป็นต้องสละประสบการณ์ที่เป็นมิตรกับ Git และเป็นแบบ OpenAPI-native เพื่อให้ได้มันมา

คุณสามารถทำงานได้สองวิธีกับโปรเจกต์เดียวกัน เครื่องมือออกแบบด้วยภาพสำหรับการกำหนด endpoint, สคีมาคำขอและการตอบกลับ, และคอมโพเนนต์ที่นำกลับมาใช้ใหม่ได้โดยไม่ต้องเขียน YAML ด้วยมือ ซึ่งเป็นสิ่งที่คนส่วนใหญ่นึกภาพเมื่อได้ยินคำว่า “design-first” และยังมีโหมด Spec-First ซึ่งเป็นตัวแก้ไขโค้ดที่คุณสามารถสร้างเอกสาร OpenAPI ได้โดยตรง โดยมี spec เป็นแหล่งข้อมูลหลักอย่างแท้จริง ทั้งสองจะซิงค์กัน ทำให้วิศวกรแบ็กเอนด์สามารถทำงานในรูปแบบ OpenAPI ดิบๆ ขณะที่วิศวกรผลิตภัณฑ์ทำงานบนพื้นที่ออกแบบ และพวกเขากำลังแก้ไขสัญญาเดียวกัน

โหมด Spec-First ยังรองรับการซิงค์ Git แบบสองทาง: spec จะอยู่ใน repository ของคุณในรูปแบบไฟล์จริง การเปลี่ยนแปลงจะไหลไปในทั้งสองทิศทาง และการออกแบบ API ของคุณจะผ่าน pull request และการตรวจสอบแบบเดียวกับโค้ดของคุณ นั่นคือคุณสมบัติ Git-native ที่ผู้ใช้ Bruno ให้ความสำคัญ ซึ่งนำมาประยุกต์ใช้กับ สัญญา แทนที่จะเป็นคอลเลกชันของคำขอ กลไกทั้งหมดอยู่ใน เอกสารประกอบโหมด Spec-First

ผลลัพธ์ที่ได้คือเวิร์กโฟลว์เดียวที่ครอบคลุมทั้งสองคำถาม นั่นคือการออกแบบสัญญาตั้งแต่แรกเมื่อจำเป็น และยังคงทดสอบกับมันเหมือนไคลเอนต์แบบ request-first เมื่อ endpoint พร้อมใช้งาน สำหรับข้อมูลเชิงลึกเพิ่มเติมว่าโมเดลเหล่านี้มาบรรจบกันอย่างไร โปรดดู spec-first เทียบกับ design-first ใน Apidog

การเลือกตามวุฒิภาวะของทีม

วิธีง่ายๆ ในการตัดสินใจ: เลือกเครื่องมือให้เหมาะสมกับสถานะของ API ของคุณ ไม่ใช่ตามความชอบส่วนตัว

• ทีมเดี่ยวหรือทีมขนาดเล็ก ส่วนใหญ่บริโภค API Request-first ก็เพียงพอแล้ว โมเดล local-first ของ Bruno จะไม่ขัดขวางการทำงานของคุณ และคุณไม่ต้องแบกรับภาระในการดูแลรักษาสัญญาที่เป็นทางการที่คุณไม่ต้องการ
• ทีมที่กำลังเติบโตซึ่งส่งมอบ API ของตัวเอง นี่คือจุดเปลี่ยน เมื่อทีมที่สองเริ่มพึ่งพา endpoint ของคุณ คอลเลกชันที่ไม่เป็นทางการก็จะหยุดขยายตัว และสัญญาที่ชัดเจนจะเริ่มช่วยประหยัดเวลาในการตรวจสอบและลดข้อผิดพลาดในการรวมระบบ
• องค์กรที่มีวุฒิภาวะซึ่งมี API สาธารณะหรือ API ภายในจำนวนมาก Design-first ถือว่าจำเป็นอย่างยิ่ง Spec จะกลายเป็นการกำกับดูแล เอกสารประกอบ และการเริ่มใช้งานทั้งหมดในคราวเดียว และเครื่องมือที่เป็น OpenAPI-native พร้อมการซิงค์ Git จะช่วยให้ทุกอย่างเป็นไปอย่างถูกต้อง

การวิเคราะห์อย่างตรงไปตรงมาเกี่ยวกับ Bruno request-first เทียบกับ design-first คือวุฒิภาวะ ไม่ใช่ความชอบ ที่มักจะเป็นตัวตัดสิน ทีมมักจะเริ่มต้นด้วย request-first และพัฒนาไปสู่ design-first เมื่อ API ของพวกเขากลายเป็นสัญญาที่ผู้อื่นต้องพึ่งพา

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

Bruno เป็นแบบ request-first หรือ design-first?

Bruno เป็นแบบ request-first โมเดลหลักคือการสร้าง จัดระเบียบ และส่งคำขอที่จัดเก็บในรูปแบบไฟล์ข้อความธรรมดา ซึ่งเหมาะสำหรับการสำรวจและทดสอบ API ที่มีอยู่แล้ว ไม่ได้มุ่งเน้นที่การสร้างสัญญา OpenAPI ก่อนที่จะสร้าง API

ฉันสามารถทำงานแบบ design-first ใน Bruno ได้หรือไม่?

ไม่ได้โดยธรรมชาติในแบบที่เครื่องมือที่เน้น spec ทำ Bruno มุ่งเน้นที่คำขอมากกว่าที่จะเป็นเครื่องมือออกแบบด้วยภาพหรือเอกสาร OpenAPI เป็นแหล่งข้อมูลหลัก หากคุณต้องการกำหนดและตรวจสอบสัญญาก่อนการเขียนโค้ด เครื่องมือที่เป็น design-first และ OpenAPI-native จะเหมาะสมกับงานนั้นมากกว่า

ฉันต้องละทิ้งความเป็นมิตรกับ Git เพื่อใช้แนวคิด design-first หรือไม่?

ไม่ คุณสมบัติ Git-native, ไฟล์ข้อความธรรมดาใน repo ของคุณ, diffs ที่อ่านได้, การตรวจสอบผ่าน PRs, สามารถนำไปใช้กับ spec ได้เอง โหมด Spec-First ของ Apidog จะเก็บเอกสาร OpenAPI ไว้ใน repository ของคุณพร้อมการซิงค์แบบสองทาง ดังนั้น design-first ไม่ได้หมายความว่าต้องทิ้ง Git ไว้ข้างหลัง