Git-first Workflow ของ Bruno: ทำให้ API Change ชัดเจนใน Pull Request เดียว

เวลาทีมพัฒนา backend เปลี่ยน API สิ่งที่มักถูกมองข้ามไม่ใช่แค่โค้ดที่แก้ แต่คือเอกสารและตัวอย่างการใช้งานที่ต้องเปลี่ยนตามไปด้วย โดยเฉพาะ request example, response example, header, body และ environment ที่เกี่ยวข้อง

Git-first workflow ของ Bruno มีประโยชน์มากในจังหวะนี้ เพราะช่วยให้ทุกคนเห็นผลกระทบของการเปลี่ยน API ได้ใน Pull Request เดียว ไม่ใช่เห็นแค่ code diff แต่เห็น collection diff ไปพร้อมกัน ทำให้ reviewer ตรวจได้ทันทีว่าการเปลี่ยนแปลงถูกสื่อสารครบหรือยัง

ปัญหาที่เกิดซ้ำในหลายทีม

สถานการณ์ที่พบได้บ่อยคือ backend เปลี่ยน response field เช่นจาก name เป็น displayName แล้วโค้ดผ่าน review และ merge เรียบร้อย แต่ collection หรือ request example ยังอ้างอิง field เดิมอยู่

ผลคือ frontend และ QA มักเป็นฝ่ายมาเจอปัญหาทีหลัง เช่น

• frontend อ่านค่าไม่ตรงกับ response ใหม่
• test case ของ QA อิงข้อมูลเก่า
• request example ในทีมเริ่มใช้การไม่ได้
• สมาชิกใหม่ในทีมหยิบตัวอย่างผิดไปใช้งาน

ปัญหาเหล่านี้ไม่ได้เกิดจากโค้ดอย่างเดียว แต่เกิดจาก API contract ไม่ได้ถูก review ไปพร้อมกับโค้ด

ทำไม Bruno แบบอยู่ใน repo ถึงช่วยได้

ถ้า Bruno ถูกเก็บไว้ใน repository เดียวกับโปรเจกต์ ทุกครั้งที่มีการเปลี่ยน API ทีมควรเห็นทั้งสองอย่างใน PR เดียวกันคือ

• code diff
• collection diff

ข้อดีคือ reviewer สามารถเช็กได้ทันทีว่า

• request ตัวอย่างถูกอัปเดตแล้วหรือยัง
• body และ header ยังสอดคล้องกับ implementation หรือไม่
• expected response เปลี่ยนตาม contract ใหม่แล้วหรือยัง
• environment ที่ใช้ทดสอบยังรันได้จริงหรือไม่

สิ่งนี้ทำให้ Bruno ไม่ใช่แค่เครื่องมือไว้ยิง API แต่กลายเป็นส่วนหนึ่งของกระบวนการ review อย่างเป็นทางการ

Checklist สำหรับ PR ที่มีการเปลี่ยน API

เมื่อ PR มีการเปลี่ยน API ไม่ว่าจะเป็น public API หรือ internal contract ควรมี checklist สำหรับตรวจอย่างน้อยดังนี้

• endpoint ใหม่มี request ใน Bruno แล้วหรือยัง
• response field ที่เปลี่ยนมีตัวอย่างใหม่หรือไม่
• environment ยังใช้งานได้ตามปกติหรือเปล่า
• request เก่าที่เลิกใช้ถูกลบหรือ marked deprecated แล้วหรือยัง
• มี error case ใหม่ที่ควรเพิ่มเข้ามาหรือไม่

การมี checklist แบบนี้ช่วยลดโอกาสที่ทีมจะ review เฉพาะ business logic แต่ลืมส่วนที่ผู้ใช้งาน API ต้องเจอจริง

ข้อดีของการ review ผ่าน Git

การใช้ Git เป็นศูนย์กลางของการ review API มีข้อดีหลายด้าน

• เห็นได้ว่าใครเป็นคนเปลี่ยน request และเปลี่ยนเมื่อไร
• ย้อนกลับ version ได้หาก API ต้อง rollback
• คุยกันบน diff ได้เหมือนการ review โค้ด
• ทำให้ API contract ไม่หลุดออกจากกระบวนการพัฒนา

เมื่อทุกอย่างอยู่ใน PR เดียวกัน การสื่อสารระหว่าง backend, frontend, QA และ reviewer จะชัดขึ้นมาก เพราะทุกคนอ้างอิงหลักฐานชุดเดียวกัน

เงื่อนไขสำคัญ: Git-first จะเวิร์กได้ต้องมีวินัย

แม้แนวทางนี้จะดี แต่ก็พังได้ง่ายถ้าทีมไม่มีวินัยร่วมกัน

ถ้าทุกคนยังแก้ collection กันในเครื่องตัวเอง และปล่อยให้ไฟล์ใน repo ไม่อัปเดต Bruno จะกลายเป็นแค่ไฟล์เก่าที่ไม่มีใครเชื่อถือ สุดท้ายทีมก็กลับไปใช้การสื่อสารแบบปากเปล่าหรือรอให้ปัญหาไปโผล่ในขั้นตอนทดสอบ

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

กติกาที่ควรตกลงกับทีม

เพื่อให้ Git-first workflow ใช้งานได้จริง ทีมควรมีกติกาชัดเจน เช่น

• ถ้า PR เปลี่ยน API public หรือ internal contract ต้องอัปเดต Bruno ด้วย
• ถ้า PR ไม่ได้อัปเดต Bruno ต้องเขียนเหตุผลไว้ใน PR description
• reviewer มีสิทธิ์ทักเรื่อง request, example และ error case ได้เหมือนการทักโค้ด

กติกาเหล่านี้ช่วยให้การ review ง่ายขึ้น และทำให้ทีมไม่ต้องเดากันเองว่า PR ไหนควรแตะ collection หรือไม่

ตัวอย่างคอมเมนต์ที่ reviewer ใช้ได้

การ review ที่ดีควรถามให้ครอบคลุมผลกระทบของ API ด้วย ตัวอย่างคำถามที่ใช้ได้ เช่น

• “endpoint นี้เปลี่ยน required field แล้ว Bruno request อัปเดตหรือยัง?”
• “มีตัวอย่าง error 403 สำหรับ permission ใหม่ไหม?”
• “response example ยังมี field เก่าอยู่หรือเปล่า?”

คำถามลักษณะนี้ช่วยบังคับให้การ review มองเกินกว่า implementation และหันมาสนใจประสบการณ์ของคนที่ต้องใช้ API จริง

ต่อยอดด้วย CI เพื่อเพิ่มความมั่นใจ

หลังจาก review diff ด้วยสายตาคนแล้ว ยังสามารถเพิ่มความมั่นใจได้อีกชั้นด้วยการให้ CI รัน Bruno CLI กับ collection ชุด smoke test

ผลลัพธ์คือ PR หนึ่งชุดจะผ่านทั้งสองมุมพร้อมกัน

• ผ่านการ review โดยคน
• ผ่านการยิง API จริงแบบอัตโนมัติ

แนวทางนี้ช่วยลดความเสี่ยงที่ตัวอย่างใน collection จะดูถูกต้องใน diff แต่ใช้งานจริงไม่ได้

สรุป

Git-first workflow ของ Bruno ทำให้การเปลี่ยน API ไม่ได้จบแค่ในระดับโค้ด แต่ถูกสะท้อนออกมาใน Pull Request อย่างครบถ้วน ทั้ง request, response, example และ environment

ถ้าทีมมีวินัยในการอัปเดต collection ใน repo และมีกติกาชัดเจนในการ review Bruno จะไม่ใช่แค่ที่เก็บ request แต่จะกลายเป็นหลักฐานสำคัญใน PR ว่า API change ถูกสื่อสารกับทีมครบแล้วจริง ๆ