บรูโน่สำหรับทีม: ทางเลือกและวิธีแก้ปัญหาการซิงค์คลาวด์

สรุป

Bruno ไม่มีระบบซิงค์ข้อมูลบนคลาวด์ในตัว ทีมต่างๆ แก้ปัญหาด้วยการใช้ Git repository, ไดรฟ์เครือข่ายที่ใช้ร่วมกัน หรือ Dev container แต่ละวิธีแก้ปัญหาก็มีข้อจำกัดที่แท้จริง Apidog เข้ามาเติมเต็มช่องว่างนี้จากทั้งสองด้าน: โหมด Spec-First Git ใหม่ของ Apidog ช่วยให้ OpenAPI spec อยู่ใน repository ของคุณและเคลื่อนผ่าน Pull Request ได้เช่นเดียวกับ Bruno ในขณะที่การซิงค์บนคลาวด์ที่เป็นตัวเลือกจะเพิ่มการทำงานร่วมกันแบบเรียลไทม์, การเข้าถึงตามบทบาท, ข้อมูลประจำตัวแบบรวมศูนย์ และ Mock server ในตัว คุณไม่จำเป็นต้องเลือกระหว่าง Git หรือ พื้นที่ทำงานของทีมอีกต่อไป

บทนำ

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

แต่ “การทำงานเฉพาะในเครื่อง” สร้างปัญหาในการประสานงานทันทีที่มีคนที่สองต้องการ Collection เดียวกัน ทีมพัฒนาห้าคนจะแชร์ API Collection ได้อย่างไร? วิศวกร QA จะได้รับคำขอล่าสุดได้อย่างไร? พนักงานใหม่จะตั้งค่าสภาพแวดล้อมได้อย่างไรโดยไม่ต้องคัดลอกไฟล์ผ่าน Slack?

คู่มือนี้จะอธิบายถึงทุกวิธีแก้ปัญหาที่ทีมใช้ ค่าใช้จ่ายที่แท้จริงของแต่ละวิธี และขีดจำกัดของมัน นอกจากนี้ยังครอบคลุมสิ่งใหม่: โหมด Spec-First Git ของ Apidog ซึ่งช่วยให้คุณรักษาวิธีคิดแบบ "ไฟล์ใน Repo" ของ Bruno ไว้ได้ และยังได้รับการทำงานร่วมกันแบบเรียลไทม์ที่ Git เพียงอย่างเดียวไม่สามารถให้คุณได้ หากคุณต้องการภาพรวมที่กว้างขึ้นก่อน รายการ เครื่องมือ API ที่ทำงานร่วมกับ Git ของเราจะให้บริบทที่เกี่ยวข้อง

แนวทาง Git (เส้นทางที่ตั้งใจไว้)

Bruno ถูกออกแบบโดยใช้ Git เป็นหลัก Collection เป็นไฟล์ .bru, สภาพแวดล้อมเป็นไฟล์ JSON, ทุกอย่างเป็นข้อความธรรมดา กลไกการแชร์ที่ตั้งใจไว้คือ Git repository

วิธีการทำงาน:

1. สร้าง Git repository สำหรับ API collection ของคุณ (หรือใช้โฟลเดอร์ภายใน Repo ที่มีอยู่แล้วของคุณ)
2. พุช Collection ไปยัง GitHub, GitLab หรือ Bitbucket
3. สมาชิกในทีมโคลน Repo และเปิดโฟลเดอร์ใน Bruno
4. การเปลี่ยนแปลงถูกคอมมิตและพุช; คนอื่น ๆ ดึงข้อมูล

ข้อดี:

• ประวัติเวอร์ชันที่สมบูรณ์ในทุกคำขอ
• การเปลี่ยนแปลง API ผ่านการตรวจสอบโค้ด
• การผสานรวม CI/CD เป็นธรรมชาติ (bru run ใน Pipeline ของคุณ)
• ไม่จำเป็นต้องมีบริการบุคคลที่สามนอกเหนือจาก Git host ของคุณ
• ใช้งานได้กับทีมทุกขนาดในทางทฤษฎี

ข้อเสีย:

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

เหมาะสำหรับ: ทีมที่มีแต่นักพัฒนาและมีวินัยในการใช้ Git อย่างสม่ำเสมอ ใช้งานได้ดีกับนักพัฒนา 2-8 คนที่ใช้ Git อยู่แล้วสำหรับงานอื่น ๆ ทั้งหมด รูปแบบนี้เข้ากันได้กับแนวทาง การควบคุมเวอร์ชัน OpenAPI ด้วย Git ที่แพร่หลายมากขึ้น

แนวทางไดรฟ์เครือข่ายที่ใช้ร่วมกัน

บางทีมเก็บโฟลเดอร์ Bruno collection ไว้บนไดรฟ์เครือข่ายที่ใช้ร่วมกัน เช่น NAS, ไฟล์เซิร์ฟเวอร์เครือข่าย, Dropbox ที่แชร์ หรือโฟลเดอร์ Google Drive

วิธีการทำงาน: Bruno เปิด Collection จากพาธโฟลเดอร์ใดก็ได้ ชี้ไปยังตำแหน่งไดรฟ์ที่ใช้ร่วมกัน

ข้อดี:

• ตั้งค่าง่าย ไม่ต้องใช้ Git
• สมาชิกในทีมทุกคนเห็นไฟล์เดียวกัน
• ใช้งานได้กับผู้ที่ไม่ใช่นักพัฒนาที่ไม่สามารถใช้ Git ได้

ข้อเสีย:

• ไม่มีประวัติเวอร์ชัน หรือประวัติเวอร์ชันไม่ดีหากใช้ Dropbox หรือ Drive
• คนสองคนเปิด Collection เดียวกันพร้อมกันอาจทำให้ไฟล์เสียหายหรือเขียนทับได้
• ไดรฟ์เครือข่ายช้ากว่าไฟล์ในเครื่อง; Collection ขนาดใหญ่อาจรู้สึกหน่วง
• ไม่มีการควบคุมการเข้าถึงนอกเหนือจากสิทธิ์ของระบบไฟล์
• ค่าความลับยังคงต้องมีการจัดการแยกต่างหาก
• ใช้งานไม่ได้เมื่อสมาชิกในทีมออฟไลน์หรือมีการเชื่อมต่อที่ไม่เสถียร

เหมาะสำหรับ: ทีมขนาดเล็ก 2-3 คนที่แก้ไขพร้อมกันไม่บ่อยนัก และต้องการการแชร์ที่ไม่ต้องใช้ Git ไม่แนะนำสำหรับการใช้งานที่จริงจัง

แนวทาง Gitpod / Dev container

บางทีมนำ Bruno collection ของตนไปไว้ใน Gitpod workspace หรือคำจำกัดความของ Dev container เพื่อให้ทุกคนได้รับสภาพแวดล้อมที่สอดคล้องกันพร้อมกับ collection ที่รวมอยู่ด้วย

วิธีการทำงาน: Collection อยู่ใน Repo Gitpod หรือ Dev container จะเริ่มต้นทำงานพร้อมกับ Bruno (หรือ Bruno CLI) และ Collection ที่โหลดไว้ล่วงหน้า

ข้อดี:

• สภาพแวดล้อมที่สอดคล้องกันสำหรับนักพัฒนาทุกคน
• Collection ตรงกับ codebase ที่ทดสอบเสมอ
• ไม่ต้องตั้งค่าในเครื่อง โคลนแล้วเริ่ม Dev container ได้เลย

ข้อเสีย:

• ยังคงใช้ Git เป็นหลัก; ผู้ใช้ที่ไม่ถนัด Git จะไม่ได้รับประโยชน์
• Bruno GUI บนเดสก์ท็อปไม่ทำงานในสภาพแวดล้อมการพัฒนาบนคลาวด์ (การตั้งค่าคอนเทนเนอร์ส่วนใหญ่ให้เฉพาะ CLI แบบ Headless)
• ยังไม่มีการซิงค์แบบเรียลไทม์

เหมาะสำหรับ: ทีมที่ใช้ Gitpod หรือ Dev container อยู่แล้ว และต้องการให้การทดสอบ API เชื่อมต่อกับสภาพแวดล้อมการพัฒนา

แนวทางคัดลอกต่อผู้พัฒนา

นี่คือตัวเลือกที่มีโครงสร้างน้อยที่สุด: นักพัฒนาแต่ละคนเก็บ Bruno collection ของตนเอง และซิงค์ด้วยตนเองกับเอกสารที่แชร์ หรือคัดลอกจากการส่งออกของเพื่อนร่วมทีม

ข้อดี:

• เป็นอิสระเต็มที่ ไม่ต้องมีการประสานงาน
• รวดเร็วสำหรับนักพัฒนาแต่ละคน

ข้อเสีย:

• Collection แยกออกจากกันทันที
• ไม่มีแหล่งความจริงร่วมกัน
• “API collection ของทีม” จะไม่มีความหมายเมื่อทุกคนมีเวอร์ชันที่แตกต่างกัน
• ค่าใช้จ่ายในการบำรุงรักษาสะสมเร็ว

เหมาะสำหรับ: ไม่มีใครนอกจากนักพัฒนาเดี่ยว รูปแบบนี้ทำให้เกิดหนี้ทางเทคนิคอย่างรวดเร็ว

ข้อจำกัดที่ทุกวิธีแก้ปัญหามีร่วมกัน

ทุกวิธีแก้ปัญหาการซิงค์ของ Bruno มีช่องว่างเดียวกัน และ Git ไม่สามารถแก้ไขได้:

ไม่มีการทำงานร่วมกันแบบเรียลไทม์ ใน Apidog หรือใน Postman รุ่นเสียเงิน สองคนสามารถเปิด Collection เดียวกันและเห็นการเปลี่ยนแปลงของกันและกันได้ทันที ด้วย Bruno และ Git, อลิซและบ็อบจะทำงานจาก Pull ล่าสุดของพวกเขาเสมอ หากอลิซเพิ่มคำขอและพุช, บ็อบจะไม่เห็นอะไรเลยจนกว่าเขาจะดึงข้อมูล ในระหว่างเซสชัน API ที่ใช้งานอยู่ นั่นคือความขัดแย้งที่เกิดขึ้นตลอดเวลา

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

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

ไม่มีความคิดเห็นระดับ Collection คุณไม่สามารถทิ้งโน้ตไว้ในคำขอเฉพาะเพื่อให้เพื่อนร่วมทีมเห็นได้ ความคิดเห็นใน Git PR ใกล้เคียง แต่จะแนบไปกับ Diff ไม่ใช่กับ Collection ที่ใช้งานจริง

ช่องว่างทั้งสี่นี้คือสาเหตุที่แท้จริงที่ทำให้ทีมเติบโตเกินกว่าวิธีแก้ปัญหาชั่วคราวเหล่านี้ ส่วนถัดไปจะกล่าวถึงวิธีที่ Apidog ปิดช่องว่างเหล่านี้โดยไม่ต้องให้คุณเลิกใช้ Git

โหมด Spec-First Git ของ Apidog: การทำงานแบบ Git โดยไม่ต้องใช้วิธีแก้ปัญหาชั่วคราว

โดยปกติแล้ว มักจะเปรียบเทียบ “Bruno บวก Git” กับ “เครื่องมือคลาวด์” โหมด Spec-First Git ของ Apidog ได้รวมสองทางเลือกนี้เข้าด้วยกัน มันช่วยให้ OpenAPI spec อยู่ใน GitHub, GitLab หรือ repository ที่โฮสต์เองของคุณในฐานะแหล่งความจริงเดียว จากนั้นจึงเพิ่มฟีเจอร์สำหรับทีมบน repository เดียวกันนั้น

นี่คือสิ่งที่เปลี่ยนแปลงเมื่อเทียบกับการตั้งค่า Bruno-plus-Git

สเปกคือแหล่งความจริง และอยู่ใน Repo ของคุณ คุณเชื่อมต่อโปรเจกต์ Apidog กับ Git repository และคำจำกัดความ API จะซิงค์เป็นไฟล์ แยก Branch ตามฟีเจอร์, เปิด Pull request, ตรวจสอบ Contract diff ทีละบรรทัด, แล้วรวมเข้าด้วยกัน นี่คือกระบวนการตรวจสอบที่ Bruno ทำได้ แต่ถูกนำมาใช้กับเอกสาร OpenAPI ฉบับเต็ม แทนที่จะเป็นไฟล์ .bru คำขอที่ไม่ต่อเนื่อง สำหรับเหตุผลเบื้องหลังแนวคิด Design-First โปรดดู การพัฒนา API แบบ Spec-First คืออะไร?

การออกแบบ, การทดสอบ, Mock, และเอกสารทั้งหมดมาจากคำจำกัดความเดียว เมื่อ Spec เปลี่ยนแปลงบน Branch, Mock server, ตัวอย่างการตอบกลับ, Test case และเอกสารอ้างอิงที่เผยแพร่ทั้งหมดจะเปลี่ยนแปลงไปพร้อมกัน และทั้งหมดจะถูกคอมมิตเป็น Diff ที่สามารถตรวจสอบได้ ด้วย Bruno คุณจะได้ไฟล์คำขอ; ส่วนเอกสารและ Mock เป็นปัญหาของคนอื่น นี่คือหัวใจของแนวทาง Spec-as-code และเป็นจุดที่ไฟล์ OpenAPI เพียงไฟล์เดียวทำงานแทนเครื่องมือสี่อย่างที่เคยใช้

คุณยังคงใช้ Git และเพิ่มการทำงานร่วมกันแบบเรียลไทม์ได้ นี่คือส่วนที่วิธีแก้ปัญหาของ Bruno ไม่สามารถเทียบได้ Repo ยังคงเป็นระบบบันทึก แต่เพื่อนร่วมทีมที่ทำงานในแอป Apidog จะเห็นการแก้ไขของกันและกันแบบเรียลไทม์ แทนที่จะต้องรอการ Pull ครั้งถัดไป Git ให้ประวัติและการตรวจสอบ; พื้นที่ทำงานร่วมกันให้เซสชันแบบเรียลไทม์ คุณไม่ต้องเลือกระหว่างสองสิ่งนี้อีกต่อไป

การเข้าถึงตามบทบาทจะอยู่เหนือ Repo บทบาทผู้ดู (Viewer), ผู้แก้ไข (Editor) และผู้ดูแล (Admin) ช่วยให้ผู้มีส่วนได้ส่วนเสียสามารถเรียกใช้คำขอได้โดยไม่ต้องแก้ไข หรือจำกัดผู้รับเหมาให้อยู่ในโปรเจกต์ที่เฉพาะเจาะจง ซึ่งสิทธิ์ Git ระดับ Repo ไม่สามารถทำได้

ข้อมูลรับรองถูกจัดการแบบรวมศูนย์ สภาพแวดล้อมคลาวด์เก็บตัวแปรที่ใช้ร่วมกัน (และจัดเก็บอย่างปลอดภัย) ดังนั้นการหมุนเวียนโทเค็นจะอัปเดตเพียงครั้งเดียว แทนที่จะต้องแจ้งให้นักพัฒนาทุกคนแก้ไขไฟล์ .secret.json ในเครื่อง

มี Mock server มาให้ในตัว Bruno ไม่มี Mock server ซึ่งเป็นเหตุผลที่ทีมมองหา ทางเลือก Mock server สำหรับ Bruno ใน Apidog, Mock จะมาจาก Spec โดยตรง ดังนั้นงาน Frontend จะเริ่มต้นได้ตั้งแต่วันแรกโดยใช้การตอบกลับที่สมจริง

ทำงานใน CI ได้ Apidog มี CLI runner ดังนั้น Test case ที่ผูกกับ Spec ที่ซิงค์ของคุณจะทำงานใน Pipeline เดียวกันกับที่ bru run ทำได้ ทุกครั้งที่มีการ Push

การเปรียบเทียบสั้น ๆ และตรงไปตรงมา:

โหมด Spec-First Git อยู่ในช่วงเบต้า ดังนั้นโปรดยืนยันรายละเอียดเฉพาะกับการตั้งค่า GitHub หรือ GitLab ของคุณในการทดลองใช้งานก่อนที่คุณจะย้ายทีมทั้งหมด สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับการเชื่อมต่อ โปรดดู การผสานรวมและการซิงค์ Git ของ Apidog และ คู่มือโหมด Spec-First หากคุณกำลังพิจารณาเปรียบเทียบสิ่งนี้กับสแตกการออกแบบและการทดสอบแบบสองเครื่องมือ Stoplight + Postman vs Apidog จะทำการประเมินแบบเดียวกัน

เมื่อควรใช้ Bruno ต่อไป และเมื่อควรเปลี่ยน

Bruno บวก Git ใช้งานได้ สำหรับทีมที่เหมาะสมมันทำงานได้ดี คำถามคือเมื่อไหร่ที่ค่าใช้จ่ายสะสมของวิธีแก้ปัญหาชั่วคราวเกินกว่าคุณค่าของความเรียบง่ายของ Bruno

ใช้ Bruno ต่อไปเมื่อทีมของคุณเป็นนักพัฒนาทั้งหมด ทุกคนใช้ Git ได้คล่องแคล่ว คุณไม่ต้องการการซิงค์แบบเรียลไทม์ และโมเดลสิทธิ์ Repo แบบทั้งหมดหรือไม่มีเลยก็เพียงพอแล้ว

เปลี่ยนไปใช้โหมด Apidog Spec-First Git เมื่อ:

• คุณมีสมาชิกในทีมที่ไม่ใช่นักพัฒนา ที่ต้องการเข้าถึง API โดยไม่ต้องเรียนรู้ Git
• ทีมของคุณมีตั้งแต่ 5 คนขึ้นไป และการประสานงานด้วย Git เพียงอย่างเดียวกลายเป็นปัญหาประจำวัน
• คุณต้องการการซิงค์แบบเรียลไทม์ ในระหว่างเซสชัน API ที่ใช้งานอยู่
• คุณต้องการการควบคุมการเข้าถึง ในระดับโปรเจกต์หรือโฟลเดอร์ ไม่ใช่แค่ในระดับ Repository
• คุณเบื่อหน่ายกับการแจกจ่ายข้อมูลรับรอง ด้วยตนเองทุกครั้งที่โทเค็นมีการเปลี่ยนแปลง
• คุณต้องการ Mock server ถัดจาก API client ของคุณ

เนื่องจาก Spec ยังคงอยู่ใน Repo ของคุณ นี่จึงไม่ใช่การเดินออกจากระบบควบคุมเวอร์ชันไปแล้วไม่หวนกลับ คุณยังคงรักษากระบวนการทำงานแบบ Git ที่ Bruno สอนไว้ และเพิ่มเลเยอร์การทำงานของทีมเข้าไป

การตั้งค่าเวิร์กโฟลว์ Bruno + Git ที่ใช้งานได้จริง

หากคุณยังคงใช้ Bruno นี่คือโครงสร้างที่จะช่วยลดความยุ่งยาก:

โครงสร้าง Repository:

api-collections/
  .gitignore              # ไม่รวมไฟล์ *.secret.json, .env
  README.md               # คำแนะนำในการเริ่มต้นใช้งาน
  environments/
    local.json
    staging.json
    production.json       # ไม่มีข้อมูลลับ มีเพียงชื่อตัวแปร
  users-api/
    get-user.bru
    create-user.bru
  orders-api/
    create-order.bru
    list-orders.bru
  bruno.json

การจัดการข้อมูลรับรอง: ใช้ environments/production.secret.json (ถูก Git ignore) สำหรับข้อมูลลับในเครื่อง ระบุตัวแปรที่จำเป็นใน environments/production.json ด้วยค่าว่างเป็นเทมเพลต จัดเก็บค่าจริงใน Password manager หรือ Secrets vault ของทีมของคุณ พร้อมลิงก์ใน README

การเริ่มต้นใช้งานสำหรับนักพัฒนาใหม่:

1. โคลน Repo
2. เปิดโฟลเดอร์ Collection ใน Bruno
3. คัดลอก production.json ไปยัง production.secret.json
4. กรอกข้อมูลรับรองจาก Vault (ลิงก์อยู่ใน README)
5. พร้อมใช้งาน

CI/CD: ใส่ Environment variable ในขณะรันไทม์ เพื่อไม่ให้มีไฟล์ความลับอยู่ใน Repo

จุดยืนของ Bruno ที่ไม่ใช้คลาวด์นั้นมีหลักการและมีประโยชน์อย่างแท้จริง และวิธีแก้ปัญหาการซิงค์ก็สามารถใช้ได้กับทีมที่เหมาะสม การรู้ข้อจำกัดของพวกมันจะช่วยให้คุณรู้ว่าเมื่อไหร่ควรพึ่งพาพวกมัน และเมื่อไหร่ควรใช้เครื่องมือที่สร้างขึ้นเพื่อการทำงานร่วมกันของทีม ด้วย Apidog ที่ตอนนี้เก็บ Spec ไว้ใน Repo ของคุณ การเปลี่ยนไปใช้ Apidog จึงไม่ได้หมายความว่าคุณต้องทิ้ง Git ไว้ข้างหลังอีกต่อไป ดาวน์โหลด Apidog และชี้ไปยัง Repository ที่มีอยู่ของคุณเพื่อดูความแตกต่างบน API ของคุณเอง