กระรอกดินต้นฉบับกำลังหมุนแว่นขยายเหนือกองเอกสารหลายชั้นบนโต๊ะสีครีม
gotoolingdocumentationtutorial

Go 1.27: ใช้ go doc -ex หา executable example ก่อนเดา API

พี่โชว์Engineering

เวลาจำชื่อ API ไม่ได้ เรามักเปิดเว็บหรือถามโมเดลก่อน ทั้งที่คำตอบที่ตรงกับ toolchain และ module ในเครื่องอาจอยู่ใกล้กว่านั้นครับ Go 1.27 ขยายคำสั่ง go doc ให้ค้น executable examples ได้ตรงขึ้นผ่านแฟล็ก -ex จึงเหมาะกับช่วงที่รู้ชื่อ package แต่ยังไม่แน่ใจรูปแบบเรียกใช้

WHY: ตัวอย่างต้องตรงกับของที่ build จริง

เอกสารออนไลน์อาจแสดงเวอร์ชันล่าสุด ขณะที่ repository ยัง pin เวอร์ชันเก่ากว่า เปรียบเหมือนอ่านคู่มือรถรุ่นใหม่แล้วเอาปุ่มไปหาบนรถคันเดิม คำสั่ง go doc อ่านข้อมูลจาก package ที่ Go resolve ในบริบทปัจจุบัน จึงช่วยลดช่องว่างระหว่างสิ่งที่เห็นกับสิ่งที่ compiler จะใช้

แฟล็ก -ex แสดง example functions ที่สัมพันธ์กับ package หรือ symbol ไม่ต้องไล่เปิดไฟล์ทดสอบเอง เหมาะกับการสำรวจ API ก่อนเขียน spike เล็ก ๆ และช่วยเห็นชื่อ example ที่ตั้งตาม convention ของ Go

HOW: เริ่มกว้างแล้วค่อยเจาะ symbol

go doc -ex bytes
go doc -ex bytes.Buffer
go doc bytes.Buffer.WriteString

บรรทัดแรกสำรวจตัวอย่างทั้ง package บรรทัดที่สองบีบมาที่ type และบรรทัดสุดท้ายอ่านสัญญาของ method โดยตรง ลำดับนี้ดีกว่าค้นแบบสุ่ม เพราะเราเห็นทั้งภาพรวม ตัวอย่าง และรายละเอียด signature

หากเป็น dependency ภายนอก ให้รันจาก root ของ module ที่มี go.mod ก่อน แล้วใช้ go list -m all ตรวจว่า resolve เวอร์ชันใด การระบุ package ที่ไม่มีใน build list อาจทำให้คำสั่งต้องค้นหรือดาวน์โหลด module ตามนโยบายของ environment ดังนั้นใน CI หรือเครื่องที่จำกัด network ควรเตรียม module cache และใช้ GOPROXY/GONOSUMDB ตามนโยบายองค์กร

จุดที่ต้องระวัง

ตัวอย่างในเอกสารไม่ใช่ test suite ของระบบเรา มันอธิบายการใช้ API หนึ่งมุม แต่ไม่ได้แทนการทดสอบ timeout, cancellation, invalid input หรือ concurrency ของ production อีกทั้ง example บางตัวมี output comment เพื่อยืนยันผล ส่วนบางตัวเป็นเพียงตัวอย่างที่ compile ได้

จังหวะที่คุ้มที่สุดคือใช้ go doc สร้าง mental model แล้วเขียน test เล็กใน repository เพื่อยืนยัน assumption กับข้อมูลจริง อย่าคัดลอกตัวอย่างยาวทั้งก้อนโดยไม่อ่าน error path และอย่าใช้ผลจากเครื่องหนึ่งแทน lock state ของอีก environment

Recap

  • เริ่มด้วย go doc -ex ที่ package แล้วค่อยเจาะ type หรือ symbol
  • รันจาก module ที่ถูกต้องเพื่อให้ version context ตรงกับ build
  • ใช้ตัวอย่างเป็นแผนที่ ไม่ใช่หลักฐานว่า production case ผ่าน
  • ปิดรอบด้วย test ของ input และ failure mode ที่ระบบเราสนใจ

ครั้งถัดไปที่ติด API เกินสองนาที ลองถาม toolchain ในเครื่องก่อนเปิด search tab แล้วจด assumption ที่ยังต้องทดสอบครับ