บทนำ
ถ้าคุณเคยทำงานกับ React มาก่อน คุณอาจเคยได้ยินชื่อ bulletproof-react คู่มือที่นำเสนอแนวทางอย่างชัดเจนและมีจุดยืน (opinionated guide) เพื่อให้ทีมมีมุมมองร่วมกันว่าจะจัดโครงสร้างแอปพลิเคชันอย่างไร ควรเลือกใช้แพตเทิร์นไหน และตรรกะแต่ละประเภทควรจัดวางไว้ตรงไหน คู่มือนี้ไม่ได้คิดค้นแนวคิดใหม่ขึ้นมาเอง หากแต่คัดสรรแนวทางที่พิสูจน์แล้วว่าใช้งานได้ผลจริงบนระบบ production แล้วจัดระเบียบให้ร้อยเรียงเป็นเนื้อเดียวกันอย่างเข้าใจง่าย
ผมจึงอยากให้มีแนวทางเช่นเดียวกันนี้สำหรับ Rust และ Axum และนั่นคือที่มาของคู่มือเล่มนี้ครับ
Axum ถูกออกแบบมาให้มีความมินิมอลโดยตั้งใจ สิ่งที่คุณได้คือเราเตอร์, ตัวแยกข้อมูล (extractor) และการเชื่อมต่อกับ Tower อย่างลึกซึ้ง หลังจากนั้นมันก็จะไม่เข้ามาวุ่นวายหรือก้าวก่ายงานของคุณอีก ความกระชับเรียบง่ายนี้ถือเป็นจุดแข็งที่แท้จริง แต่ในทางกลับกัน ก็หมายความว่าโปรเจกต์ Axum สองโปรเจกต์ที่สร้างโดยสองทีมที่แตกต่างกัน อาจมีหน้าตาของโครงสร้างโค้ดไม่เหมือนกันเลยแม้แต่น้อย ทีมหนึ่งอาจเขียน SQL ลงในแฮนด์เลอร์โดยตรง ขณะที่อีกทีมหนึ่งอาจสร้างสถาปัตยกรรมเฮกซะโกนัล (hexagonal architecture) อันซับซ้อนที่แยกเป็น 5 เครตในเวิร์กสเปซเดียว ซึ่งก็ไม่มีแนวทางใดที่ผิดเสียทีเดียว แต่ความไม่สอดคล้องกันเช่นนี้ทำให้การรับสมาชิกใหม่เข้าสู่ทีม (onboarding) ทำได้ยากขึ้น ดูแลรักษาระบบในระยะยาวได้ลำบากขึ้น และตัดสินใจได้ยากว่าตรรกะแต่ละส่วนควรวางไว้ที่ใด ผมเห็นปัญหานี้เกิดขึ้นซ้ำแล้วซ้ำเล่าจนมั่นใจว่านี่คือปัญหาจริงในการพัฒนา
สิ่งที่ผมตั้งใจทำในคู่มือนี้ คือการรวบรวมชุดคำตอบที่ผ่านการคัดสรรมาอย่างดีสำหรับคำถามเชิงโครงสร้างเหล่านี้ แนวคิดทั้งหมดได้รับแรงบันดาลใจจากสถาปัตยกรรมเฮกซะโกนัลและสถาปัตยกรรม Clean Architecture รวมถึงประสบการณ์จริงที่ผมสั่งสมมาจากบล็อกโพสต์, บทบรรยายในงานประชุม และโปรเจกต์โอเพนซอร์สจำนวนมากในชุมชน Rust web
หนังสือเล่มนี้ครอบคลุมอะไรบ้าง
หนังสือเล่มนี้แบ่งเนื้อหาออกเป็น 6 ส่วน ผมขอพาคุณไปดูภาพรวมสั้นๆ เพื่อให้เห็นว่าเนื้อหาแต่ละเรื่องอยู่ตรงไหน
สถาปัตยกรรม เป็นการวางรากฐานที่มั่นคง เราจะพูดถึงวิธีจัดระเบียบไฟล์และโมดูล วิธีคิดเรื่องเลเยอร์และทิศทางของ dependency ตลอดจนวิธีสร้างแบบจำลองโดเมน (domain modeling) โดยใช้ระบบชนิดข้อมูลของ Rust เพื่อทำให้สถานะที่ไม่ถูกต้องกลายเป็นสิ่งที่ไม่สามารถเกิดขึ้นได้ในโค้ด (unrepresentable) นี่คือสิ่งที่ผมอยากรู้ตั้งแต่เริ่มทำโปรเจกต์ Axum จริงจังครั้งแรก
แพตเทิร์นหลัก จัดการกับปัญหาที่เว็บแอปพลิเคชันทุกตัวต้องเผชิญ ไม่ว่าจะเป็นการจัดการข้อผิดพลาด (error handling), การเข้าถึงฐานข้อมูล, สถานะของแอปพลิเคชัน (application state) และการจัดการการตั้งค่า (configuration) คุณจะได้พบกับแพตเทิร์นที่เป็นรูปธรรมพร้อมโค้ดจริงที่สามารถนำไปปรับใช้ในโปรเจกต์ของคุณได้ทันที
เลเยอร์ HTTP เจาะลึกไปยังส่วนเฉพาะของ Axum ในสแตกทั้งหมด ได้แก่ การกำหนดเส้นทาง (routing), แฮนด์เลอร์, การประกอบมิดเดิลแวร์, การตรวจสอบความถูกต้องของคำขอ (request validation), การยืนยันตัวตน (authentication) ตลอดจนแบบแผนในการออกแบบ API เช่น การแบ่งหน้า (pagination) และการกำหนดเวอร์ชัน
การนำไปใช้งานจริง ครอบคลุมสิ่งจำเป็นที่คุณต้องใช้ในการส่งมอบและดูแลระบบจริงบน production ตั้งแต่การบันทึกข้อมูลแบบมีโครงสร้าง (structured logging) และ tracing, การเสริมความปลอดภัย, กลยุทธ์การทดสอบ, ข้อควรพิจารณาด้านประสิทธิภาพ ไปจนถึงการดีพลอยต์ด้วย Docker พร้อมกลไกการปิดระบบอย่างนุ่มนวล (graceful shutdown) เพราะการเขียนโค้ดเป็นเพียงแค่ครึ่งหนึ่งของงานทั้งหมดเท่านั้น
ขั้นสูง ก้าวข้ามโมเดล HTTP เซิร์ฟเวอร์เดี่ยวไปสู่แพตเทิร์นที่พบในระบบ production ที่มีความซับซ้อนสูง เราจะเจาะลึกจุดที่ต้องระวังเป็นพิเศษของ async ใน Rust (ความปลอดภัยเมื่อถูกยกเลิก หรือ cancellation safety, พฤติกรรมการทำงานของ select!), การสื่อสารระหว่างคอมโพเนนต์ผ่านแชนเนล, การปิดระบบอย่างสอดประสานกันของหลายซับซิสเต็ม, การจัดการงานเบื้องหลัง (background jobs), การเพิ่มพื้นผิว gRPC ด้วย Tonic และการสร้าง state machine ระดับเวลาคอมไพล์ด้วยแพตเทิร์นไทป์สเตต (typestate) บางเรื่องผมต้องใช้เวลานานกว่าจะตกผลึกได้ด้วยตัวเอง จึงหวังเป็นอย่างยิ่งว่าเนื้อหาส่วนนี้จะช่วยให้คุณประหยัดเวลาและไม่ต้องมาปวดหัวกับเรื่องเดิมๆ
อ้างอิง รวบรวมตารางสรุปเครตสำคัญที่ค้นหาได้อย่างรวดเร็ว, แคตตาล็อกแอนติแพตเทิร์นที่พบบ่อยเพื่อช่วยเตือนให้ระวัง และรายการหนังสือ บทความ ตลอดจนตัวอย่างรีพอสิทอรีที่คัดสรรมาสำหรับผู้ที่ต้องการศึกษาต่อในเชิงลึก
หลักการชี้นำ
มีค่านิยมบางประการที่สอดแทรกอยู่ในทุกคำแนะนำของหนังสือเล่มนี้ สิ่งเหล่านี้ไม่ใช่แนวคิดใหม่ที่ผมคิดขึ้นมาเอง แต่เป็นหลักการที่ผมมักจะวนกลับมาใช้เป็นเข็มทิศอยู่เสมอ
ทำให้แฮนด์เลอร์บางที่สุด (Keep handlers thin) หน้าที่ของแฮนด์เลอร์มีเพียงแค่ดึงข้อมูลออกจากคำขอ เรียกใช้เซอร์วิส แล้วแปลงผลลัพธ์ให้เป็นการตอบกลับ (response) เท่านั้น หากแฮนด์เลอร์ของคุณต้องทำทั้งการตรวจสอบความถูกต้อง คิวรีฐานข้อมูล และประมวลผลตรรกะทางธุรกิจในฟังก์ชันเดียว แสดงว่ามันกำลังทำงานมากเกินไปแล้ว ผมเห็นแฮนด์เลอร์ยาว 200 บรรทัดมามากพอที่จะรู้ว่าหนทางนั้นจะนำไปสู่อะไร ดังนั้น จงผลักภาระงานเหล่านั้นไปยังเลเยอร์ที่เหมาะสม
ให้ระบบชนิดข้อมูลทำงานแทนเรา (Let the type system do the work) ระบบชนิดข้อมูลของ Rust ทรงพลังเป็นพิเศษเมื่อเทียบกับภาษาเชิงระบบทั่วไป และจากประสบการณ์ของผม มันเปล่งประกายอย่างเด่นชัดมากในเว็บแอปพลิเคชัน นิวไทป์ (newtype) ที่ช่วยบังคับเงื่อนไขคงสภาพ (invariant) ตั้งแต่ขั้นตอนการสร้างค่า, ชนิดข้อมูล Result ที่ระบุเส้นทางการจัดการข้อผิดพลาดอย่างชัดเจนเปิดเผย และการสร้างนามธรรมด้วย trait เพื่อลดการผูกมัด (decouple) ระหว่างแต่ละเลเยอร์ สิ่งเหล่านี้ช่วยดักจับบั๊กได้ตั้งแต่ตอนคอมไพล์ แทนที่จะหลุดรอดไปสร้างปัญหาบน production ตอนตีสอง ซึ่งคุ้มค่ากับความพยายามตั้งแต่แรกเริ่มเสมอ
แยกสิ่งที่เปลี่ยนแปลงด้วยเหตุผลที่ต่างกัน (Separate what changes for different reasons) เส้นทาง HTTP ของคุณอาจเปลี่ยนเพราะมีการเพิ่มเอนด์พอยต์ใหม่ คิวรีฐานข้อมูลอาจเปลี่ยนเพราะคุณต้องการเพิ่มประสิทธิภาพในจุดที่ช้า กฎเกณฑ์ทางธุรกิจอาจเปลี่ยนเพราะความต้องการของผลิตภัณฑ์พัฒนาไป เมื่อความรับผิดชอบเหล่านี้แยกอยู่ในคนละโมดูลที่มีขอบเขตชัดเจน คุณจะสามารถแก้ไขส่วนหนึ่งได้โดยไม่ต้องกังวลว่าจะกระทบส่วนอื่น ฟังดูเป็นเรื่องธรรมดา แต่ในทางปฏิบัติกลับง่ายมากที่เราจะเผลอปล่อยให้โค้ดแต่ละส่วนปะปนกันจนยุ่งเหยิง
เริ่มจากเรียบง่าย แล้วค่อยต่อยอดอย่างตั้งใจ (Start simple, evolve deliberately) ไม่ใช่ทุกโปรเจกต์ที่จะต้องเริ่มต้นด้วยสถาปัตยกรรมเฮกซะโกนัลและแยก 5 เครตในเวิร์กสเปซ API ขนาดเล็กที่มีเพียงไม่กี่เอนด์พอยต์สามารถเริ่มต้นด้วยโครงสร้างโมดูลแบบเรียบง่ายและเรียกใช้ SQLx โดยตรงได้ สิ่งสำคัญคือการเข้าใจหลักการเบื้องหลังสถาปัตยกรรมที่ซับซ้อนกว่า เพื่อให้คุณสามารถขยับขยายไปสู่จุดนั้นได้อย่างเป็นขั้นเป็นตอนเมื่อความซับซ้อนของระบบเรียกร้องจริงๆ แทนที่จะ over-engineer ตั้งแต่เริ่มต้น หรือต้องมารีแฟกเตอร์กันวุ่นวายเมื่อโครงสร้างเดิมเริ่มรับมือไม่ไหว
ให้ความสำคัญกับผู้อ่านโค้ดเป็นอันดับแรก (Optimize for the reader) โค้ดถูกอ่านบ่อยกว่าถูกเขียนเสมอ เรารู้ความจริงข้อนี้กันดี แต่ก็มักจะลืมได้ง่ายเมื่ออยู่ใต้ความกดดัน แพตเทิร์นในคู่มือนี้จึงให้ความสำคัญกับความชัดเจนและความตรงไปตรงมามากกว่าการเขียนโค้ดที่ดูฉลาดจนเกินไป เมื่อมีเพื่อนร่วมทีมคนใหม่เข้ามาและเปิดดูโค้ดเบสเป็นครั้งแรก พวกเขาควรจะค้นหาสิ่งที่ต้องการพบได้อย่างรวดเร็ว และเข้าใจได้ทันทีว่าทำไมโครงสร้างถึงถูกจัดวางไว้เช่นนั้น
วิธีใช้คู่มือนี้
คุณไม่จำเป็นต้องอ่านคู่มือนี้เรียงตามลำดับตั้งแต่หน้าแรกจนถึงหน้าสุดท้าย หากคุณกำลังเริ่มต้นโปรเจกต์ใหม่ เนื้อหาในส่วนสถาปัตยกรรมจะช่วยให้คุณวางรากฐานที่มั่นคง แต่หากคุณกำลังทำงานกับโปรเจกต์เดิมที่มีอยู่แล้วและต้องการปรับปรุงเฉพาะจุด คุณสามารถข้ามไปยังบทที่เกี่ยวข้องได้ทันที แต่ละบทมีความสมบูรณ์ในตัวเองเพียงพอที่จะอ่านแยกเดี่ยวได้ แม้จะมีการอ้างอิงข้ามบทในหัวข้อที่มีความเกี่ยวเนื่องกันบ้างก็ตาม
ผมพยายามทำให้ตัวอย่างโค้ดมีความสมจริงที่สุด โดยใช้ API จากเครตจริงในแบบที่คุณจะนำไปใช้งานจริงบน production พร้อมการจัดการข้อผิดพลาดที่ถูกต้องและระบุ type signature ชัดเจน ไม่มีการใส่โค้ดหลอกๆ อย่าง todo!() ไว้ในส่วนที่ยาก และในจุดที่มีข้อแลกเปลี่ยน (trade-off) สำคัญระหว่างแต่ละแนวทาง ผมจะอธิบายทั้งสองทางเลือกพร้อมบริบทที่เพียงพอ เพื่อให้คุณตัดสินใจเลือกแนวทางที่เหมาะสมที่สุดสำหรับสถานการณ์ของคุณ
อีกประการหนึ่ง: เอกสารชุดนี้คือเอกสารที่มีชีวิต (living document) ระบบนิเวศเว็บของ Rust ยังคงเติบโตและพัฒนาอย่างรวดเร็ว สิ่งที่เรามองว่าเป็นแนวปฏิบัติที่ดีที่สุดในวันนี้ย่อมได้รับการปรับปรุงต่อไปในอนาคต ทว่าหลักการพื้นฐานมักจะมีความยั่งยืนและมั่นคงกว่าตัวเครตหรือ API เฉพาะเจาะจง และนั่นคือจุดที่ผมเชื่อว่าคุณค่าที่แท้จริงของคู่มือเล่มนี้สถิตอยู่ ถ้าพร้อมแล้ว เรามาเริ่มกันเลยครับ
โครงสร้างโปรเจกต์
ถ้าคุณเคยเปิดโปรเจกต์ใหม่แล้วไม่รู้ว่าจะวางไฟล์ใหม่ของคุณตรงไหน คุณคงตระหนักดีว่าโครงสร้างไดเรกทอรีมีความสำคัญเพียงใด ฟังดูเหมือนเรื่องเล็กน้อย แต่ผมเคยเห็นหลายทีมต้องเสียเวลาไปหลายชั่วโมงกับการถกเถียงว่าโค้ดควรจัดวางไว้ตรงไหน และเคยเห็นโปรเจกต์ที่ทุกอย่างถูกยัดรวมกันไว้ในไดเรกทอรี src/ ขนาดมหึมาเพียงแห่งเดียวเพราะไม่มีใครกำหนดแนวทางไว้ตั้งแต่เริ่มต้น ซึ่งไม่ใช่เรื่องน่าอภิรมย์เลยแม้แต่น้อย
ไม่มีวิธีจัดโครงสร้างเว็บแอปพลิเคชัน Rust ที่ถูกต้องสมบูรณ์แบบเพียงวิธีเดียว แต่มีแพตเทิร์นที่พิสูจน์แล้วว่าใช้งานได้ผลดีเยี่ยมในทางปฏิบัติ ในบทนี้เราจะมาดู 2 รูปแบบหลัก ได้แก่ โครงสร้างแบบเครตเดียว (single-crate) สำหรับโปรเจกต์ขนาดเล็กถึงขนาดกลาง และโครงสร้างแบบเวิร์กสเปซ (workspace) สำหรับระบบที่เติบโตขึ้น ทั้งสองรูปแบบต่างตั้งอยู่บนหลักการพื้นฐานเดียวกัน เพียงแค่ปรับเปลี่ยนตามขนาดและสเกลของระบบเท่านั้น
หลักการ
ก่อนที่เราจะไปดูผังโครงสร้างไดเรกทอรีในรายละเอียด ผมขอสรุปแนวคิดหลักที่อยู่เบื้องหลังโครงสร้างเหล่านี้ให้ฟังก่อนครับ
จัดกลุ่มตามเลเยอร์สถาปัตยกรรมก่อน แล้วค่อยจัดตามความรับผิดชอบ (concern) ภายในแต่ละเลเยอร์ การแบ่งสัดส่วนหลักของเราคือระหว่าง api, domain, และ infra ซึ่งเป็นการบังคับใช้กฎของ dependency (Dependency Rule) ตามที่เราได้พูดถึงไปก่อนหน้านี้ ภายในแต่ละเลเยอร์ เราจะจัดโมดูลตามหน้าที่ความรับผิดชอบ (เช่น แฮนด์เลอร์, โมเดล, รีพอสิทอรี) ขอบอกตามตรงว่าแนวทางนี้หมายความว่า เวลาที่คุณพัฒนาฟีเจอร์เกี่ยวกับผู้ใช้ คุณอาจต้องเปิดสลับไปมาระหว่าง api/handlers/users.rs, domain/models/user.rs และ infra/repositories/user_repo.rs ซึ่งนี่คือข้อแลกเปลี่ยน (trade-off) ในทางปฏิบัติ เมื่อโค้ดเบสขยายใหญ่ขึ้น บางทีมอาจพบว่าการจัดโครงสร้างภายในเลเยอร์ตามแนวฟีเจอร์ (feature slice) เช่น domain/users/model.rs, domain/users/service.rs สะดวกกว่าการจัดตามบทบาทหน้าที่ ซึ่งไม่ว่าจะเลือกแบบใดก็ใช้ได้ทั้งสิ้น สิ่งที่สำคัญที่สุดคือขอบเขตระหว่างแต่ละเลเยอร์จะต้องเด่นชัดและไม่คลุมเครือ
บังคับทิศทางของ dependency (Enforce dependency direction) นี่คือหลักการสำคัญที่สุด ดีเพนเดนซีควรไหลเข้าสู่แกนกลางเสมอ นั่นคือจากเลเยอร์ HTTP มุ่งหน้าเข้าหาเลเยอร์โดเมน โมดูลโดเมนของคุณจึงต้องไม่มีการ import สิ่งใดจาก api หรือ infra เลยแม้แต่อย่างเดียว ความเป็นอิสระนี้เองที่ทำให้ตรรกะทางธุรกิจของคุณสามารถนำไปใช้งานที่อื่นได้ง่าย (portable) และทดสอบแยกเดี่ยวได้อย่างแท้จริง ในโครงสร้างแบบเครตเดียว คุณต้องบังคับใช้ผ่านข้อตกลงร่วมกันและการตรวจทานโค้ด (code review) ซึ่งต้องอาศัยวินัยและความไว้ใจในทีม แต่หากเป็นเวิร์กสเปซ Cargo จะช่วยบังคับผ่านกราฟดีเพนเดนซีของเครตให้อัตโนมัติ ซึ่งแน่นอนว่าปลอดภัยกว่ามาก
ทำให้ main.rs บางที่สุด (Keep main.rs thin) จุดเริ่มต้นการทำงาน (entry point) ของคุณควรทำเพียง 3 หน้าที่หลักเท่านั้น ได้แก่: โหลดการตั้งค่า, ประกอบแอปพลิเคชัน (เชื่อมต่อ wiring ดีเพนเดนซีต่างๆ เข้าด้วยกัน) และสตาร์ตเซิร์ฟเวอร์ เพียงเท่านี้จริงๆ หาก main.rs ของคุณเริ่มยาวขึ้นเรื่อยๆ นั่นเป็นสัญญาณเตือนว่าถึงเวลาย้ายตรรกะการเตรียมระบบ (setup logic) ไปไว้ในโมดูลเฉพาะของตัวเองแล้ว
ใช้ระบบการควบคุมการเข้าถึงเพื่อกำหนดขอบเขต กลไกการกำหนดสิทธิ์การเข้าถึงโมดูลของ Rust (pub, pub(crate), pub(super) และค่าเริ่มต้นที่เป็นแบบ private) คือเครื่องมือทรงพลังในการควบคุมว่าโค้ดส่วนใดสามารถเข้าถึงสิ่งใดได้บ้าง จงเปิดเผยเฉพาะสิ่งที่จำเป็นต้องเป็น public ผ่านไฟล์ mod.rs เท่านั้น และเก็บรายละเอียดการทำงานภายใน (implementation details) ไว้เป็น private หากคุณคุ้นเคยกับโลก JavaScript ลองนึกภาพแพตเทิร์น barrel-export แต่ถูกบังคับใช้อย่างเข้มงวดโดยคอมไพเลอร์ แทนที่จะต้องพึ่งพาเพียงวินัยหรือเจตนาที่ดีของนักพัฒนา
โครงสร้างเครตเดียว
นี่คือรูปแบบที่ผมเลือกใช้สำหรับโปรเจกต์ส่วนใหญ่ เพราะให้การแยกเลเยอร์ที่สะอาดหมดจดโดยไม่ต้องแบกรับภาระการดูแลหลายเครต และคุณยังสามารถต่อยอดไปเป็นเวิร์กสเปซในภายหลังได้อย่างราบรื่นหากระบบเติบโตขึ้น เรามาดูโครงสร้างกันครับ
my-app/
├── Cargo.toml
├── .env.example
├── migrations/
│ ├── 20240101_create_users.sql
│ └── 20240102_create_posts.sql
├── src/
│ ├── main.rs
│ ├── lib.rs
│ ├── config.rs
│ ├── error.rs
│ │
│ ├── domain/
│ │ ├── mod.rs
│ │ ├── models/
│ │ │ ├── mod.rs
│ │ │ ├── user.rs
│ │ │ └── post.rs
│ │ ├── errors.rs
│ │ ├── ports/ # Trait definitions (optional, for trait-based abstractions)
│ │ │ └── user_repository.rs
│ │ └── services/
│ │ ├── mod.rs
│ │ ├── user_service.rs
│ │ └── post_service.rs
│ │
│ ├── infra/
│ │ ├── mod.rs
│ │ ├── db.rs
│ │ └── repositories/
│ │ ├── mod.rs
│ │ ├── user_repo.rs
│ │ └── post_repo.rs
│ │
│ └── api/
│ ├── mod.rs
│ ├── routes.rs
│ ├── state.rs
│ ├── handlers/
│ │ ├── mod.rs
│ │ ├── health.rs
│ │ ├── users.rs
│ │ └── posts.rs
│ ├── extractors/
│ │ ├── mod.rs
│ │ ├── validated_json.rs
│ │ └── auth_user.rs
│ ├── middleware/
│ │ ├── mod.rs
│ │ └── auth.rs
│ └── dtos/
│ ├── mod.rs
│ ├── user_dto.rs
│ └── post_dto.rs
│
├── tests/
│ ├── common/
│ │ ├── mod.rs
│ │ └── test_app.rs
│ └── api/
│ ├── health_test.rs
│ └── users_test.rs
มาดูกันว่าแต่ละส่วนทำหน้าที่อะไร
main.rs และ lib.rs
ไฟล์ main.rs คือจุดเริ่มต้นการทำงานของแอปพลิเคชัน ทำหน้าที่โหลดการตั้งค่า, เริ่มต้นระบบ tracing, สร้างตัวแอปพลิเคชัน และเปิดเซิร์ฟเวอร์เพื่อรอรับคำขอ หน้าที่มีเพียงเท่านี้ และควรคงความเรียบง่ายนี้ไว้เสมอ
use my_app::{config::Config, create_app, observability};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let config = Config::from_env()?;
observability::init_tracing(&config.log_level);
let app = create_app(config.clone()).await?;
let addr = format!("0.0.0.0:{}", config.port);
let listener = tokio::net::TcpListener::bind(&addr).await?;
tracing::info!("listening on {}", listener.local_addr()?);
axum::serve(listener, app)
.with_graceful_shutdown(shutdown_signal()) // defined in the Deployment chapter
.await?;
Ok(())
}
ไฟล์ lib.rs ทำหน้าที่ประกาศโมดูลต่างๆ และเตรียมฟังก์ชัน create_app ไว้ให้ใช้งาน ซึ่งฟังก์ชันนี้จะถูกเรียกใช้โดยชุดการทดสอบการผสาน (integration tests) ด้วยเช่นกัน นั่นหมายความว่าการทดสอบของคุณจะทดสอบกระบวนการเชื่อมต่อ (wiring) แบบเดียวกับที่ใช้บนระบบ production ทุกประการ ผมชื่นชอบแพตเทิร์นนี้มาก เพราะทำให้มั่นใจได้ว่าจะไม่มีเส้นทางการเตรียมระบบ “สำหรับการทดสอบโดยเฉพาะ” ที่อาจมีพฤติกรรมเบี่ยงเบนไปจากระบบจริงโดยที่เราไม่รู้ตัว
#![allow(unused)]
fn main() {
pub mod api;
pub mod config;
pub mod domain;
pub mod error;
pub mod infra;
pub mod observability;
use axum::Router;
use config::Config;
pub async fn create_app(config: Config) -> anyhow::Result<Router> {
let pool = infra::db::create_pool(
config.database_url.expose_secret()
).await?;
sqlx::migrate!("./migrations").run(&pool).await?;
let state = AppState::new(config, pool);
let router = api::routes::router(state);
Ok(router)
}
}
โมดูล domain
นี่คือหัวใจของแอปพลิเคชันของคุณ และต้องไม่มี dependency ใดๆ ต่อ Axum, SQLx หรือเฟรมเวิร์กภายนอกเลยแม้แต่ตัวเดียว เครตภายนอกที่จำเป็นมักมีเพียง serde (สำหรับการ serialize ข้อมูล), thiserror (สำหรับสร้างชนิดข้อมูลข้อผิดพลาด) และเครตยูทิลิตี้พื้นฐานอย่าง uuid และ chrono เท่านั้น แม้จะดูเข้มงวดและมีข้อจำกัด แต่ข้อจำกัดนี้นี่เองที่ช่วยปกป้องความบริสุทธิ์ของเลเยอร์นี้ให้ทำหน้าที่ตามที่ควรจะเป็นอย่างแท้จริง
ไดเรกทอรี models/ บรรจุเอนทิตีของโดเมนและ value object ซึ่งเป็นชนิดข้อมูลที่จำลองแนวคิดหลักที่ระบบทำงานด้วย ส่วน services/ คือที่อยู่ของตรรกะทางธุรกิจ (business logic) ซึ่งก็คือโค้ดที่เข้ามาจัดการและประมวลผลโมเดลเหล่านั้น และ errors.rs จะทำหน้าที่กำหนดชนิดข้อมูลข้อผิดพลาดเฉพาะของโดเมน
แล้วถ้าเลเยอร์โดเมนจำเป็นต้องติดต่อกับโลกภายนอกล่ะ? ไม่ว่าจะเป็นฐานข้อมูล, บริการส่งอีเมล หรือ API ภายนอก? คำตอบคือโดเมนจะกำหนดสัญญาข้อตกลงผ่าน trait ไว้ในไดเรกทอรี ports/ ส่วนโค้ดที่นำ trait เหล่านั้นไปอิมพลีเมนต์ใช้งานจริงจะไปอยู่ที่เลเยอร์ infra เราจะได้เห็นตัวอย่างแพตเทิร์นนี้อย่างละเอียดในบทต่อๆ ไป
โมดูล infra
นี่คือที่อยู่ของโค้ดที่จัดการฐานข้อมูล db.rs ดูแลการสร้าง connection pool และ repositories/ จะบรรจุการอิมพลีเมนต์จริง (concrete implementation) ของ repository trait ต่างๆ ที่โดเมนได้กำหนดไว้
แต่ละ struct ในรีพอสิทอรีจะถือการอ้างอิงไปยัง connection pool และอิมพลีเมนต์ trait ที่ตรงกันจากเลเยอร์โดเมน หน้าที่ของมันคือทำตัวเป็นสะพานเชื่อม แปลงข้อมูลระหว่างชนิดข้อมูลแถว (row type) ของฐานข้อมูลกับโมเดลของโดเมน เปรียบเสมือนล่ามที่เชี่ยวชาญทั้งภาษา SQL และภาษาโดเมนของ Rust
โมดูล api
นี่คือเลเยอร์ที่ผูกพันกับ Axum โดยตรง เข้าใจและรับรู้แนวคิดของ HTTP อย่างสมบูรณ์ เช่น รหัสสถานะ (status code), บอดี้ JSON, ส่วนหัว (header) และมิดเดิลแวร์ เลเยอร์นี้ต้องไม่มีตรรกะทางธุรกิจปะปนอยู่ หากคุณพบว่าตัวเองกำลังเขียนคำสั่ง if เพื่อตรวจสอบเงื่อนไขทางธุรกิจภายในแฮนด์เลอร์ นั่นคือสัญญาณว่าคุณควรย้ายโค้ดส่วนนั้นไปยังเซอร์วิสได้แล้ว
ฟังก์ชันใน handlers/ จะต้องบางและกระชับ มีหน้าที่เพียงสกัดข้อมูลจากคำขอ เรียกใช้เมธอดของเซอร์วิส และส่งผลลัพธ์กลับเป็นการตอบกลับ ผมชอบให้ฟังก์ชันเหล่านี้สั้นที่สุดเท่าที่จะทำได้ ในอุดมคติคือไม่ควรเกิน 20 บรรทัด ส่วน dtos/ จะทำหน้าที่กำหนดโครงสร้างของข้อมูลคำขอและการตอบกลับ (request/response bodies) โดยแยกขาดจากโมเดลของโดเมน เพื่อให้สัญญาของ API (API contract) สามารถปรับเปลี่ยนได้อย่างอิสระโดยไม่ขึ้นอยู่กับโครงสร้างข้อมูลภายใน ส่วน extractors/ จะเก็บ extractor แบบกำหนดเองของ Axum เช่น ValidatedJson หรือ AuthUser (ซึ่งเราจะร่วมกันสร้างในบทต่อๆ ไป) และ middleware/ จะรวบรวมมิดเดิลแวร์ของ Tower ที่สร้างขึ้นเฉพาะสำหรับโปรเจกต์
สุดท้าย ไฟล์ routes.rs จะทำหน้าที่ประกอบเราเตอร์ขึ้นมา โดยนำกลุ่มเส้นทางแต่ละกลุ่มมารวมเข้าด้วยกันและติดตั้งเลเยอร์มิดเดิลแวร์ให้พร้อมใช้งาน
โครงสร้างเวิร์กสเปซ
เมื่อถึงจุดหนึ่ง โปรเจกต์ของคุณอาจเติบโตจนเวลาที่ใช้ในการคอมไพล์เริ่มส่งผลกระทบต่อความเร็วในการพัฒนา หรือระบบอาจมีหลายทีมที่ต้องรับผิดชอบคนละส่วนของระบบ นั่นคือจังหวะที่ผมแนะนำให้เริ่มพิจารณาแบ่งโปรเจกต์ออกเป็น Cargo workspace เวิร์กสเปซจะช่วยบังคับใช้กฎของ dependency ในระดับเครต: หากเครต domain ไม่ได้ประกาศ sqlx ไว้ใน Cargo.toml ก็จะไม่มีใครสามารถเผลอ import มันเข้ามาใช้งานในโดเมนได้อย่างแน่นอน เพราะคอมไพเลอร์จะคอยตรวจจับให้เสมอ
my-app/
├── Cargo.toml # [workspace] definition
├── .env.example
├── migrations/
│
├── crates/
│ ├── domain/
│ │ ├── Cargo.toml # deps: serde, thiserror, uuid, chrono
│ │ └── src/
│ │ ├── lib.rs
│ │ ├── models/
│ │ ├── services/
│ │ ├── ports/ # trait definitions
│ │ └── errors.rs
│ │
│ ├── infra/
│ │ ├── Cargo.toml # deps: domain, sqlx, reqwest, etc.
│ │ └── src/
│ │ ├── lib.rs
│ │ ├── postgres/
│ │ ├── redis/
│ │ └── email/
│ │
│ ├── api/
│ │ ├── Cargo.toml # deps: domain, infra, axum, tower, tower-http
│ │ └── src/
│ │ ├── main.rs
│ │ ├── lib.rs
│ │ ├── routes/
│ │ ├── handlers/
│ │ ├── middleware/
│ │ ├── extractors/
│ │ └── dtos/
│ │
│ └── shared/
│ ├── Cargo.toml
│ └── src/
│ ├── lib.rs
│ ├── config.rs
│ └── observability.rs
ไฟล์ Cargo.toml ที่ระดับรูตจะทำหน้าที่กำหนดขอบเขตของเวิร์กสเปซ และที่สำคัญไม่แพ้กันคือ การกำหนดเวอร์ชันของ dependency ส่วนกลางร่วมกัน นี่คือหนึ่งในฟีเจอร์ของ Cargo ที่ผมชื่นชอบมากที่สุด เพราะช่วยป้องกันไม่ให้เกิดปัญหาที่มี serde 3 เวอร์ชันแตกต่างกันกระจายตัวอยู่ในแต่ละเครตของคุณ:
[workspace]
members = ["crates/*"]
resolver = "2"
[workspace.dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres", "uuid", "chrono", "migrate"] }
axum = { version = "0.8", features = ["macros"] }
tower = "0.5"
tower-http = { version = "0.6", features = ["cors", "compression-gzip", "trace", "timeout", "request-id", "limit"] }
thiserror = "2"
anyhow = "1"
uuid = { version = "1", features = ["v4", "serde"] }
chrono = { version = "0.4", features = ["serde"] }
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
จากนั้นแต่ละเครตจะสืบทอดเวอร์ชันส่วนกลางเหล่านี้ผ่านการตั้งค่า .workspace = true:
# crates/domain/Cargo.toml
[package]
name = "domain"
[dependencies]
serde.workspace = true
thiserror.workspace = true
uuid.workspace = true
chrono.workspace = true
# Note: no axum, no sqlx
จุดเด่นสำคัญที่สุดของแนวทางนี้คือ Cargo จะทำหน้าที่เป็นเกราะป้องกันการละเมิดสถาปัตยกรรมให้คุณ หากใครในทีมพยายามเพิ่มโค้ด import SQLx ในเครตโดเมน ตัวบิลด์จะล้มเหลวทันทีเนื่องจากไม่มี sqlx อยู่ในรายการ dependency ของเครตนั้น ผมเคยเห็นบั๊กประเภท “เผลอผูกโดเมนเข้ากับฐานข้อมูลโดยไม่รู้ตัว” มามากพอ จนรู้สึกซาบซึ้งทุกครั้งที่คอมไพเลอร์ช่วยดักจับความผิดพลาดเหล่านี้ให้ตั้งแต่แรก ซึ่งเป็นการรับประกันที่หนักแน่นและเชื่อถือได้มากกว่าการพึ่งพาเพียงการตรวจทานโค้ด (code review) เพียงอย่างเดียว
เมื่อไหร่ควรเลือกแบบไหน
คำแนะนำของผม: เริ่มต้นด้วยโครงสร้างแบบเครตเดียว (single-crate) ก่อนเสมอ เพราะแนวทางนี้ให้ประโยชน์เชิงโครงสร้างในการแบ่งแยกโค้ดอย่างสะอาดหมดจดครบถ้วน โดยไม่ต้องแบกรับภาระความยุ่งยากในการบริหารจัดการเวิร์กสเปซ คุณสามารถแยกเป็นเวิร์กสเปซในภายหลังเมื่อมีความจำเป็นเกิดขึ้นจริงได้อย่างไม่ยากเย็น เพราะขอบเขตของแต่ละโมดูลถูกวางไว้อย่างเป็นระเบียบตั้งแต่แรกอยู่แล้ว
แล้วเมื่อใดที่คุณควรพิจารณาย้ายไปใช้เวิร์กสเปซจริงๆ? จากประสบการณ์ของผม คือเมื่อคุณเริ่มเผชิญกับสถานการณ์ข้อใดข้อหนึ่งต่อไปนี้:
- เวลาที่ใช้ในการคอมไพล์เริ่มนานเกินไปจนกระทบต่อประสิทธิภาพการทำงาน และคุณต้องการให้กระบวนการบิลด์แบบเพิ่มหน่วย (incremental build) คอมไพล์เฉพาะส่วนที่มีการเปลี่ยนแปลงเท่านั้น
- มีหลายทีมทำงานร่วมกันในแต่ละส่วนของระบบ และคุณต้องการสร้างเส้นแบ่งขอบเขตที่เด็ดขาดระหว่างขอบเขตความรับผิดชอบของแต่ละทีม
- คุณต้องการเผยแพร่บางเครตแยกเป็นอิสระ (เช่น ไลบรารีโดเมนส่วนกลางที่ถูกเรียกใช้โดยหลากหลายเซอร์วิส)
- โปรเจกต์เติบโตจนไดเรกทอรี
src/เพียงแห่งเดียวเริ่มรู้สึกเทอะทะและจัดการได้ยาก
โครงสร้างเวิร์กสเปซยังทำงานได้อย่างยอดเยี่ยมกับสถาปัตยกรรมแบบ monorepo ซึ่งมีหลากหลายเซอร์วิส (เช่น API เซิร์ฟเวอร์, เวิร์กเกอร์เบื้องหลัง, เครื่องมือ CLI) ที่ใช้โค้ดโดเมนและโค้ดอินฟราสตรักเจอร์ชุดเดียวกัน เราจะมาเจาะลึกรูปแบบการตั้งค่าลักษณะนี้ในบทต่อๆ ไปเมื่อพูดถึงเรื่องงานเบื้องหลัง (background jobs)
แพตเทิร์นสถาปัตยกรรม
ถ้าคุณเคยทำงานบนโค้ดเบสที่ตรรกะคิวรีฐานข้อมูลปะปนอยู่ใน HTTP แฮนด์เลอร์ และกฎทางธุรกิจกระจายตัวอยู่หลายแห่ง คุณคงตระหนักดีว่าความยุ่งเหยิงนี้สร้างความเจ็บปวดมากเพียงใดเมื่อเวลาผ่านไป ผมเคยเจอกับตัวเองมาหลายครั้ง และจุดจบมักลงเอยเหมือนเดิมเสมอ: คุณจะเริ่มกลัวการแตะต้องโค้ด เพราะไม่สามารถบอกได้แน่ชัดว่าการแก้ไขจุดหนึ่งจะส่งผลกระทบต่อเนื่องไปถึงส่วนใดบ้าง
บทนี้จะกล่าวถึงแพตเทิร์นที่จะช่วยป้องกันไม่ให้เกิดความสับสนวุ่นวายเหล่านั้น เราจะมาดูวิธีจัดระเบียบเว็บแอปพลิเคชัน Rust ให้แต่ละชิ้นส่วนมีความสะอาดและเป็นอิสระต่อกัน ผมจะไม่ฟันธงว่ามีแนวทางใดเพียงแนวทางเดียวที่ถูกต้อง เพราะระดับความซับซ้อนของโครงสร้างที่เหมาะสมย่อมขึ้นอยู่กับบริบทของโปรเจกต์คุณ แต่เป้าหมายของผมคือต้องการให้คุณเข้าใจตัวเลือกต่างๆ อย่างลึกซึ้งพอที่จะตัดสินใจได้อย่างมั่นใจด้วยตัวเอง
หัวใจสำคัญที่เป็นแกนหลักร่วมกันของทุกแพตเทิร์นคือ กฎของดีเพนเดนซี (Dependency Rule): ดีเพนเดนซีต้องชี้เข้าหาแกนกลางเสมอ นั่นคือจากอินฟราสตรักเจอร์มุ่งหน้าเข้าสู่โดเมน ตรรกะทางธุรกิจของคุณไม่ควรจำเป็นต้องรู้จักรหัสสถานะ HTTP, คิวรี SQL หรือแม้กระทั่งว่ากำลังใช้งานเว็บเฟรมเวิร์กตัวใดอยู่ เมื่อคุณวางรากฐานข้อนี้ได้อย่างถูกต้อง โดเมนของคุณจะสามารถนำไปใช้งานที่อื่นได้ง่าย (portable), ทดสอบได้อย่างมั่นใจ และพร้อมที่จะพัฒนาต่อยอดได้อย่างราบรื่นเมื่อบริบทแวดล้อมเปลี่ยนแปลงไป
โมเดลแบบเลเยอร์
สถาปัตยกรรมที่เรียบง่ายที่สุดและพิสูจน์แล้วว่าใช้งานได้จริงบนระบบ production คือการแบ่งโค้ดออกเป็น 3 เลเยอร์ คุณอาจเคยคุ้นตากับรูปแบบทำนองนี้มาบ้างแล้ว แต่เรามาทบทวนกันว่าแต่ละเลเยอร์มีหน้าที่ทำอะไร และที่สำคัญยิ่งกว่าคือสิ่งใดบ้างที่ไม่ควรทำ
┌──────────────────────────────────────────────┐
│ API Layer │
│ Handlers, routes, middleware, DTOs │
│ Knows about: Axum, HTTP, JSON │
├──────────────────────────────────────────────┤
│ Domain Layer │
│ Models, services, business rules, ports │
│ Knows about: nothing external │
├──────────────────────────────────────────────┤
│ Infrastructure Layer │
│ Repositories, database, external APIs │
│ Knows about: SQLx, Diesel, reqwest, etc. │
└──────────────────────────────────────────────┘
เลเยอร์ API ทำหน้าที่เป็นล่ามแปลภาษาระหว่างโลกของ HTTP กับโลกของโดเมนของคุณ มีหน้าที่แปลงข้อมูลจากบอดี้คำขอ (deserialize) ให้อยู่ในรูปของชนิดข้อมูลโดเมน เรียกใช้เมธอดของเซอร์วิส แล้วแปลงผลลัพธ์ที่ได้กลับไปเป็นการตอบกลับแบบ HTTP (serialize) จงรักษาเลเยอร์นี้ให้บางและกระชับที่สุด หากคุณพบว่าตัวเองกำลังเขียนตรรกะทางธุรกิจลงในแฮนด์เลอร์ ขอให้หยุดทันที เพราะตรรกะนั้นควรไปอยู่ที่เลเยอร์โดเมน ผมเคยเห็นแฮนด์เลอร์บวมจนกลายเป็นโค้ดยาว 200 บรรทัดมามากพอ จนตระหนักดีว่าเราควรรักษามาตรฐานเรื่องนี้อย่างเคร่งครัดตั้งแต่เริ่มต้น
เลเยอร์โดเมนคือแกนกลางและหัวใจของระบบทั้งหมด เป็นที่อยู่ของเอนทิตีทางธุรกิจ, value object, ฟังก์ชันเซอร์วิส ตลอดจนนิยาม trait (พอร์ต) ที่ระบุว่าโดเมนต้องการความสามารถใดจากโลกภายนอกบ้าง เช่น “บันทึกข้อมูลผู้ใช้” หรือ “ส่งอีเมลแจ้งเตือน” จุดสำคัญอย่างยิ่งคือ เลเยอร์นี้ไม่มีความจำเป็นต้องรับรู้เลยว่าความสามารถเหล่านั้นถูกนำไปทำงานจริงอย่างไร ไม่มีการ import sqlx, axum หรือเฟรมเวิร์กใดๆ ทั้งสิ้น เลเยอร์นี้จะบรรจุเพียงตรรกะทางธุรกิจที่บริสุทธิ์เท่านั้น
เลเยอร์อินฟราสตรักเจอร์ทำหน้าที่เตรียมการทำงานจริง (concrete implementation) ให้แก่ trait ต่างๆ ของโดเมน เป็นเลเยอร์ที่รู้จักฐานข้อมูลเฉพาะเจาะจง, API ภายนอก, บริการส่งอีเมล หรือระบบคิวข้อความ เลเยอร์นี้จะขึ้นตรงต่อเลเยอร์โดเมน (เนื่องจากต้องอิมพลีเมนต์ trait ที่โดเมนกำหนดไว้) แต่เลเยอร์โดเมนจะไม่พึ่งพาเลเยอร์นี้เลยแม้แต่น้อย ทิศทางของ dependency ที่ไหลไปในทิศทางเดียวเช่นนี้คือเคล็ดลับที่ทำให้สถาปัตยกรรมทำงานได้อย่างมีประสิทธิภาพ
ทำไมลำดับนี้จึงสำคัญ
คุณอาจมองดูแผนภาพนี้แล้วนึกในใจว่า “ไดอะแกรมก็ดูสวยดี แต่ในทางปฏิบัติมันให้ประโยชน์จริงหรือ?” คำตอบคือสำคัญมากครับ และนี่คือประโยชน์ที่เป็นรูปธรรมอย่างยิ่ง:
เมื่อโดเมนของคุณไม่ต้องพึ่งพาฐานข้อมูล คุณจะสามารถทดสอบตรรกะทางธุรกิจทั้งหมดได้ง่ายๆ เพียงแค่เสียบอิมพลีเมนเทชันแบบ in-memory เข้าไปแทนที่ repository trait โดยไม่จำเป็นต้องเปิดเซิร์ฟเวอร์ PostgreSQL ขึ้นมาเพื่อพิสูจน์ว่าฟังก์ชันคำนวณราคาของคุณทำงานถูกต้อง ชุดทดสอบของคุณจะรันเสร็จในระดับมิลลิวินาที และสามารถรันแบบออฟไลน์ได้ทุกที่ทุกเวลา ซึ่งผมชอบข้อดีนี้มาก
เมื่อโดเมนของคุณเป็นอิสระจาก Axum คุณสามารถนำโค้ดโดเมนชุดเดียวกันนี้ไปใช้งานร่วมกับเครื่องมือ CLI, งานเบื้องหลัง (worker) หรือแม้กระทั่งบริการ gRPC ได้ทันที โดยไม่ต้องพ่วงพาเอาเลเยอร์ HTTP ทั้งกระบิเข้ามาเป็นภาระส่วนเกิน
และเมื่อรายละเอียดการทำงานฝั่งฐานข้อมูลมีการเปลี่ยนแปลง (เช่น การย้ายระบบจาก PostgreSQL ไปยัง CockroachDB หรือเปลี่ยนไลบรารีจาก SQLx เป็น Diesel) เลเยอร์โดเมนของคุณจะไม่ได้รับผลกระทบใดๆ เลย คุณเพียงแค่เขียนโค้ดในเลเยอร์อินฟราสตรักเจอร์ขึ้นมาใหม่ โดยที่ส่วนอื่นๆ ของแอปพลิเคชันไม่จำเป็นต้องรับรู้ถึงความเปลี่ยนแปลงนั้น ผมเคยทำไมเกรชันลักษณะนี้บนโปรเจกต์จริงมาแล้ว และกระบวนการดำเนินไปได้อย่างราบรื่นมากเพราะเรามีการแยกเลเยอร์ที่ชัดเจนตั้งแต่แรก
การแยกชั้นเชิงนามธรรมด้วยเทรต (พอร์ตและอะแดปเตอร์)
แล้วเราจะบังคับใช้การแยกเลเยอร์นี้ในภาษา Rust ได้อย่างไร? คำตอบคือการใช้ trait เลเยอร์โดเมนจะกำหนดนิยาม trait เพื่ออธิบายการดำเนินการที่ต้องการ ส่วนเลเยอร์อินฟราสตรักเจอร์จะสร้าง struct ที่อิมพลีเมนต์ trait เหล่านั้นขึ้นมา จากนั้นเลเยอร์แอปพลิเคชันจะทำหน้าที่เชื่อมต่อ (wiring) ทุกอย่างเข้าด้วยกันในตอนเริ่มต้นระบบ หากคุณคุ้นเคยกับ interface ในภาษาอื่น คุณจะเข้าใจแนวคิดนี้ได้ทันที แต่ระบบ trait ของ Rust ยังมอบการรับประกันความถูกต้องในระดับเวลาคอมไพล์ที่ยอดเยี่ยมเพิ่มขึ้นมาอีกชั้นหนึ่ง
ตัวอย่างหน้าตาของ repository port ในเลเยอร์โดเมน:
#![allow(unused)]
fn main() {
// domain/ports/user_repository.rs
use std::future::Future;
use crate::domain::models::{User, UserId, Email};
use crate::domain::errors::CreateUserError;
pub trait UserRepository: Send + Sync + 'static {
fn create(
&self,
req: &CreateUserRequest,
) -> impl Future<Output = Result<User, CreateUserError>> + Send;
fn find_by_id(
&self,
id: &UserId,
) -> impl Future<Output = Result<Option<User>, anyhow::Error>> + Send;
fn find_by_email(
&self,
email: &Email,
) -> impl Future<Output = Result<Option<User>, anyhow::Error>> + Send;
}
}
มีประเด็นเกี่ยวกับ trait bound ที่น่าสนใจ ขอบเขต Send + Sync + 'static ถูกกำหนดไว้เพราะ Axum จำเป็นต้องแชร์สถานะข้าม async task ต่างๆ ที่อาจทำงานบนเธรดที่ต่างกัน หากคุณเคยเจอกับข้อผิดพลาดตอนคอมไพล์ประเภท “future is not Send” ขอบเขตเหล่านี้คือคำตอบที่ช่วยแก้ปัญหาดังกล่าว ตั้งแต่ Rust 1.75 เป็นต้นมา ฟีเจอร์ async fn ใน trait และ impl Trait ในตำแหน่ง return type ได้รับการพัฒนาจนเข้าสู่สถานะ stable แล้ว ทำให้เราสามารถเขียน signature เหล่านี้ได้โดยตรงโดยไม่ต้องพึ่งพาแมโคร #[async_trait] อีกต่อไป ซึ่งถือเป็นการพัฒนาที่น่ายินดีอย่างยิ่ง
อย่างไรก็ตาม ยังมีข้อจำกัด 2 ประการที่ควรทราบ ประการแรกคือ trait ที่ใช้ -> impl Future หรือ async fn จะไม่เป็น object-safe นั่นหมายความว่าคุณจะไม่สามารถนำมันไปใช้ในรูปของ trait object (dyn Trait) ได้โดยตรง หรือพูดให้เห็นภาพคือ Arc<dyn UserRepository> จะคอมไพล์ไม่ผ่าน หากคุณต้องการใช้งานแบบ dynamic dispatch (ซึ่งเราจะอธิบายในหัวข้อถัดไป) คุณยังคงต้องใช้เครต async_trait หรือทำการห่อ future ด้วย Box ด้วยตัวเอง สำหรับแพตเทิร์นที่แสดงในตัวอย่างนี้จะทำงานร่วมกับ static dispatch (generics) ซึ่งเป็นแนวทางที่ผมแนะนำให้ใช้เป็นค่าเริ่มต้น
ประการที่สอง สำหรับ trait ที่เป็นไลบรารีสาธารณะ (ไม่ใช่พอร์ตที่ใช้ภายในแอปพลิเคชันเอง) การใช้ async fn แบบตรงๆ อาจสร้างปัญหาได้ เนื่องจากผู้เรียกใช้งานภายนอกจะไม่สามารถเพิ่มขอบเขตอย่าง Send ให้แก่ future ที่คืนกลับมาได้โดยไม่ส่งผลกระทบต่อ API (breaking change) หากคุณกำลังพัฒนา trait สำหรับเผยแพร่ให้โค้ดภายนอกเครตนำไปใช้งาน ควรพิจารณาใช้เครต trait_variant (พัฒนาโดย Rust async working group) เพื่อช่วยสร้างวาเรียนต์ที่รองรับ Send ให้อัตโนมัติ:
#![allow(unused)]
fn main() {
#[trait_variant::make(UserRepositorySend: Send)]
pub trait UserRepository { ... }
}
แต่สำหรับพอร์ตที่ใช้งานภายในแอปพลิเคชันทั่วไป (ซึ่งครอบคลุมเซอร์วิสส่วนใหญ่ของ Axum) การใช้ async trait แบบเนทีฟถือว่าตอบโจทย์ได้อย่างยอดเยี่ยมแล้วครับ
อีกข้อสังเกตเล็กๆ คือ Clone ไม่ได้ถูกรวมอยู่ในนิยามของ trait เนื่องจากความสามารถในการโคลนเป็นคุณสมบัติของผู้ถือครอง (เช่น ตัวห่อหุ้ม Arc หรือ struct AppState) ไม่ใช่ข้อกำหนดของสัญญาในระดับโดเมน ตัว struct ในเลเยอร์อินฟราสตรักเจอร์ของคุณยังสามารถ derive Clone ได้ตามต้องการ การแยก Clone ออกจากนิยาม trait จะช่วยรักษาให้สัญญาของโดเมนมุ่งเน้นเฉพาะภารกิจที่แท้จริงเท่านั้น
ต่อไป เรามาดูการอิมพลีเมนต์ใช้งานจริงในเลเยอร์อินฟราสตรักเจอร์กันครับ:
#![allow(unused)]
fn main() {
// infra/repositories/postgres_user_repo.rs
use domain::ports::UserRepository;
#[derive(Clone)]
pub struct PostgresUserRepo {
pool: PgPool,
}
impl PostgresUserRepo {
pub fn new(pool: PgPool) -> Self {
Self { pool }
}
}
impl UserRepository for PostgresUserRepo {
async fn create(&self, req: &CreateUserRequest) -> Result<User, CreateUserError> {
let row = sqlx::query_as!(
UserRow,
r#"INSERT INTO users (id, email, name, password_hash)
VALUES ($1, $2, $3, $4)
RETURNING *"#,
Uuid::new_v4(),
req.email.as_str(),
req.name.as_str(),
req.password_hash,
)
.fetch_one(&self.pool)
.await
.map_err(|e| match e {
sqlx::Error::Database(ref db_err) if db_err.is_unique_violation() => {
CreateUserError::Duplicate { email: req.email.clone() }
}
other => CreateUserError::Unknown(other.into()),
})?;
Ok(row.into())
}
// ... other methods
}
}
สังเกตว่าเลเยอร์อินฟราสตรักเจอร์จะทำหน้าที่แปลงข้อผิดพลาดเฉพาะทางของฐานข้อมูล (เช่น การละเมิดเงื่อนไขความซ้ำซ้อน หรือ unique violation) ให้กลายเป็นข้อผิดพลาดเฉพาะของโดเมน ชนิดข้อมูลข้อผิดพลาดของโดเมนจึงรู้จักเพียงแนวคิดอย่าง “อีเมลซ้ำในระบบ” แทนที่จะเป็นรหัสข้อผิดพลาดของ SQL นี่คือรายละเอียดเล็กๆ ที่สร้างความแตกต่างอย่างมหาศาลเวลาที่คุณต้องตื่นมาดีบั๊กตอนตีสอง เพราะข้อความแจ้งเตือนจะสื่อสารอย่างตรงไปตรงมาว่าเกิดปัญหาอะไรขึ้นในมุมของธุรกิจ
เลเยอร์เซอร์วิส
เซอร์วิสจะอาศัยอยู่ภายในเลเยอร์โดเมนและรับผิดชอบการประสานงาน (orchestrate) ตรรกะทางธุรกิจ เซอร์วิสจะรับเอาพอร์ตของโดเมนเข้ามาผ่านทางพารามิเตอร์เจเนอริก (หรือในรูป trait object หากคุณเลือกใช้ dynamic dispatch) เรียกใช้งานตามลำดับขั้นตอนที่ถูกต้อง และบังคับใช้กฎเกณฑ์ทางธุรกิจ นี่คือพื้นที่ที่ตรรกะสำคัญที่สุดของระบบอาศัยอยู่ หากคุณต้องการทำความเข้าใจว่าแอปพลิเคชันนี้ทำงานอย่างไร การอ่านโค้ดในเลเยอร์เซอร์วิสควรช่วยให้คุณเห็นภาพรวมทั้งหมดได้อย่างชัดเจน โดยไม่ต้องพะวงกับรายละเอียดของ HTTP หรือคำสั่ง SQL
#![allow(unused)]
fn main() {
// domain/services/user_service.rs
#[derive(Clone)]
pub struct UserService<R: UserRepository> {
repo: R,
}
impl<R: UserRepository> UserService<R> {
pub fn new(repo: R) -> Self {
Self { repo }
}
pub async fn register(
&self,
name: UserName,
email: Email,
password: &str,
) -> Result<User, CreateUserError> {
let password_hash = hash_password(password)?;
let req = CreateUserRequest {
name,
email,
password_hash,
};
self.repo.create(&req).await
}
pub async fn get_by_id(&self, id: &UserId) -> Result<Option<User>, anyhow::Error> {
self.repo.find_by_id(id).await
}
}
}
ตัวเซอร์วิสเองไม่มีความจำเป็นต้องรับรู้เลยว่า R คือรีพอสิทอรี PostgreSQL หรือไม่ มันอาจเป็นเพียง mock repository ในหน่วยความจำที่สร้างขึ้นเพื่อใช้ในการทดสอบ หรือเป็นแคชเลเยอร์ที่คอยตรวจสอบ Redis ก่อนจะส่งต่อไปยังฐานข้อมูล เซอร์วิสรับรู้เพียงว่าไม่ว่า R จะเป็นสิ่งใด มันย่อมปฏิบัติตามสัญญาที่ระบุไว้ใน UserRepository อย่างแน่นอน นั่นคือความงดงามของแพตเทิร์นนี้ และเป็นสิ่งที่ทำให้การเขียนชุดทดสอบสำหรับตรรกะทางธุรกิจกลายเป็นเรื่องง่ายและน่ารื่นรมย์อย่างแท้จริง
สแตติกดิสแพตช์กับไดนามิกดิสแพตช์
เมื่อคุณตัดสินใจนำนามธรรมแบบ trait มาใช้ คุณจะพบกับคำถามสำคัญข้อนี้: ควรเลือกใช้เจเนอริก (static dispatch) หรือใช้ trait object (dynamic dispatch) ดี? การทำความเข้าใจข้อแลกเปลี่ยนของทั้งสองแนวทางจะช่วยให้คุณเลือกได้อย่างเหมาะสม:
สแตติกดิสแพตช์ (Static dispatch) ใช้เจเนอริก โดยคอมไพเลอร์จะทำการ monomorphize (สร้างโค้ดเฉพาะสำหรับแต่ละชนิดข้อมูลขึ้นมา) ซึ่งทำให้ไม่มี overhead ในตอนรันไทม์จากการเรียกผ่าน virtual table (vtable) เลย นี่คือแนวทางเดียวกับที่เราใช้กับ UserService<R: UserRepository> ด้านบน
#![allow(unused)]
fn main() {
// Static dispatch: zero runtime cost, resolved at compile time
pub struct UserService<R: UserRepository> {
repo: R,
}
}
ไดนามิกดิสแพตช์ (Dynamic dispatch) อาศัย trait object ที่ถูกห่อหุ้มไว้ใต้ Arc โดยการเรียกใช้เมธอดจะวิ่งผ่าน vtable ในระหว่างรันไทม์ ซึ่งจะเพิ่ม overhead เล็กน้อย แต่ในทางปฏิบัติสำหรับเว็บแอปพลิเคชันแล้ว ผลกระทบนี้แทบจะไม่มีนัยสำคัญเลยเมื่อเทียบกับเวลาที่ต้องใช้ในการรอข้อมูลไปกลับจากฐานข้อมูล ข้อดีคือทำให้ type signature มีความกระชับและสามารถสลับเปลี่ยนการทำงานในตอนรันไทม์ได้สะดวกกว่า
ทว่ามีประเด็นสำคัญที่ต้องคำนึงถึง: trait ที่ใช้ -> impl Future หรือ async fn ใน Rust จะไม่รองรับ object-safe ทำให้ไม่สามารถนำไปใช้กับ dyn Trait ได้โดยตรง หากคุณต้องการใช้ dynamic dispatch คุณมี 2 ทางเลือกหลัก โดยวิธีที่นิยมคือการใช้เครต async_trait เพื่อแปลง async method ให้กลายเป็น boxed future ซึ่งจะทำให้ trait กลายเป็น object-safe:
#![allow(unused)]
fn main() {
use async_trait::async_trait;
#[async_trait]
pub trait UserRepository: Send + Sync + 'static {
async fn create(&self, req: &CreateUserRequest) -> Result<User, CreateUserError>;
async fn find_by_id(&self, id: UserId) -> anyhow::Result<Option<User>>;
}
// Now this works:
pub struct UserService {
repo: Arc<dyn UserRepository>,
}
}
คุณอาจเลือกเขียน boxed future ด้วยตัวเองก็ได้ แต่ในความเป็นจริง แมโคร async_trait ช่วยจัดการสิ่งเหล่านี้ด้วย boilerplate ที่น้อยกว่ามาก จึงไม่คุ้มที่จะต้องมานั่งเขียนโค้ดซ้ำซ้อนด้วยตัวเอง
คำแนะนำของผม: เริ่มต้นด้วย static dispatch ก่อนเสมอ เพราะให้การรับประกันในตอนคอมไพล์ที่แข็งแกร่งกว่า ข้อความแจ้งเตือนข้อผิดพลาดชัดเจน และไม่ต้องกังวลเรื่อง object-safety ให้ยุ่งยาก แล้วค่อยพิจารณาเปลี่ยนไปใช้ dynamic dispatch เมื่อคุณต้องการความยืดหยุ่นในการสลับการทำงานในตอนรันไทม์จริงๆ เช่น การสลับการทำงานตามคอนฟิก หรือเมื่อพารามิเตอร์เจเนอริกเริ่มทำให้ signature รุงรังจนอ่านเข้าใจยากข้ามหลายเลเยอร์ คุณจะรู้ตัวทันทีเมื่อถึงจุดนั้น เพราะคุณจะพบว่าตัวเองกำลังจ้องมอง type signature ที่เต็มไปด้วยพารามิเตอร์รุงรังจนอ่านแทบไม่รู้เรื่อง
สถาปัตยกรรมเฮกซะโกนัลและสถาปัตยกรรมแบบหัวหอม
หากคุณเคยศึกษาเรื่องสถาปัตยกรรมซอฟต์แวร์มาก่อน คุณคงเคยได้ยินชื่อเรียกทั้งสองนี้มาบ้าง แม้ชื่อจะฟังดูซับซ้อน แต่โดยแก่นแท้แล้ว ทั้งหมดเป็นเพียงรูปแบบหนึ่งของแนวคิดหลักเดียวกันกับที่เราได้พูดถึงไปแล้ว นั่นคือการนำโดเมนมาไว้ตรงกลาง แล้วผลักโค้ดเฉพาะทางของเฟรมเวิร์กออกไปไว้ที่ขอบรอบนอก
สถาปัตยกรรมเฮกซะโกนัล (Hexagonal Architecture) (หรือที่รู้จักกันในชื่อพอร์ตและอะแดปเตอร์) มุ่งเน้นความสมมาตรระหว่างอะแดปเตอร์ขาเข้า (inbound adapter) ซึ่งเป็นส่วนที่เรียกเข้ามาหาโดเมน เช่น HTTP แฮนด์เลอร์หรือ gRPC เซิร์ฟเวอร์ กับอะแดปเตอร์ขาออก (outbound adapter) ซึ่งเป็นส่วนที่โดเมนเรียกออกไปหา เช่น ฐานข้อมูลหรือบริการส่งอีเมล โดย “พอร์ต” คือนิยามของ trait และ “อะแดปเตอร์” คือการอิมพลีเมนต์ใช้งานจริง ซึ่งเป็นแนวทางเดียวกับที่เราทำกันมาตลอด
สถาปัตยกรรมแบบหัวหอม (Onion Architecture) นำเสนอภาพของแนวคิดเดียวกันในรูปแบบของวงแหวนที่ซ้อนกันเป็นชั้นๆ รอบศูนย์กลาง โดยวงแหวนชั้นในสุดคือแบบจำลองโดเมน (domain model) ถัดออกมาคือเลเยอร์แอปพลิเคชันหรือเซอร์วิส จากนั้นคือเลเยอร์อินฟราสตรักเจอร์ และวงแหวนชั้นนอกสุดคือเลเยอร์การนำเสนอ (presentation) โดยมีกฎเหล็กว่า dependency ต้องชี้เข้าหาจุดศูนย์กลางเสมอ
ในความเป็นจริง สิ่งเหล่านี้เป็นเพียงชื่อเรียกที่แตกต่างกันของแพตเทิร์นพื้นฐานเดียวกัน โมเดล 3 เลเยอร์ที่เราศึกษามาตั้งแต่ต้นบทคือการนำแนวคิดเหล่านี้มาปรับใช้ในเชิงปฏิบัติ คุณไม่จำเป็นต้องยึดติดกับธรรมเนียมการตั้งชื่อหรือโครงสร้างที่เป็นทางการจนเกินไป สิ่งที่ผมและคุณควรให้ความสำคัญที่สุดคือกฎของ dependency จะต้องเป็นที่เข้าใจและถูกบังคับใช้อย่างเคร่งครัด เพราะชื่อเรียกเป็นเพียงแค่ป้ายกำกับเท่านั้น
การเลือกระดับของสถาปัตยกรรมที่เหมาะสม
โดยเนื้อแท้แล้วผมเป็นคนเน้นการใช้งานจริง (pragmatist) และอยากพูดกับคุณอย่างตรงไปตรงมาว่า: ไม่ใช่ทุกโปรเจกต์ที่ต้องการสถาปัตยกรรมเฮกซะโกนัลแบบเต็มสูบ พร้อม trait port, generic service และ 5 เครตในเวิร์กสเปซ การทำ Over-engineering มีต้นทุนที่ต้องจ่ายจริง ทั้งปริมาณโค้ดที่ต้องเขียนเพิ่ม, ภาระทางความคิด (cognitive load) และความเร็วในการพัฒนาที่ต้องแลกไปเพื่อผลประโยชน์ที่อาจไม่เคยได้ใช้จริง ผมเองก็เคย over-engineer ระบบมาหลายครั้ง และจบลงด้วยความเสียดายเวลาทุกครั้ง
นี่คือแนวทางคร่าวๆ ที่อิงจากประสบการณ์ที่ผมพบว่าใช้งานได้ผลดีที่สุด:
โมดูลแบบเรียบง่าย (Flat modules) เหมาะสำหรับงานโปรโตไทป์, API ขนาดเล็ก และโปรเจกต์ที่มีเอนด์พอยต์เพียงไม่กี่ตัว จัดวางแฮนด์เลอร์, โมเดล และคิวรีไว้ในโมดูลแยกจากกันโดยไม่ต้องสร้าง trait หรือเลเยอร์เซอร์วิสให้ยุ่งยาก คุณสามารถรีแฟกเตอร์ในภายหลังได้เสมอ และสำหรับเซอร์วิสขนาดเล็ก แนวทางที่เรียบง่ายกว่ามักเป็นแนวทางที่ดีกว่าจริงๆ
สถาปัตยกรรมแบบเลเยอร์ในเครตเดียว (Single-crate layered architecture) คือจุดลงตัวที่เหมาะสมที่สุด (sweet spot) สำหรับแอปพลิเคชันบน production ส่วนใหญ่ แยกโดเมนออกจากอินฟราสตรักเจอร์ ใช้เซอร์วิสเพื่อห่อหุ้มตรรกะทางธุรกิจ และรักษาให้แฮนด์เลอร์บางที่สุด แนวทางนี้มอบทั้งความสามารถในการทดสอบและการดูแลรักษาที่ง่ายดายโดยไม่มีขั้นตอนที่ซับซ้อนเกินจำเป็น หากคุณกำลังพัฒนาระบบที่จะนำขึ้น production และมีทีมงานร่วมดูแล นี่คือจุดเริ่มต้นที่เหมาะสมที่สุด
สถาปัตยกรรมเฮกซะโกนัลหรือแบบหัวหอมในเวิร์กสเปซ (Workspace hexagonal/onion architecture) เหมาะสำหรับระบบที่มีโดเมนซับซ้อนและมีตรรกะทางธุรกิจปริมาณมาก, มีหลายทีมทำงานควบคู่กัน หรือมีความจำเป็นต้องรองรับช่องทางขาเข้าหลากหลายรูปแบบ (เช่น HTTP, gRPC, CLI, message consumer) ภายใต้โดเมนเดียวกัน แม้จะต้องลงทุนลงแรงในช่วงแรกค่อนข้างมาก แต่จะคุ้มค่าอย่างยิ่งตลอดอายุการใช้งานของโค้ดเบสระยะยาว ผมเคยร่วมงานในโปรเจกต์ลักษณะนี้ที่การแยกเลเยอร์อย่างสะอาดช่วยประหยัดเวลาในการรีแฟกเตอร์ไปได้หลายสัปดาห์
สิ่งสำคัญที่สุดคือการเริ่มต้นด้วยการแบ่งแยกเลเยอร์ให้ชัดเจนตั้งแต่แรก แม้จะเป็นในโครงสร้างที่เรียบง่ายที่สุดก็ตาม เพราะแพตเทิร์นที่คุณใช้ในการบังคับใช้ขอบเขตจะค่อยๆ วิวัฒนาการไปพร้อมกับการเติบโตของโปรเจกต์ การขยับจากการเรียกใช้ฟังก์ชันโดยตรงไปสู่การสร้างนามธรรมด้วย trait นั้นทำได้ไม่ยากตราบใดที่ขอบเขตระหว่างโมดูลมีความสะอาดตั้งแต่แรก ดังนั้น อย่ากดดันตัวเองให้ต้องสร้างสถาปัตยกรรมที่ “สมบูรณ์แบบไร้ที่ติ” ตั้งแต่วันแรก ขอเพียงแค่วางโครงสร้างเลเยอร์ให้ถูกต้อง แล้วสิ่งดีๆ อื่นๆ จะตามมาเองครับ
การสร้างแบบจำลองโดเมน
ถ้าคุณเคยทำงานบนโค้ดเบสที่มีขนาดจริงจังสักหน่อย คุณอาจเคยเจอเหตุการณ์ทำนองนี้: ฟังก์ชันหนึ่งรับพารามิเตอร์ประเภท String 3 ตัว แต่มีคนเผลอสลับตำแหน่งของ 2 ตัวเข้าด้วยกัน และไม่มีใครสังเกตเห็นจนกระทั่งผู้ใช้ได้รับอีเมลที่มีเนื้อหาสับสนปนเป ผมเคยเจอบั๊กแบบนี้บนระบบ production มามากกว่าหนึ่งครั้ง และมันเป็นความผิดพลาดประเภทที่ทำให้คุณนึกอยากให้คอมไพเลอร์ช่วยตรวจจับให้ได้ตั้งแต่แรก
ข่าวดีก็คือ ในภาษา Rust เราสามารถทำเช่นนั้นได้จริง ระบบชนิดข้อมูลของ Rust มีพลังมากพอที่เราจะฝังกฎเกณฑ์ของโดเมนลงไปในชนิดข้อมูลได้โดยตรง เพื่อให้คอมไพเลอร์ปฏิเสธข้อมูลที่ไม่ถูกต้องตั้งแต่ก่อนที่โค้ดจะได้เริ่มทำงานเสียด้วยซ้ำ บทนี้จะพาคุณไปดูแพตเทิร์นต่างๆ ที่จะช่วยเปลี่ยนแนวคิดนี้ให้กลายเป็นจริงในทางปฏิบัติ
แนวคิดหลักนี้หยิบยืมมาจากโลกของการเขียนโปรแกรมเชิงฟังก์ชัน (functional programming): parse, don’t validate (แยกวิเคราะห์เพื่อสร้างชนิดข้อมูล แทนที่จะเป็นเพียงแค่การตรวจเช็ก) แทนที่จะยอมรับสตริงดิบๆ เข้ามาแล้วโปรยคำสั่งตรวจเช็กแบบ boolean กระจายอยู่ทั่วทุกที่ เราจะนิยามชนิดข้อมูลขึ้นมาใหม่ที่รับประกันว่าจะถูกสร้างขึ้นมาจากข้อมูลที่ถูกต้องเท่านั้น และเมื่อคุณถือตัวแปรชนิดนั้นไว้ในมือ คุณก็มั่นใจได้ทันทีว่ามันถูกต้องเสมอโดยไม่ต้องเสียเวลาตรวจสอบซ้ำอีกต่อไป
แพตเทิร์น newtype
นิวไทป์ (newtype) คือ struct ที่ทำหน้าที่ห่อหุ้มค่าเพียงค่าเดียวไว้ข้างใน ในระหว่างรันไทม์มันมี overhead เป็นศูนย์อย่างแท้จริง เพราะคอมไพเลอร์จะจัดการกับมันเหมือนกับค่าที่อยู่ข้างในโดยตรง แต่ในขั้นตอนการคอมไพล์ มันจะถูกมองว่าเป็นชนิดข้อมูลที่แตกต่างกันโดยสิ้นเชิง ซึ่งหมายความว่าคอมไพเลอร์จะปฏิเสธทันทีหากมีความพยายามนำค่าชนิดหนึ่งไปใส่ในตำแหน่งที่คาดหวังอีกชนิดหนึ่ง ซึ่งถือเป็นข้อแลกเปลี่ยนที่คุ้มค่าอย่างยิ่ง
ผมขอแสดงตัวอย่างให้เห็นภาพชัดเจนขึ้น สมมติว่าแอปพลิเคชันของคุณต้องทำงานกับที่อยู่อีเมล คุณอาจเลือกใช้ String แทนค่าอีเมลในทุกๆ ที่ แต่วิธีนั้นไม่ได้บอกอะไรแก่คอมไพเลอร์ (และเพื่อนร่วมทีมที่มาอ่านโค้ด) เลยว่าสตริงนั้นคือข้อมูลประเภทใด ฟังก์ชันที่รับพารามิเตอร์ (String, String) สำหรับชื่อและอีเมลจึงอาจถูกเรียกใช้งานโดยสลับลำดับอาร์กิวเมนต์ได้ง่ายดาย และคงไม่มีใครรู้ตัวจนกระทั่งผู้ใช้ได้รับอีเมลที่ส่งถึง “alice@example.com” พร้อมคำขึ้นต้นว่า “Dear Alice Johnson” ซึ่งผมเองก็เคยเจอปัญหานี้มาแล้วกับตัว
#![allow(unused)]
fn main() {
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Email(String);
impl Email {
/// WARNING: This is a simplified validator for illustration only.
/// In production, use a proper email validation library or at minimum
/// a well-tested regex. The `validator` crate's `#[validate(email)]`
/// attribute handles this at the DTO layer; this constructor is for
/// the domain layer where you want the type itself to guarantee validity.
pub fn parse(raw: &str) -> Result<Self, DomainError> {
let trimmed = raw.trim().to_lowercase();
if trimmed.contains('@') && trimmed.len() >= 3 {
Ok(Self(trimmed))
} else {
Err(DomainError::InvalidEmail(raw.to_string()))
}
}
pub fn as_str(&self) -> &str {
&self.0
}
}
impl AsRef<str> for Email {
fn as_ref(&self) -> &str {
&self.0
}
}
}
มีประเด็นสำคัญหลายจุดที่ควรสังเกตจากโค้ดข้างต้น:
ฟิลด์ String ภายในถูกกำหนดให้เป็น private ทำให้ไม่มีทางสร้าง instance ของ Email ขึ้นมาได้เลยนอกจากต้องผ่านคอนสตรักเตอร์ parse เท่านั้น ซึ่งจุดนี้ทำหน้าที่เป็นตัวบังคับใช้เงื่อนไขคงสภาพ (invariant) ของเรา และไม่มีทางที่จะขอ mutable reference เข้าไปแก้ไขสตริงด้านในได้โดยตรง เงื่อนไขความถูกต้องจึงไม่มีทางถูกละเมิดหลังจากที่ออบเจกต์ถูกสร้างขึ้นมาแล้ว และนั่นคือหัวใจสำคัญของเทคนิคนี้
เมธอด parse จะส่งผลลัพธ์กลับมาเป็น Result ซึ่งสะท้อนถึงคำว่า “parse” ในหลักการ “parse, don’t validate” กล่าวคือ มันจะส่งคืน instance ของ Email ที่ผ่านการรับประกันความถูกต้องแล้ว หรือไม่ก็ส่งคืนข้อผิดพลาดที่ระบุชัดเจนว่าเหตุใดข้อมูลอินพุตจึงถูกปฏิเสธ เมื่อคุณมีออบเจกต์ Email อยู่ในมือแล้ว คุณจึงมั่นใจได้ทันทีในความถูกต้องของมันโดยไม่จำเป็นต้องตรวจสอบซ้ำอีกเมื่อส่งต่อไปยังฟังก์ชันอื่น ซึ่งเป็นคุณสมบัติที่ช่วยลดความผิดพลาดได้อย่างมหาศาล
การอิมพลีเมนต์ AsRef<str> ช่วยให้ชนิดข้อมูลนี้สามารถนำไปใช้งานร่วมกับฟังก์ชันต่างๆ ที่ต้องการสตริงอ้างอิงได้อย่างสะดวก เช่น การจัดรูปแบบข้อความ หรือการนำไปใช้ในคิวรีฐานข้อมูล โดยยังคงความปลอดภัยและไม่เปิดโอกาสให้มีการแก้ไขค่าภายในได้
การสร้างคำศัพท์ของชนิดข้อมูลโดเมน
เมื่อคุณเริ่มคุ้นเคยกับแพตเทิร์น newtype แล้ว ผมแนะนำให้นำไปปรับใช้กับทุกแนวคิดที่มีความหมายในโดเมนของคุณ ในช่วงแรกอาจรู้สึกเหมือนมีขั้นตอนพิธีรีตองเพิ่มขึ้นมาบ้าง แต่เชื่อเถอะว่ามันจะให้ผลตอบแทนที่คุ้มค่าอย่างรวดเร็วแน่นอน นี่คือตัวอย่างชุดชนิดข้อมูลโดเมนสำหรับระบบบริหารจัดการผู้ใช้:
#![allow(unused)]
fn main() {
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct UserId(Uuid);
impl UserId {
pub fn new() -> Self {
Self(Uuid::new_v4())
}
pub fn from_uuid(id: Uuid) -> Self {
Self(id)
}
pub fn as_uuid(&self) -> &Uuid {
&self.0
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UserName(String);
impl UserName {
pub fn parse(raw: &str) -> Result<Self, DomainError> {
let trimmed = raw.trim();
if trimmed.is_empty() {
return Err(DomainError::EmptyName);
}
if trimmed.len() > 100 {
return Err(DomainError::NameTooLong);
}
// Reject characters that could cause problems in downstream systems
let forbidden = ['/', '(', ')', '"', '<', '>', '\\', '{', '}'];
if trimmed.chars().any(|c| forbidden.contains(&c)) {
return Err(DomainError::NameContainsForbiddenCharacters);
}
Ok(Self(trimmed.to_string()))
}
pub fn as_str(&self) -> &str {
&self.0
}
}
}
ทีนี้ลองมาดูความเปลี่ยนแปลงที่เกิดขึ้นกับ function signature ของเรากันครับ:
#![allow(unused)]
fn main() {
// Before: what is the first String? The second? Who knows.
fn create_user(name: String, email: String) -> Result<User, Error> { ... }
// After: the types make it self-documenting and impossible to mix up.
fn create_user(name: UserName, email: Email) -> Result<User, CreateUserError> { ... }
}
ฟังก์ชันในเวอร์ชันหลังไม่เพียงแค่อ่านเข้าใจได้ง่ายและชัดเจนขึ้นเท่านั้น แต่ยังเป็นไปไม่ได้เลยในทางกายภาพที่จะส่งอาร์กิวเมนต์สลับลำดับกัน เพราะคอมไพเลอร์จะปฏิเสธโค้ดนั้นในทันที นี่คือสิ่งที่ผมหลงรักในภาษา Rust: คุณสามารถทำให้บั๊กทั้งหมวดหมู่กลายเป็นสิ่งที่ไม่สามารถเกิดขึ้นได้ในโค้ด (unrepresentable) โดยไม่ต้องรอให้ “ถูกตรวจพบโดยชุดทดสอบ” หรือ “ถูกทักท้วงในการรีวิวโค้ด” แต่มันไม่สามารถถูกเขียนออกมาได้ตั้งแต่แรกเลยต่างหาก
เอนทิตีของโดเมน
เอนทิตี (Entity) คือออบเจกต์ของโดเมนที่มีเอกลักษณ์ประจำตัวชัดเจน (โดยทั่วไปคือรหัส ID) และมีวงจรชีวิต (lifecycle) ของตัวเอง ลองนึกถึงสิ่งที่มีตัวตนคงอยู่ในระบบของคุณ เช่น ผู้ใช้หนึ่งคน, คำสั่งซื้อหนึ่งรายการ หรือบทความบล็อกหนึ่งเรื่อง สิ่งเหล่านี้คือเอนทิตีของระบบ และมักจะเป็นคำนามเดียวกับที่ทีมงานฝ่ายผลิตภัณฑ์ใช้เรียกในการพูดคุยกันอยู่เสมอ
#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
pub struct User {
id: UserId,
name: UserName,
email: Email,
created_at: DateTime<Utc>,
updated_at: DateTime<Utc>,
}
impl User {
/// Used by the repository layer when hydrating from the database.
pub fn hydrate(
id: UserId,
name: UserName,
email: Email,
created_at: DateTime<Utc>,
updated_at: DateTime<Utc>,
) -> Self {
Self { id, name, email, created_at, updated_at }
}
pub fn id(&self) -> &UserId { &self.id }
pub fn name(&self) -> &UserName { &self.name }
pub fn email(&self) -> &Email { &self.email }
pub fn created_at(&self) -> DateTime<Utc> { self.created_at }
pub fn updated_at(&self) -> DateTime<Utc> { self.updated_at }
}
}
สังเกตว่าฟิลด์ทั้งหมดถูกตั้งค่าให้เป็นแบบ private และ struct จะเปิดเผยเพียงเมธอดประเภท getter ที่คืนการอ้างอิงเท่านั้น ซึ่งนี่เป็นความตั้งใจในการออกแบบ เพราะหากเราต้องการปรับปรุงชื่อของผู้ใช้ การกระทำนั้นควรเกิดขึ้นผ่านเมธอดบนตัวเอนทิตี (หรือผ่านเซอร์วิส) ที่สามารถบังคับใช้กฎเกณฑ์ใดๆ ที่เกี่ยวข้องกับการเปลี่ยนชื่อได้อย่างครบถ้วน เราไม่ต้องการเปิดโอกาสให้โค้ดส่วนอื่นตามใจชอบสามารถเอื้อมเข้ามาแก้ไขค่าของฟิลด์ได้โดยตรง เพราะผมเคยเจ็บปวดกับพฤติกรรมลักษณะนี้ในภาษาอื่นมามากพอจนเกิดความระมัดระวังเป็นพิเศษ
ชนิดข้อมูลคำขอกับชนิดข้อมูลเอนทิตี
นี่คือแพตเทิร์นที่เมื่อเห็นแล้วอาจดูเหมือนเป็นเรื่องธรรมดา แต่ผมเคยเห็นหลายทีมมองข้ามแล้วต้องมานั่งเสียใจในภายหลัง ข้อมูลที่คุณจำเป็นต้องใช้ในการ สร้าง สิ่งของชิ้นหนึ่ง ย่อมไม่เหมือนกับตัวตนของสิ่งของชิ้นนั้นเอง เช่น CreateUserRequest จะประกอบด้วย ชื่อ, อีเมล และรหัสผ่านดิบ ขณะที่ตัวตนของ User จะมีรหัส ID, ข้อมูลเวลา และไม่มีรหัสผ่านดิบอยู่เลย (จะเก็บเพียงค่าแฮชเท่านั้น) ข้อมูลทั้งสองชุดนี้เป็นแนวคิดที่แตกต่างกันโดยสิ้นเชิง จึงควรแยกเป็นชนิดข้อมูลคนละตัวกัน
#![allow(unused)]
fn main() {
/// The data needed to register a new user.
/// All fields have already been parsed into domain types.
pub struct CreateUserRequest {
pub name: UserName,
pub email: Email,
pub password_hash: String,
}
}
ชนิดข้อมูลนี้จะอาศัยอยู่ในเลเยอร์โดเมน โดยแยกขาดจาก DTO ของคำขอ HTTP (ซึ่งอยู่ในเลเยอร์ API) และแยกจากโครงสร้างแถวข้อมูลในฐานข้อมูล (ซึ่งอยู่ในเลเยอร์อินฟราสตรักเจอร์) แต่ละเลเยอร์จะมีชนิดข้อมูลเป็นของตัวเองอย่างชัดเจน และการแปลงข้อมูลข้ามขอบเขตอย่างเปิดเผยจะช่วยรักษาให้เส้นแบ่งเลเยอร์มีความสะอาดหมดจด จริงอยู่ที่วิธีนี้อาจทำให้มี struct ให้ต้องดูแลเพิ่มขึ้น แต่คุณจะรู้สึกขอบคุณตัวเองทันที เมื่อถึงวันที่ต้องปรับแก้รูปแบบการตอบกลับของ API โดยไม่ต้องไปแตะต้องสกีมาของฐานข้อมูลเลยแม้แต่น้อย
การแปลงระหว่างเลเยอร์
เมื่อเรามีชนิดข้อมูลที่แยกเฉพาะในแต่ละเลเยอร์ เราจึงจำเป็นต้องแปลงข้อมูลข้ามไปมาระหว่างเลเยอร์ที่บริเวณขอบเขตของมัน ในภาษา Rust การอิมพลีเมนต์ trait มาตรฐานอย่าง From และ TryFrom ถือเป็นแนวทางที่เป็นธรรมชาติและทรงพลังที่สุดในการจัดการเรื่องนี้
#![allow(unused)]
fn main() {
// Database row type (lives in infra layer)
#[derive(sqlx::FromRow)]
pub struct UserRow {
pub id: Uuid,
pub name: String,
pub email: String,
pub password_hash: String,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
// Convert from database row to domain entity.
// Using TryFrom rather than From because database values may not satisfy
// current domain invariants: legacy rows, manual SQL fixes, schema migrations,
// and previous bugs can all produce data that would fail validation today.
impl TryFrom<UserRow> for User {
type Error = anyhow::Error;
fn try_from(row: UserRow) -> Result<Self, Self::Error> {
Ok(User::hydrate(
UserId::from_uuid(row.id),
UserName::parse(&row.name)
.map_err(|e| anyhow::anyhow!("corrupt user name in row {}: {}", row.id, e))?,
Email::parse(&row.email)
.map_err(|e| anyhow::anyhow!("corrupt email in row {}: {}", row.id, e))?,
row.created_at,
row.updated_at,
))
}
}
// API response type (lives in api layer)
#[derive(Serialize)]
pub struct UserResponse {
pub id: Uuid,
pub name: String,
pub email: String,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
// Convert from domain entity to API response
impl From<User> for UserResponse {
fn from(user: User) -> Self {
Self {
id: *user.id().as_uuid(),
name: user.name().as_str().to_string(),
email: user.email().as_str().to_string(),
created_at: user.created_at(),
updated_at: user.updated_at(),
}
}
}
}
สังเกตว่าชนิดข้อมูลในการตอบกลับของ API นั้น ไม่ได้รวมฟิลด์แฮชของรหัสผ่านเข้าไปด้วย นี่คือหนึ่งในจุดเด่นที่ผมประทับใจที่สุดของการแยกชนิดข้อมูลตามขอบเขต: คุณไม่มีทางที่จะเผลอทำข้อมูลที่มีความอ่อนไหวรั่วไหลออกไปสู่การตอบกลับของ API ได้เลย เพราะ struct นั้นไม่มีฟิลด์ดังกล่าวตั้งแต่แรกแล้วนั่นเอง โดยไม่ต้องคอยพึ่งพาการรีวิวโค้ด หรือต้องคอยจำกฎของ linter แต่อย่างใด
ข้อผิดพลาดของโดเมน
ข้อผิดพลาดที่เกิดขึ้นในระดับโดเมนควรอธิบายความล้มเหลวในเชิงของตรรกะทางธุรกิจ ไม่ใช่ความล้มเหลวในระดับอินฟราสตรักเจอร์ โดเมนควรเข้าใจความหมายของ “ผู้ใช้นี้มีอยู่ในระบบแล้ว” หรือ “รูปแบบของอีเมลไม่ถูกต้อง” แต่ไม่ควร (และไม่มีความจำเป็นต้อง) ไปรับรู้เรื่อง “SQL unique constraint violation” หรือ “HTTP 409 Conflict” หากคุณพบว่าตัวเองกำลัง import ชนิดข้อมูลของ sqlx หรือ axum เข้ามาใน enum ข้อผิดพลาดของโดเมน แสดงว่าโครงสร้างสถาปัตยกรรมเริ่มมีจุดผิดเพี้ยนเกิดขึ้นแล้ว
#![allow(unused)]
fn main() {
#[derive(Debug, thiserror::Error)]
pub enum DomainError {
#[error("invalid email address: {0}")]
InvalidEmail(String),
#[error("name cannot be empty")]
EmptyName,
#[error("name exceeds maximum length")]
NameTooLong,
#[error("name contains forbidden characters")]
NameContainsForbiddenCharacters,
}
#[derive(Debug, thiserror::Error)]
pub enum CreateUserError {
#[error("a user with email {email} already exists")]
Duplicate { email: Email },
#[error(transparent)]
Unknown(#[from] anyhow::Error),
}
}
วาเรียนต์ CreateUserError::Unknown ใช้ anyhow::Error เป็นตัวรับข้อผิดพลาดแบบครอบคลุม (catch-all) สำหรับความล้มเหลวที่ไม่คาดคิด ช่วยให้เลเยอร์อินฟราสตรักเจอร์สามารถแปลงข้อผิดพลาดทั่วไป (เช่น ฐานข้อมูลเกิด connection timeout) ให้กลายเป็นข้อผิดพลาดของโดเมนได้ โดยที่โดเมนไม่จำเป็นต้องระบุรายการข้อผิดพลาดที่เป็นไปได้ทั้งหมด จากนั้นเลเยอร์ API จะทำหน้าที่แมป Unknown ไปเป็นการตอบกลับ HTTP 500 สำหรับฝั่งผู้ใช้ พร้อมทั้งบันทึกรายละเอียดข้อผิดพลาดทั้งหมดไว้ในล็อกฝั่งเซิร์ฟเวอร์ คุณอาจสงสัยว่าการทำเช่นนี้จะหลวมเกินไปหรือไม่ แต่จากประสบการณ์ของผม นี่คือจุดที่ช่วยสร้างสมดุลได้อย่างลงตัว: ข้อผิดพลาดที่คาดการณ์ได้จะถูกระบุชนิดข้อมูลอย่างชัดเจน ขณะที่ข้อผิดพลาดที่ไม่คาดคิดก็ยังคงได้รับการจัดการอย่างนุ่มนวล
การรวมทุกอย่างเข้าด้วยกัน
เราลองมาติดตามเส้นทางการเดินทางของข้อมูลแบบสมบูรณ์ ตั้งแต่คำขอ HTTP ถูกส่งเข้ามา เดินทางไปยังฐานข้อมูล และส่งผลลัพธ์กลับออกไป เพื่อให้เห็นว่าชนิดข้อมูลมีการแปลงรูปข้ามแต่ละขอบเขตอย่างไร:
HTTP POST /api/users
{ "name": "Alice", "email": "alice@example.com", "password": "hunter2" }
↓ Axum deserializes into CreateUserDto (api/dtos)
↓ Handler parses fields into domain types: UserName, Email
↓ Handler calls user_service.register(name, email, &password)
↓ Service hashes password, builds CreateUserRequest (domain)
↓ Service calls repo.create(&request)
↓ Repository converts to SQL, executes INSERT
↓ Repository gets UserRow back from the database
↓ Repository converts UserRow into User (domain entity)
↑ Service returns User to handler
↑ Handler converts User into UserResponse (api/dtos)
↑ Handler returns (StatusCode::CREATED, Json(response))
HTTP 201 Created
{ "id": "...", "name": "Alice", "email": "alice@example.com", ... }
ในทุกๆ ขอบเขต ข้อมูลจะถูกแปลงไปเป็นชนิดข้อมูลที่สังกัดอยู่ในเลเยอร์นั้นๆ เลเยอร์ API จัดการเฉพาะ DTO, เลเยอร์โดเมนจัดการเฉพาะชนิดข้อมูลโดเมน, และเลเยอร์อินฟราสตรักเจอร์จัดการเฉพาะโครงสร้างแถวข้อมูลของฐานข้อมูล การแปลงข้อมูลระหว่างเลเยอร์เหล่านี้มีความโปร่งใส ตรวจสอบย้อนกลับได้ และถูกตรวจสอบอย่างเข้มงวดโดยคอมไพเลอร์
ผมเข้าใจดีว่าแนวทางนี้อาจรู้สึกเหมือนมีขั้นตอนซ้ำซ้อนเมื่อเทียบกับการใช้ struct ตัวเดียวส่งต่อลุยไปตลอดทั้งกระบวนการ ซึ่งผมเองก็เคยรู้สึกเช่นนั้นในตอนเริ่มต้น แต่สิ่งที่ผมได้เรียนรู้จากการทำงานจริงคือ: เวลาที่คุณต้องการเพิ่มฟิลด์ใน API response คุณแค่แก้ที่ DTO, เวลาที่คุณต้องการเพิ่มคอลัมน์ในฐานข้อมูล คุณแค่แก้ที่ row type, และเวลาที่คุณมีกฎทางธุรกิจใหม่ๆ คุณก็ปรับที่ชนิดข้อมูลของโดเมน การเปลี่ยนแปลงแต่ละอย่างจะถูกจำกัดวงอยู่เฉพาะในเลเยอร์ของตัวเองอย่างชัดเจน และโค้ดการอิมพลีเมนต์ From จะทำหน้าที่เป็นเอกสารบอกเราอย่างตรงไปตรงมาว่าแต่ละเลเยอร์เชื่อมโยงกันอย่างไร เมื่อคุณได้สัมผัสกับความสงบเรียบร้อยแบบนี้ในโปรเจกต์ที่มีขนาดเกินสองสามพันบรรทัดขึ้นไปแล้ว คุณจะไม่อยากหวนกลับไปใช้วิธีเดิมๆ อีกเลยครับ
การรวมทุกอย่างเข้าด้วยกัน
ถ้าคุณอ่านบทก่อนๆ มาตลอด คุณคงได้เรียนรู้แนวคิดไปมากมาย ไม่ว่าจะเป็นสถาปัตยกรรมแบบเลเยอร์, การสร้างแบบจำลองโดเมน และการแยกเลเยอร์ออกจากกันอย่างเหมาะสม ทฤษฎีทั้งหมดนั้นฟังดูดี แต่เมื่อถึงเวลาที่เราต้องลงมือพัฒนาแอปพลิเคชันจริง โค้ดจะมีหน้าตาเป็นอย่างไรกันแน่? นั่นคือเป้าหมายหลักของบทนี้ครับ เราจะมาเจาะลึกการพัฒนาฟีเจอร์หนึ่งฟีเจอร์อย่างครบวงจรตั้งแต่ต้นจนจบ ไล่เรียงทีละไฟล์ ทีละชนิดข้อมูล และแสดงให้เห็นถึงการเชื่อมต่อระหว่างแต่ละเลเยอร์ เมื่อจบบทนี้ คุณจะได้เห็นชิ้นส่วนแนวตั้ง (vertical slice) ที่สมบูรณ์แบบหนึ่งชิ้นที่ตัดผ่านทั้งแอปพลิเคชัน ตั้งแต่คำขอ HTTP ที่เดินทางมาถึงแฮนด์เลอร์ ส่งผ่านไปยังเซอร์วิสของโดเมนและพอร์ตของรีพอสิทอรี ลงไปจนถึงฐานข้อมูล และส่งผลลัพธ์ย้อนกลับขึ้นมาเป็นการตอบกลับของ API
ฟีเจอร์ที่เราจะร่วมกันสร้างคือระบบลงทะเบียนผู้ใช้: เอนด์พอยต์ POST /api/v1/users ที่รับชื่อ, อีเมล และรหัสผ่านดิบเข้ามา ทำการตรวจสอบความถูกต้อง, แฮชรหัสผ่าน, บันทึกข้อมูลผู้ใช้ลงในฐานข้อมูล และส่งคืนข้อมูลผู้ใช้ที่สร้างขึ้นกลับไป แม้จะเป็นฟีเจอร์พื้นฐานที่พบได้ทั่วไป แต่มันครอบคลุมการทำงานของทุกเลเยอร์ในระบบ ซึ่งนั่นคือเหตุผลที่ผมเลือกนำฟีเจอร์นี้มาเป็นตัวอย่าง
ไฟล์ที่เราจะสร้าง
ก่อนที่เราจะลงมือเขียนโค้ด นี่คือภาพรวมตำแหน่งของแต่ละไฟล์ในโครงสร้างโปรเจกต์ของเรา:
src/
├── domain/
│ ├── models/
│ │ └── user.rs # Entity, value objects (Email, UserName, UserId)
│ ├── errors.rs # CreateUserError
│ ├── ports/
│ │ └── user_repository.rs # The trait (port)
│ └── services/
│ └── user_service.rs # Business logic
│
├── infra/
│ └── repositories/
│ └── user_repo.rs # PostgresUserRepo (implements the port)
│
├── api/
│ ├── dtos/
│ │ └── user_dto.rs # CreateUserDto, UserResponse
│ ├── handlers/
│ │ └── users.rs # The HTTP handler
│ ├── routes.rs # Route registration
│ └── state.rs # AppState
│
├── error.rs # AppError (HTTP error mapping)
└── main.rs # Wiring everything together
เราจะเริ่มสร้างทีละส่วนโดยเริ่มจากแกนในสุด (เลเยอร์โดเมน) แล้วค่อยๆ ขยายออกสู่เลเยอร์รอบนอก ผมพบว่าการสร้างตามลำดับนี้ช่วยให้ทำงานได้ง่ายที่สุด เพราะเมื่อเราเขียนมาถึงเลเยอร์แฮนด์เลอร์ ชนิดข้อมูลทั้งหมดที่จำเป็นต้องใช้งานก็จะถูกเตรียมไว้พร้อมอยู่แล้ว
ขั้นตอนที่ 1: แบบจำลองโดเมนและวัตถุค่า
ชนิดข้อมูลเหล่านี้จะถูกเก็บไว้ที่ src/domain/models/user.rs สิ่งสำคัญที่สุดคือไฟล์นี้ต้องไม่มี dependency ใดๆ ต่อ Axum, SQLx หรือเฟรมเวิร์กภายนอกเลยแม้แต่น้อย ชนิดข้อมูลเหล่านี้จะบังคับใช้เงื่อนไขคงสภาพ (invariant) ของตัวเองผ่านทางฟิลด์ที่เป็น private และคอนสตรักเตอร์ที่มีการตรวจสอบความถูกต้อง ทำให้คุณไม่มีทางเผลอสร้าง Email ที่ผิดรูปแบบ หรือ UserName ที่เป็นค่าว่างขึ้นมาได้อย่างแน่นอน
#![allow(unused)]
fn main() {
use uuid::Uuid;
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct UserId(Uuid);
impl UserId {
pub fn new() -> Self { Self(Uuid::new_v4()) }
pub fn from_uuid(id: Uuid) -> Self { Self(id) }
pub fn as_uuid(&self) -> &Uuid { &self.0 }
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Email(String);
impl Email {
pub fn parse(raw: &str) -> Result<Self, String> {
let trimmed = raw.trim().to_lowercase();
if trimmed.contains('@') && trimmed.len() >= 3 {
Ok(Self(trimmed))
} else {
Err(format!("'{}' is not a valid email", raw))
}
}
pub fn as_str(&self) -> &str { &self.0 }
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UserName(String);
impl UserName {
pub fn parse(raw: &str) -> Result<Self, String> {
let trimmed = raw.trim();
if trimmed.is_empty() {
return Err("name cannot be empty".into());
}
if trimmed.len() > 100 {
return Err("name cannot exceed 100 characters".into());
}
Ok(Self(trimmed.to_string()))
}
pub fn as_str(&self) -> &str { &self.0 }
}
/// The domain entity. Fields are private; access is through getters.
#[derive(Debug, Clone)]
pub struct User {
id: UserId,
name: UserName,
email: Email,
created_at: chrono::DateTime<chrono::Utc>,
}
impl User {
/// Used by the repository when hydrating from the database.
pub fn hydrate(
id: UserId,
name: UserName,
email: Email,
created_at: chrono::DateTime<chrono::Utc>,
) -> Self {
Self { id, name, email, created_at }
}
pub fn id(&self) -> &UserId { &self.id }
pub fn name(&self) -> &UserName { &self.name }
pub fn email(&self) -> &Email { &self.email }
pub fn created_at(&self) -> chrono::DateTime<chrono::Utc> { self.created_at }
}
/// The data needed to create a new user.
/// By the time this struct exists, all fields have been validated
/// and the password has been hashed.
pub struct NewUser {
pub name: UserName,
pub email: Email,
pub password_hash: String,
}
}
สังเกตว่า User ไม่มีฟิลด์ password_hash รวมอยู่ด้วย ซึ่งนี่คือความตั้งใจในการออกแบบ เอนทิตีตัวนี้ทำหน้าที่เป็นตัวแทนมุมมองสาธารณะของผู้ใช้ ซึ่งปลอดภัยที่จะส่งกลับผ่าน API ได้ ส่วน NewUser เป็น struct แยกต่างหากสำหรับบรรจุข้อมูลที่จำเป็นในขั้นตอนการ สร้าง ผู้ใช้ใหม่ ซึ่งรวมถึงค่าแฮชของรหัสผ่านด้วย คุณอาจสงสัยว่าทำไมเราไม่ใช้ Option<String> ใน struct User เดียวกันไปเลย คำตอบจากประสบการณ์จริงของผมคือ แนวทางนั้นมักนำไปสู่บั๊กประเภทเผลอ serialize ค่าแฮชของรหัสผ่านหลุดเข้าไปในการตอบกลับ JSON โดยไม่ตั้งใจ การแยกเป็นสองชนิดข้อมูลสำหรับสองวัตถุประสงค์ จึงช่วยตัดโอกาสที่จะเกิดอุบัติเหตุเช่นนี้ได้อย่างเด็ดขาด
ขั้นตอนที่ 2: ข้อผิดพลาดของโดเมน
ชนิดข้อมูลข้อผิดพลาดเหล่านี้จะอยู่ใน src/domain/errors.rs เพื่ออธิบายความล้มเหลวในระดับตรรกะทางธุรกิจ ซึ่งเป็นสิ่งที่ทุกคนในทีมเข้าใจตรงกันได้ ไม่ใช่รายละเอียดทางเทคนิคของโครงสร้างพื้นฐานอย่าง “การเชื่อมต่อ TCP หมดเวลา”
#![allow(unused)]
fn main() {
#[derive(Debug, thiserror::Error)]
pub enum CreateUserError {
#[error("a user with email {email} already exists")]
Duplicate { email: Email },
#[error(transparent)]
Unknown(#[from] anyhow::Error),
}
}
CreateUserError::Duplicate สะท้อนถึงการละเมิดกฎทางธุรกิจ: มีผู้ใช้พยายามลงทะเบียนด้วยอีเมลที่มีอยู่ในระบบแล้ว ส่วน CreateUserError::Unknown ทำหน้าที่เป็นกลไกรับมือ (escape hatch) สำหรับความล้มเหลวในระดับอินฟราสตรักเจอร์ที่ไม่คาดคิด (เช่น ฐานข้อมูลหมดเวลาเชื่อมต่อ หรือระบบเครือข่ายขัดข้อง) โดเมนไม่มีความจำเป็นต้องรับรู้รายละเอียดทางเทคนิคเหล่านั้น รู้เพียงแค่ว่าเกิดข้อผิดพลาดขึ้นในกระบวนการทำงาน
ขั้นตอนที่ 3: พอร์ต (เทรตของรีพอสิทอรี)
นี่คือแนวคิดสำคัญที่ทำให้สถาปัตยกรรมแบบเลเยอร์ทำงานร่วมกันได้อย่างสมบูรณ์แบบ หากคุณจะจดจำสิ่งสำคัญที่สุดเพียงข้อเดียวจากบทนี้ ขอให้จำส่วนนี้ไว้ครับ: พอร์ต (Port) คือ trait ที่กำหนดขึ้นในเลเยอร์โดเมน เพื่ออธิบายการดำเนินการที่โดเมนต้องการจากโลกภายนอก โดยโดเมนจะระบุว่า “ฉันต้องการระบบที่สามารถบันทึกและค้นหาข้อมูลผู้ใช้ได้” แต่จะไม่บอกว่า ทำอย่างไร trait นี้จะอยู่ใน src/domain/ports/user_repository.rs
#![allow(unused)]
fn main() {
use std::future::Future;
use crate::domain::models::{User, UserId, Email, NewUser};
use crate::domain::errors::CreateUserError;
pub trait UserRepository: Send + Sync + 'static {
fn create(
&self,
new_user: &NewUser,
) -> impl Future<Output = Result<User, CreateUserError>> + Send;
fn find_by_id(
&self,
id: &UserId,
) -> impl Future<Output = Result<Option<User>, anyhow::Error>> + Send;
fn find_by_email(
&self,
email: &Email,
) -> impl Future<Output = Result<Option<User>, anyhow::Error>> + Send;
}
}
ลองสังเกตส่วนของคำสั่ง import ให้ดี trait นี้จะ import เฉพาะชนิดข้อมูลของโดเมนเท่านั้น ไม่มีการเรียกใช้ PgPool, sqlx::query หรือ axum::State เลย นั่นคือคุณสมบัติที่ทำให้มันทำหน้าที่เป็นพอร์ตได้อย่างแท้จริง: มันทำหน้าที่ขีดเส้นแบ่งขอบเขตระหว่างโดเมนกับอินฟราสตรักเจอร์โดยไม่ผูกมัดกับฝั่งใดฝั่งหนึ่ง
ขอบเขต Send + Sync + 'static ถูกกำหนดไว้เพราะ Axum ต้องแชร์สถานะการทำงานข้าม async task บนหลากหลายเธรด และ trait ใช้ impl Future<...> + Send เป็นชนิดข้อมูลขากลับ ซึ่งทำงานร่วมกับฟีเจอร์ async fn in traits ของ Rust (เป็น stable ตั้งแต่ 1.75) สำหรับการเรียกใช้งานแบบ static dispatch ได้อย่างสมบูรณ์แบบ หากในอนาคตคุณต้องการเปลี่ยนไปใช้ dynamic dispatch (Arc<dyn UserRepository>) คุณก็สามารถสลับไปใช้เครต async_trait ได้ตามที่เราอธิบายไว้ในบท แพตเทิร์นสถาปัตยกรรม
ทำไมเราต้องยอมเสียเวลาสร้างพอร์ตด้วย? ผมมองว่ามันมอบผลตอบแทนที่คุ้มค่า 2 ประการหลัก อย่างแรกคือ ช่วยให้คุณสามารถทดสอบเลเยอร์เซอร์วิสได้โดยไม่ต้องพึ่งพาฐานข้อมูลจริง คุณเพียงแค่เขียนอิมพลีเมนเทชันจำลองของ UserRepository ในหน่วยความจำเพื่อใช้ในการทดสอบ และตัวเซอร์วิสก็ทำงานได้ทันทีโดยไม่เห็นความแตกต่าง ประการที่สองคือ ช่วยบังคับใช้กฎของ dependency ในระดับโมดูล โดเมนจะไม่มีทางเผลอ import SQLx เข้ามาได้โดยบังเอิญ เพราะใน trait ไม่ได้มีการอ้างอิงถึง หากใครพยายามจะเพิ่มพารามิเตอร์ PgPool เข้ามาในไฟล์นี้ พวกเขาจะตระหนักได้ทันทีว่ามันไม่ควรอยู่ที่นี่
เมื่อใดที่คุณไม่จำเป็นต้องใช้พอร์ต: หากแอปพลิเคชันของคุณมีขนาดเล็ก เป็นเพียงระบบ CRUD ทั่วไป และไม่มีแนวโน้มที่จะต้องมี repository implementation รูปแบบที่สอง คุณสามารถข้ามการสร้าง trait ไปได้เลย และให้เซอร์วิสเรียกใช้ struct ของรีพอสิทอรีจริงโดยตรง ซึ่งผมเองก็ใช้วิธีนี้อยู่บ่อยครั้งสำหรับโปรเจกต์งานอดิเรกหรือเครื่องมือใช้งานภายใน บท แอนติแพตเทิร์น จะอธิบายเพิ่มเติมว่าเมื่อใดที่การลดทอนความซับซ้อนเช่นนั้นจึงจะสมเหตุสมผล การใช้พอร์ตจะเริ่มคุ้มค่าเมื่อคุณมีตรรกะทางธุรกิจที่จริงจังซึ่งจำเป็นต้องได้รับการทดสอบ, เมื่อคุณต้องการนำโดเมนไปใช้ซ้ำจากหลายช่องทาง หรือเมื่อทีมมีขนาดใหญ่ขึ้นจนราวกั้นทางสถาปัตยกรรม (architectural guardrails) เริ่มมีความสำคัญ
ขั้นตอนที่ 4: เซอร์วิส
เลเยอร์เซอร์วิสจะอยู่ใน src/domain/services/user_service.rs ซึ่งเป็นจุดที่ตรรกะทางธุรกิจที่แท้จริงทำงาน เซอร์วิสจะเรียกใช้งานรีพอสิทอรีผ่านทาง trait พอร์ตที่เราเพิ่งกำหนดขึ้น
#![allow(unused)]
fn main() {
use crate::domain::models::{User, UserId, Email, UserName, NewUser};
use crate::domain::errors::CreateUserError;
use crate::domain::ports::UserRepository;
#[derive(Clone)]
pub struct UserService<R: UserRepository> {
repo: R,
}
impl<R: UserRepository> UserService<R> {
pub fn new(repo: R) -> Self {
Self { repo }
}
pub async fn register(
&self,
name: UserName,
email: Email,
password: &str,
) -> Result<User, CreateUserError> {
// Hash the password on a blocking thread so we do not
// tie up the async runtime with CPU-intensive work.
let password = password.to_string();
let password_hash = tokio::task::spawn_blocking(move || {
hash_password(&password)
})
.await
.map_err(|e| CreateUserError::Unknown(e.into()))?
.map_err(|e| CreateUserError::Unknown(e.into()))?;
let new_user = NewUser { name, email, password_hash };
self.repo.create(&new_user).await
}
pub async fn get_by_id(&self, id: &UserId) -> Result<Option<User>, anyhow::Error> {
self.repo.find_by_id(id).await
}
}
}
ตัวเซอร์วิสถูกออกแบบให้เป็นเจเนอริกเหนือ R: UserRepository ทำให้ไม่ต้องรับรู้เลยว่า R คือรีพอสิทอรี PostgreSQL ของจริง หรือเป็นเพียง mock repository สำหรับการทดสอบ มันเพียงแค่เรียกใช้เมธอดตามสัญญาที่ trait ระบุไว้ เมธอด register คือจุดที่ตรรกะสำคัญเกิดขึ้น: มันทำการแฮชรหัสผ่านบนเธรดแบบ blocking (เพราะคุณคงไม่อยากให้งานคำนวณหนักๆ อย่าง bcrypt ไปขัดขวางหรือหน่วงการทำงานของ async runtime) แล้วสร้าง struct NewUser ขึ้นมาเพื่อส่งต่อไปให้รีพอสิทอรีบันทึกลงฐานข้อมูล
และสังเกตว่าสิ่งที่เซอร์วิส ไม่รู้ มีอะไรบ้าง: มันไม่มีแนวคิดเกี่ยวกับรหัสสถานะ HTTP, การแปลงข้อมูล JSON หรือรูปแบบของ request/response DTO เลย มันรับเฉพาะชนิดข้อมูลของโดเมน (UserName, Email) และส่งคืนเฉพาะชนิดข้อมูลของโดเมน (User, CreateUserError) ส่วนการแปลงระหว่างโลกของ HTTP กับโลกของโดเมนนั้น คือหน้าที่ความรับผิดชอบของแฮนด์เลอร์ ซึ่งเราจะไปดูกันต่อไป
ขั้นตอนที่ 5: การนำรีพอสิทอรีไปใช้
ตอนนี้เราจะก้าวข้ามขอบเขตเข้าสู่เลเยอร์อินฟราสตรักเจอร์ โค้ดส่วนนี้จะอยู่ใน src/infra/repositories/user_repo.rs และทำหน้าที่อิมพลีเมนต์ trait พอร์ตโดยใช้ SQLx นี่คือพื้นที่ที่โค้ด SQL อาศัยอยู่อย่างแท้จริง
#![allow(unused)]
fn main() {
use anyhow::Context;
use sqlx::PgPool;
use crate::domain::models::{User, UserId, Email, UserName, NewUser};
use crate::domain::errors::CreateUserError;
use crate::domain::ports::UserRepository;
/// The database row type. This is separate from the domain entity
/// because it maps to the database schema, which may differ from
/// the domain's representation.
#[derive(sqlx::FromRow)]
struct UserRow {
id: uuid::Uuid,
name: String,
email: String,
password_hash: String,
created_at: chrono::DateTime<chrono::Utc>,
}
/// Convert a database row to a domain entity.
/// Uses TryFrom because stored data may not satisfy current
/// domain invariants (legacy rows, manual SQL fixes, migrations).
impl TryFrom<UserRow> for User {
type Error = anyhow::Error;
fn try_from(row: UserRow) -> Result<Self, Self::Error> {
Ok(User::hydrate(
UserId::from_uuid(row.id),
UserName::parse(&row.name)
.map_err(|e| anyhow::anyhow!("corrupt name in row {}: {}", row.id, e))?,
Email::parse(&row.email)
.map_err(|e| anyhow::anyhow!("corrupt email in row {}: {}", row.id, e))?,
row.created_at,
))
}
}
#[derive(Clone)]
pub struct PostgresUserRepo {
pool: PgPool,
}
impl PostgresUserRepo {
pub fn new(pool: PgPool) -> Self {
Self { pool }
}
}
impl UserRepository for PostgresUserRepo {
async fn create(&self, new_user: &NewUser) -> Result<User, CreateUserError> {
let row = sqlx::query_as!(
UserRow,
r#"
INSERT INTO users (id, email, name, password_hash)
VALUES ($1, $2, $3, $4)
RETURNING id, email, name, password_hash, created_at
"#,
uuid::Uuid::new_v4(),
new_user.email.as_str(),
new_user.name.as_str(),
&new_user.password_hash,
)
.fetch_one(&self.pool)
.await
.map_err(|e| match e {
sqlx::Error::Database(ref db_err) if db_err.is_unique_violation() => {
CreateUserError::Duplicate { email: new_user.email.clone() }
}
other => CreateUserError::Unknown(
anyhow::anyhow!(other).context("failed to insert user")
),
})?;
row.try_into()
.map_err(|e: anyhow::Error| CreateUserError::Unknown(e))
}
async fn find_by_id(&self, id: &UserId) -> Result<Option<User>, anyhow::Error> {
let row = sqlx::query_as!(
UserRow,
"SELECT id, email, name, password_hash, created_at FROM users WHERE id = $1",
id.as_uuid(),
)
.fetch_optional(&self.pool)
.await
.context("failed to fetch user by id")?;
row.map(TryInto::try_into).transpose()
}
async fn find_by_email(&self, email: &Email) -> Result<Option<User>, anyhow::Error> {
let row = sqlx::query_as!(
UserRow,
"SELECT id, email, name, password_hash, created_at FROM users WHERE email = $1",
email.as_str(),
)
.fetch_optional(&self.pool)
.await
.context("failed to fetch user by email")?;
row.map(TryInto::try_into).transpose()
}
}
}
ไฟล์นี้ร่วมกับโค้ดประกอบระบบใน main.rs (ซึ่งเรียกใช้ PgPool และ sqlx::migrate!) เป็นเพียง 2 จุดในทั้งแอปพลิเคชันที่มีการ import sqlx ผมอยากเน้นย้ำประเด็นนี้เป็นพิเศษ เพราะนี่คือหัวใจของสถาปัตยกรรม: เลเยอร์โดเมนและเลเยอร์ API จะไม่มีทางพบเห็นชนิดข้อมูลของ SQLx เลย แฮนด์เลอร์จะไม่ต้องแตะต้อง UserRow หรือ sqlx::Error รายละเอียดทางเทคนิคเหล่านั้นจะถูกจำกัดไว้ให้อยู่เฉพาะในเลเยอร์อินฟราสตรักเจอร์ตามที่ควรจะเป็น หากในอนาคตคุณตัดสินใจเปลี่ยนจาก Postgres ไปเป็นระบบอื่น คุณจะแก้ไขเพียงแค่ไฟล์นี้ไฟล์เดียว โดยที่เลเยอร์โดเมนจะไม่ได้รับผลกระทบใดๆ เลยแม้แต่น้อย
ขั้นตอนที่ 6: DTO และ AppError
ชนิดข้อมูลสำหรับคำขอและการตอบกลับจะอยู่ที่ src/api/dtos/user_dto.rs สิ่งเหล่านี้คือโครงสร้างข้อมูลที่โลกภายนอกมองเห็น และถูกแยกออกจากชนิดข้อมูลโดเมนอย่างตั้งใจ:
#![allow(unused)]
fn main() {
use serde::{Deserialize, Serialize};
use validator::Validate;
/// What the client sends. Raw strings, validated by the validator crate.
#[derive(Debug, Deserialize, Validate)]
pub struct CreateUserDto {
#[validate(length(min = 1, max = 100))]
pub name: String,
#[validate(email)]
pub email: String,
#[validate(length(min = 8))]
pub password: String,
}
/// What the client receives. No password_hash, no internal IDs.
#[derive(Debug, Serialize)]
pub struct UserResponse {
pub id: uuid::Uuid,
pub name: String,
pub email: String,
pub created_at: chrono::DateTime<chrono::Utc>,
}
impl From<crate::domain::models::User> for UserResponse {
fn from(user: crate::domain::models::User) -> Self {
Self {
id: *user.id().as_uuid(),
name: user.name().as_str().to_string(),
email: user.email().as_str().to_string(),
created_at: user.created_at(),
}
}
}
}
ถัดมาคือ AppError ใน src/error.rs ซึ่งทำหน้าที่เป็นสะพานเชื่อมระหว่างข้อผิดพลาดของโดเมนกับโปรโตคอล HTTP แม้โค้ดส่วนนี้อาจดูเหมือนมี boilerplate อยู่บ้าง แต่มันมอบจุดศูนย์กลางเพียงจุดเดียวที่คุณสามารถกำหนดได้อย่างชัดเจนว่า “ข้อผิดพลาดทางธุรกิจข้อนี้ จะถูกแปลงเป็นรหัสสถานะ HTTP ใด”:
#![allow(unused)]
fn main() {
use std::collections::HashMap;
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use axum::Json;
#[derive(Debug, thiserror::Error)]
pub enum AppError {
#[error("not found")]
NotFound,
#[error("{0}")]
Validation(String),
#[error("unauthorized")]
Unauthorized,
#[error("{0}")]
Conflict(String),
#[error(transparent)]
Internal(#[from] anyhow::Error),
}
pub type AppResult<T> = Result<T, AppError>;
impl IntoResponse for AppError {
fn into_response(self) -> Response {
let (status, message) = match &self {
Self::NotFound => (StatusCode::NOT_FOUND, self.to_string()),
Self::Validation(msg) => (StatusCode::BAD_REQUEST, msg.clone()),
Self::Unauthorized => (StatusCode::UNAUTHORIZED, self.to_string()),
Self::Conflict(msg) => (StatusCode::CONFLICT, msg.clone()),
Self::Internal(e) => {
tracing::error!(error = ?e, "internal error");
(StatusCode::INTERNAL_SERVER_ERROR, "internal error".into())
}
};
let body = serde_json::json!({ "error": { "message": message } });
(status, Json(body)).into_response()
}
}
// Domain error -> AppError conversion
impl From<crate::domain::errors::CreateUserError> for AppError {
fn from(err: crate::domain::errors::CreateUserError) -> Self {
use crate::domain::errors::CreateUserError;
match err {
CreateUserError::Duplicate { email } => {
AppError::Conflict(format!("user with email {} already exists", email.as_str()))
}
CreateUserError::Unknown(e) => AppError::Internal(e),
}
}
}
}
แฮนด์เลอร์จะส่งผลลัพธ์กลับมาเป็น AppResult<T> และหากเกิดกรณีที่เป็น Err ทาง Axum จะเรียกใช้ into_response() อัตโนมัติเพื่อแปลงเป็น HTTP response ข้อผิดพลาด จุดเด่นของแพตเทิร์นนี้คือตัวแฮนด์เลอร์เองไม่ต้องมาพะวงเรื่องรหัสสถานะ HTTP สำหรับกรณี error เลย เพียงแค่ใช้เครื่องหมาย ? แล้วการอิมพลีเมนต์ From จะดูแลรายละเอียดที่เหลือให้ทั้งหมด
ขั้นตอนที่ 7: แฮนด์เลอร์
โค้ดของแฮนด์เลอร์จะอยู่ที่ src/api/handlers/users.rs หากคุณติดตามเนื้อหามาตั้งแต่ต้น คุณคงเดาได้ว่านี่จะเป็นไฟล์ที่เรียบง่ายที่สุดไฟล์หนึ่ง และมันก็เป็นเช่นนั้นจริงๆ โดยแฮนด์เลอร์จะทำงานตามแพตเทิร์น: สกัดข้อมูล (extract), แปลงชนิดข้อมูล (parse), มอบหมายงานให้เซอร์วิส (delegate), และส่งการตอบกลับ (respond)
#![allow(unused)]
fn main() {
use axum::{extract::State, http::StatusCode, Json};
use crate::api::dtos::user_dto::{CreateUserDto, UserResponse};
use crate::api::extractors::ValidatedJson;
use crate::api::state::AppState;
use crate::domain::models::{UserName, Email};
use crate::error::{AppError, AppResult};
pub async fn create_user(
State(state): State<AppState>,
ValidatedJson(payload): ValidatedJson<CreateUserDto>,
) -> AppResult<(StatusCode, Json<UserResponse>)> {
// Parse raw strings into domain types.
// If parsing fails, it becomes a validation error.
let name = UserName::parse(&payload.name)
.map_err(|e| AppError::Validation(e))?;
let email = Email::parse(&payload.email)
.map_err(|e| AppError::Validation(e))?;
// Delegate to the service. The ? operator converts
// CreateUserError -> AppError automatically via the From impl.
let user = state.user_service
.register(name, email, &payload.password)
.await?;
// Convert the domain entity to a response DTO.
Ok((StatusCode::CREATED, Json(user.into())))
}
}
มีโค้ดตรรกะเพียง 14 บรรทัดเท่านั้นจริงๆ ไม่มี SQL, ไม่มีการแฮชรหัสผ่าน, และไม่มีกฎทางธุรกิจปะปน หน้าที่ของมันมีเพียงดึงข้อมูลจากคำขอ แปลงฟิลด์ต่างๆ ให้เป็นชนิดข้อมูลโดเมน เรียกใช้เซอร์วิส และส่งคืนการตอบกลับ หากมีขั้นตอนใดล้มเหลว โอเปอเรเตอร์ ? จะส่งต่อข้อผิดพลาดผ่านสายโซ่ของ From จนกระทั่งกลายเป็นการตอบกลับแบบ HTTP ที่เหมาะสม ผมพบว่าเมื่อแฮนด์เลอร์มีความบางและกระชับเช่นนี้ แทบจะเป็นไปไม่ได้เลยที่จะเขียนโค้ดผิดพลาด และการตรวจทานโค้ด (code review) ก็ดำเนินไปได้อย่างรวดเร็วและง่ายดาย
ขั้นตอนที่ 8: AppState และการต่อสาย
AppState ใน src/api/state.rs ทำหน้าที่เก็บ dependency ส่วนกลางที่ต้องแชร์ร่วมกัน เปรียบเสมือนศูนย์รวม dependency ต่างๆ ที่แฮนด์เลอร์จำเป็นต้องใช้ในการปฏิบัติงาน:
#![allow(unused)]
fn main() {
use axum::extract::FromRef;
use sqlx::PgPool;
use std::sync::Arc;
use crate::config::Config;
use crate::domain::services::UserService;
use crate::infra::repositories::PostgresUserRepo;
#[derive(Clone, FromRef)]
pub struct AppState {
pub config: Arc<Config>,
pub db: PgPool,
pub user_service: UserService<PostgresUserRepo>,
}
}
จากนั้น ไฟล์ main.rs จะทำหน้าที่เชื่อมต่อ (wiring) ทุกอย่างเข้าด้วยกัน นี่คือจังหวะที่นามธรรมทั้งหมดที่เราออกแบบไว้ เชื่อมโยงเข้ากับความเป็นจริงในทางปฏิบัติ:
use crate::api::state::AppState;
use crate::config::Config;
use crate::infra::repositories::PostgresUserRepo;
use crate::domain::services::UserService;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let config = Config::from_env()?;
init_tracing(&config.log_level);
// Infrastructure: create the database pool.
let pool = create_pool(config.database_url.expose_secret()).await?;
sqlx::migrate!("./migrations").run(&pool).await?;
// Infrastructure: create the repository (implements the port).
let user_repo = PostgresUserRepo::new(pool.clone());
// Domain: create the service, injecting the repository.
let user_service = UserService::new(user_repo);
// API: assemble the state and router.
let state = AppState {
config: Arc::new(config.clone()),
db: pool,
user_service,
};
let app = api::routes::router(state);
let addr = format!("0.0.0.0:{}", config.port);
let listener = tokio::net::TcpListener::bind(&addr).await?;
tracing::info!("listening on {}", listener.local_addr()?);
axum::serve(listener, app)
.with_graceful_shutdown(shutdown_signal())
.await?;
Ok(())
}
นี่คือ composition root ของแอปพลิเคชัน: จุดศูนย์กลางเพียงจุดเดียวที่เราเลือก concrete type และประกอบเชื่อมต่อ (wiring) dependency ต่างๆ เข้าด้วยกัน เซอร์วิสของโดเมนจะได้รับ PostgresUserRepo เข้าไปใช้งาน แต่รับรู้เพียงว่ามันคือ “สิ่งใดก็ตามที่อิมพลีเมนต์ UserRepository” หากคุณต้องการสลับไปใช้ฐานข้อมูลอื่น คุณจะแก้ไขเพียงแค่ไฟล์นี้และโมดูล infra/ เท่านั้น โดยที่เลเยอร์โดเมนและเลเยอร์ API ไม่ต้องแตะต้องเลยแม้แต่น้อย ซึ่งเป็นคุณสมบัติที่ยอดเยี่ยมอย่างยิ่งเมื่อระบบเติบโตขึ้น
เส้นทางข้อมูลที่สมบูรณ์
เราลองมาติดตามการทำงานตั้งแต่ต้นจนจบแบบเป็นขั้นเป็นตอน นี่คือสิ่งที่เกิดขึ้นเมื่อไคลเอนต์ส่งคำขอ POST /api/v1/users เข้ามา:
Client sends: { "name": "Alice", "email": "alice@example.com", "password": "secret123" }
1. Axum deserializes into CreateUserDto (api/dtos)
2. ValidatedJson checks: name length, email format, password length
3. Handler parses fields into domain types: UserName, Email
4. Handler calls user_service.register(name, email, &password)
5. Service hashes password on blocking thread
6. Service builds NewUser and calls repo.create(&new_user)
7. Repository executes INSERT via sqlx::query_as!
8. If email is duplicate: sqlx returns unique violation
→ Repository maps to CreateUserError::Duplicate
→ Handler's ? maps to AppError::Conflict
→ Axum returns 409 with error message
9. If successful: repository gets UserRow back from RETURNING clause
→ TryFrom<UserRow> converts to User (domain entity)
10. Service returns User to handler
11. Handler converts User to UserResponse via From trait
12. Axum serializes to JSON and returns 201 Created
Client receives: { "id": "...", "name": "Alice", "email": "alice@example.com", "created_at": "..." }
ทุกขอบเขตถูกแบ่งแยกอย่างเด็ดขาด และนั่นคือสิ่งที่ทำให้แนวทางนี้คุ้มค่ากับจำนวนไฟล์ที่เพิ่มขึ้น แฮนด์เลอร์จัดการเฉพาะ DTO และชนิดข้อมูลโดเมน, เซอร์วิสจัดการเฉพาะชนิดข้อมูลโดเมนและพอร์ต, รีพอสิทอรีจัดการเฉพาะ SQL และชนิดข้อมูลแถวข้อมูลในฐานข้อมูล และการอิมพลีเมนต์ From / TryFrom จะทำหน้าที่เชื่อมผสานข้อมูลระหว่างกัน ไม่มีเลเยอร์ใดก้าวก่ายเข้าไปในรายละเอียดภายในของเลเยอร์อื่น หากรู้สึกเหมือนมีขั้นตอนหลายขั้นตอนสำหรับเอนด์พอยต์เพียงตัวเดียว คุณก็คิดไม่ผิดครับ แต่เมื่อคุณวางโครงสร้างนี้สำเร็จเป็นแบบอย่างได้แล้ว ฟีเจอร์ต่อๆ ไปทุกตัวจะดำเนินไปตามรูปแบบเดียวกันทั้งหมด และความสม่ำเสมอเป็นระเบียบเรียบร้อยนี้จะมอบความคุ้มค่ากลับคืนมาให้อย่างมหาศาล
การขยายขนาด: ฟีเจอร์ที่ใหญ่ขึ้น เซอร์วิสมากขึ้น
เมื่อแอปพลิเคชันของคุณเติบโตและมีฟีเจอร์เพิ่มขึ้น แต่ละฟีเจอร์จะดำเนินรอยตามแพตเทิร์นเดียวกันเสมอ ได้แก่ ชนิดข้อมูลโดเมน, พอร์ต (หากจำเป็น), เซอร์วิส, รีพอสิทอรี, DTO และแฮนด์เลอร์ เมื่อคุณสร้างฟีเจอร์ตามแนวทางนี้ไปสัก 2-3 ฟีเจอร์ โครงสร้างนี้จะกลายเป็นความคุ้นเคยที่คุณสามารถเขียนได้อย่างเป็นธรรมชาติโดยแทบไม่ต้องหยุดคิด
เมื่อถึงจุดหนึ่ง คุณอาจสังเกตเห็นว่าไดเรกทอรีที่รวมศูนย์อย่าง models/, services/, และ repositories/ เริ่มมีความหนาแน่นของไฟล์มากเกินไป ในจังหวะนั้น คุณสามารถจัดกลุ่มโค้ดใหม่ตามแนวฟีเจอร์ (feature slice) ได้ทันที:
src/domain/
├── users/
│ ├── mod.rs
│ ├── model.rs # User, UserId, Email, UserName, NewUser
│ ├── errors.rs # CreateUserError
│ ├── port.rs # UserRepository trait
│ └── service.rs # UserService
├── posts/
│ ├── mod.rs
│ ├── model.rs
│ ├── errors.rs
│ ├── port.rs
│ └── service.rs
ทั้งสองรูปแบบต่างตั้งอยู่บนหลักการพื้นฐานเดียวกันกับที่เราใช้มาตลอดทั้งบท การเลือกระหว่างสองแนวทางนี้จึงเป็นเพียงเรื่องของจำนวนไฟล์และความสะดวกในการค้นหาโค้ด ไม่ใช่เรื่องของความแตกต่างทางสถาปัตยกรรม คำแนะนำของผมคือ: เริ่มต้นด้วยโครงสร้างแบบรวมศูนย์ก่อน แล้วค่อยปรับเป็นโครงสร้างตามแนวฟีเจอร์เมื่อการค้นหาไฟล์ในโฟลเดอร์เดิมเริ่มทำให้คุณรู้สึกเสียเวลา จุดเปลี่ยนที่เหมาะสมมักอยู่ที่ราวๆ 5 ถึง 10 โดเมนคอนเซปต์ แต่เมื่อถึงจุดนั้น คุณจะสัมผัสได้ด้วยตัวเองอย่างแน่นอนครับ
การจัดการข้อผิดพลาด
ถ้าคุณเคยพัฒนาเว็บเซอร์วิสมาระยะหนึ่ง คุณจะตระหนักได้ว่าการจัดการข้อผิดพลาดแท้จริงแล้วคือการตอบสนองความต้องการของผู้รับข้อมูล 2 กลุ่มที่แตกต่างกันโดยสิ้นเชิง: ฝั่งผู้ใช้งาน API ต้องการข้อความแจ้งเตือนที่เข้าใจง่ายเมื่อมีสิ่งใดผิดพลาด นั่นคือรหัสสถานะ HTTP ที่ถูกต้องและคำอธิบายที่ช่วยให้แก้ไขปัญหาได้จริง ขณะที่ฝั่งทีมงานผู้พัฒนาของคุณต้องการภาพรวมเชิงลึกทั้งหมด ไม่ว่าจะเป็น stack trace, สายโซ่ของข้อผิดพลาด (error chain) และบริบทแวดล้อมที่เพียงพอต่อการสืบค้นต้นตอของบั๊ก เคล็ดลับสำคัญจึงอยู่ที่การตอบโจทย์ทั้งสองกลุ่มนี้ไปพร้อมกัน โดยไม่เปิดเผยรายละเอียดการทำงานภายในให้รั่วไหลออกสู่โลกภายนอก
Axum มีแนวทางการออกแบบที่น่าสนใจมากตรงจุดนี้ กล่าวคือ เฟรมเวิร์กกำหนดให้แฮนด์เลอร์ทุกตัวต้องไม่มีวันล้มเหลว (infallible) ในระดับของเฟรมเวิร์ก ซึ่งหมายความว่าแฮนด์เลอร์จะต้องส่งคืน HTTP response ที่สมบูรณ์กลับมาเสมอ ไม่ว่าจะเกิดข้อผิดพลาดใดๆ ขึ้นก็ตาม ในทางปฏิบัติ เราทำได้โดยการคืนค่าเป็น Result<T, E> โดยที่ E จะต้องอิมพลีเมนต์ trait IntoResponse เมื่อใดก็ตามที่แฮนด์เลอร์คืนค่าเป็น Err(e) ทาง Axum จะเรียกใช้ e.into_response() อัตโนมัติเพื่อสร้าง HTTP response สำหรับข้อผิดพลาดนั้นขึ้นมา กลไกนี้เปิดโอกาสให้เราควบคุมรูปแบบของการตอบกลับได้อย่างเบ็ดเสร็จ ซึ่งเป็นสิ่งที่ตรงกับความต้องการของเราอย่างยิ่ง
แพตเทิร์น AppError
แนวคิดนี้มีความตรงไปตรงมา: เราจะสร้าง enum ข้อผิดพลาดส่วนกลางขึ้นมาหนึ่งตัวเพื่อรวบรวมทุกกรณีข้อผิดพลาดที่ API สามารถสร้างขึ้นได้ โดยแฮนด์เลอร์ทุกตัวจะคืนค่าเป็น Result<T, AppError> และโค้ดการอิมพลีเมนต์ IntoResponse บน AppError จะทำหน้าที่จับคู่วาเรียนต์แต่ละตัวเข้ากับรหัสสถานะ HTTP และโครงสร้างบอดี้ของการตอบกลับที่เหมาะสม เรามาดูตัวอย่างการใช้งานจริงกันครับ:
#![allow(unused)]
fn main() {
use std::collections::HashMap;
use axum::http::StatusCode;
use axum::response::{IntoResponse, Response};
use axum::Json;
#[derive(Debug, thiserror::Error)]
pub enum AppError {
#[error("resource not found")]
NotFound,
#[error("{0}")]
Validation(String),
#[error("validation failed")]
ValidationFields(HashMap<String, Vec<String>>),
#[error("authentication required")]
Unauthorized,
#[error("insufficient permissions")]
Forbidden,
#[error("{0}")]
Conflict(String),
#[error(transparent)]
Internal(#[from] anyhow::Error),
}
impl IntoResponse for AppError {
fn into_response(self) -> Response {
let (status, error_type, message) = match &self {
AppError::NotFound => (
StatusCode::NOT_FOUND,
"not_found",
self.to_string(),
),
AppError::Validation(msg) => (
StatusCode::BAD_REQUEST,
"validation_error",
msg.clone(),
),
AppError::ValidationFields(ref fields) => {
let body = serde_json::json!({
"error": {
"type": "validation_error",
"message": "request validation failed",
"fields": fields,
}
});
return (StatusCode::BAD_REQUEST, Json(body)).into_response();
}
AppError::Unauthorized => (
StatusCode::UNAUTHORIZED,
"unauthorized",
self.to_string(),
),
AppError::Forbidden => (
StatusCode::FORBIDDEN,
"forbidden",
self.to_string(),
),
AppError::Conflict(msg) => (
StatusCode::CONFLICT,
"conflict",
msg.clone(),
),
AppError::Internal(err) => {
// Log the full error chain for debugging. This is the only
// place where the real error details are visible.
tracing::error!(error = ?err, "internal server error");
(
StatusCode::INTERNAL_SERVER_ERROR,
"internal_error",
"an internal error occurred".to_string(),
)
}
};
let body = serde_json::json!({
"error": {
"type": error_type,
"message": message,
}
});
(status, Json(body)).into_response()
}
}
}
ชิ้นส่วนที่สำคัญที่สุดในโค้ดชุดนี้คือวาเรียนต์ Internal ซึ่งทำหน้าที่ห่อหุ้ม anyhow::Error เอาไว้ ทำให้สามารถรองรับชนิดข้อมูลข้อผิดพลาดรูปแบบใดก็ได้พร้อมสายโซ่ของบริบท (context chain) เมื่อเกิดข้อผิดพลาดภายในระบบ เราจะบันทึกรายละเอียดทั้งหมดลงในระบบล็อก (ทั้ง error chain และ backtrace หากมี) แต่จะส่งกลับไปยังผู้ใช้งานภายนอกเพียงแค่ข้อความทั่วไปเท่านั้น นี่คือวิธีป้องกันข้อมูลภายในรั่วไหลที่มีประสิทธิภาพสูง คุณคงไม่อยากให้โครงสร้างสกีมาของฐานข้อมูลหรือเส้นทางไฟล์ภายในเซิร์ฟเวอร์หลุดรอดออกไปใน API response เพราะผมเคยเห็นเหตุการณ์นั้นเกิดขึ้นบน production มาแล้ว และไม่ใช่เรื่องน่าอภิรมย์เลยในการต้องตอบคำถามกับทีมดูแลความปลอดภัย (security team)
type alias เพื่อความสะดวก
แม้จะดูเหมือนเป็นเรื่องเล็กน้อย แต่วิธีนี้ช่วยเพิ่มความสบายตาและทำให้อ่านโค้ดได้ง่ายขึ้นอย่างมาก เราจะสร้าง type alias ขึ้นมาเพื่อช่วยให้ signature ของแฮนด์เลอร์มีความกระชับ:
#![allow(unused)]
fn main() {
pub type AppResult<T> = Result<T, AppError>;
}
ทำให้แฮนด์เลอร์ของเราสามารถเขียนได้อย่างสะอาดตาเช่นนี้:
#![allow(unused)]
fn main() {
async fn get_user(
State(state): State<AppState>,
Path(id): Path<Uuid>,
) -> AppResult<Json<UserResponse>> {
let user = state.user_service
.get_by_id(UserId::from_uuid(id))
.await?
.ok_or(AppError::NotFound)?;
Ok(Json(user.into()))
}
}
สังเกตว่าโอเปอเรเตอร์ ? สามารถทำงานร่วมกันได้อย่างราบรื่นทันที ผ่านทางการอิมพลีเมนต์ From บน AppError ซึ่งเราจะไปดูกันในหัวข้อถัดไป
ห่วงโซ่การแปลงข้อผิดพลาด
ในสถาปัตยกรรมแบบเลเยอร์ ข้อผิดพลาดจะเริ่มต้นจากชั้นล่างสุด (เลเยอร์อินฟราสตรักเจอร์) ส่งผ่านขึ้นมายังเลเยอร์โดเมน และสุดท้ายเดินทางมาถึงเลเยอร์ API เพื่อแปลงรูปไปเป็น HTTP response แต่ละเลเยอร์จะมีชนิดข้อมูลข้อผิดพลาดเป็นของตัวเอง และเราจะใช้การอิมพลีเมนต์ trait From ในการแปลงข้อมูลข้ามขอบเขตระหว่างกัน
ภาพรวมของสายโซ่การแปลงข้อผิดพลาดสำหรับการดำเนินการ “สร้างผู้ใช้ใหม่” (create user):
sqlx::Error
→ CreateUserError (domain)
→ AppError (api)
→ HTTP Response
เลเยอร์อินฟราสตรักเจอร์จะดักจับข้อผิดพลาดของฐานข้อมูล แล้วแปลงให้อยู่ในรูปที่เลเยอร์โดเมนเข้าใจ:
#![allow(unused)]
fn main() {
// In the repository implementation
.map_err(|e| match e {
sqlx::Error::Database(ref db_err) if db_err.is_unique_violation() => {
CreateUserError::Duplicate { email: req.email.clone() }
}
other => CreateUserError::Unknown(other.into()),
})
}
จากนั้นเลเยอร์ API จะทำหน้าที่แปลงข้อผิดพลาดระดับโดเมนนั้นให้กลายเป็น AppError:
#![allow(unused)]
fn main() {
impl From<CreateUserError> for AppError {
fn from(err: CreateUserError) -> Self {
match err {
CreateUserError::Duplicate { email } => {
AppError::Conflict(
format!("a user with email {} already exists", email.as_str())
)
}
CreateUserError::Unknown(inner) => AppError::Internal(inner),
}
}
}
}
เมื่อมีการอิมพลีเมนต์ From ไว้อย่างครบถ้วน แฮนด์เลอร์ของเราจะสามารถใช้โอเปอเรเตอร์ ? ได้ทันที และปล่อยให้คอมไพเลอร์จัดการกระบวนการแปลงข้อมูลทั้งหมดให้โดยอัตโนมัติ โดยไม่ต้องมานั่งแปลงค่าด้วยตัวเองให้รกโค้ด:
#![allow(unused)]
fn main() {
async fn create_user(
State(state): State<AppState>,
ValidatedJson(payload): ValidatedJson<CreateUserDto>,
) -> AppResult<(StatusCode, Json<UserResponse>)> {
let user = state.user_service.register(payload).await?; // ? handles the full chain
Ok((StatusCode::CREATED, Json(user.into())))
}
}
thiserror กับ anyhow
คุณอาจสงสัยว่าเหตุใดเราจึงเลือกใช้เครตจัดการข้อผิดพลาดถึง 2 ตัวคู่กัน ในความเป็นจริง เครตทั้งสองถูกออกแบบมาเพื่อทำหน้าที่เสริมซึ่งกันและกันอย่างสมบูรณ์ และจากประสบการณ์ของผม แอปพลิเคชันที่มีโครงสร้างที่ดีควรนำทั้งสองตัวมาใช้งานร่วมกันอย่างถูกจุด:
thiserror เหมาะสำหรับข้อผิดพลาดที่โค้ดของคุณจำเป็นต้องนำไป match หรือตรวจสอบเงื่อนไข เครตนี้จะช่วยสร้างโค้ดการอิมพลีเมนต์ trait Display และ Error ให้จากนิยาม enum ของคุณโดยอัตโนมัติ เราจึงเลือกใช้มันกับข้อผิดพลาดในระดับโดเมน (CreateUserError, AuthError), ใช้กับ enum AppError, รวมถึงชนิดข้อมูลข้อผิดพลาดใดๆ ที่ฝั่งผู้เรียกจำเป็นต้องแยกแยะวาเรียนต์เพื่อจัดการต่ออย่างจำเพาะเจาะจง
anyhow เหมาะสำหรับข้อผิดพลาดที่โค้ดของคุณต้องการเพียงแค่ส่งต่อ (propagate) ขึ้นไปด้านบน โดยมอบชนิดข้อมูล anyhow::Error ตัวเดียวที่สามารถบรรจุข้อผิดพลาดรูปแบบใดก็ได้ พร้อมแนบข้อความบริบทแวดล้อมเพื่อร้อยเรียงเป็นคำอธิบายสิ่งที่เกิดขึ้น เราจึงใช้มันกับวาเรียนต์ Internal ซึ่งเป็น catch-all ของ AppError และใช้ในโค้ดอินฟราสตรักเจอร์เมื่อเราต้องการเพิ่มบริบทโดยไม่ต้องมานั่งประกาศ enum วาเรียนต์ใหม่สำหรับทุกๆ ความผิดพลาดที่เป็นไปได้
หลักคิดง่ายๆ (rule of thumb) ที่ผมยึดถือเสมอคือ: ใช้ thiserror บริเวณขอบเขตที่ผู้เรียกจำเป็นต้องตัดสินใจตามวาเรียนต์ของข้อผิดพลาด และใช้ anyhow สำหรับกรณี “ข้อผิดพลาดส่วนที่เหลือทั้งหมด” ที่ต้องการเพียงบันทึกลงในระบบล็อกและรายงานผลเท่านั้น
การเพิ่มบริบทด้วย anyhow
Trait anyhow::Context ช่วยให้คุณสามารถแนบข้อความบริบทที่มนุษย์อ่านเข้าใจง่ายเข้ากับข้อผิดพลาดในระหว่างที่มันถูกส่งต่อขึ้นไปตาม call stack แม้จะดูเหมือนเป็นงานที่ต้องเขียนเพิ่มขึ้นเล็กน้อยในตอนพัฒนา แต่มันมีประโยชน์มหาศาลในยามที่ต้องดีบั๊ก เพราะมันไม่ได้บอกแค่ว่าอะไรล้มเหลว แต่บอกว่าทำไมโค้ดถึงพยายามทำสิ่งนั้นตั้งแต่แรก
#![allow(unused)]
fn main() {
use anyhow::Context;
pub async fn create_pool(database_url: &str) -> anyhow::Result<PgPool> {
PgPoolOptions::new()
.max_connections(10)
.acquire_timeout(Duration::from_secs(3))
.connect(database_url)
.await
.context("failed to connect to the database")
}
}
เมื่อข้อผิดพลาดนี้เดินทางมาถึงวาเรียนต์ Internal ของ AppError และถูกบันทึกลงล็อก เอาต์พุตที่ได้จะประกอบด้วยทั้งข้อผิดพลาดตั้งต้น (“connection refused”) และข้อความบริบท (“failed to connect to the database”) ซึ่งนี่คือความแตกต่างระหว่างการนั่งมองข้อความแจ้งเตือนที่ชวนสับสน กับการรู้ได้ทันทีว่าควรเริ่มตรวจสอบที่จุดใด
หลักสังเขป (Rules of thumb)
ห้ามเรียกใช้ unwrap() หรือ expect() ในโค้ดเส้นทางประมวลผลคำขอ HTTP โดยเด็ดขาด อาการ panic ในแฮนด์เลอร์ไม่ได้ส่งผลกระทบต่อคำขอนั้นเพียงคำขอเดียว หาก panic เกิดขึ้นในระหว่างที่กำลังถือ mutex หรือทรัพยากรส่วนกลางอื่นๆ มันอาจทำให้ทรัพยากรนั้นกลายสภาพเป็นพิษ (poisoned) และลุกลามสร้างความเสียหายไปยังคำขออื่นๆ ในระบบ ผมเคยเห็นบั๊กที่เกิดจากการใช้ unwrap() อย่างประมาทมามากพอ จนต้องขอย้ำเตือนเรื่องนี้อย่างจริงจัง: จงส่งผ่านข้อผิดพลาดด้วยชนิดข้อมูล Result เสมอ
อย่าเปิดเผยข้อความข้อผิดพลาดภายในให้ผู้ใช้ภายนอกเห็นโดยเด็ดขาด ข้อผิดพลาดของฐานข้อมูล, เส้นทางไดเรกทอรีไฟล์, stack trace และชื่อเซอร์วิสภายใน ล้วนเป็นข้อมูลที่มีมูลค่าสำหรับผู้ไม่ประสงค์ดี จงบันทึกข้อมูลเหล่านี้ลงในระบบล็อกที่ระดับ error สำหรับทีมงานของคุณ และส่งคืนเพียงข้อความทั่วไปอย่าง “internal error” ให้แก่ผู้ใช้งานภายนอก
ใช้ thiserror สำหรับข้อผิดพลาดที่มีโครงสร้างชัดเจน และใช้ anyhow สำหรับการส่งต่อแบบ catch-all หลีกเลี่ยงการใช้ anyhow เป็นชนิดข้อมูลผลลัพธ์ของแฮนด์เลอร์โดยตรง เพราะจะทำให้คุณสูญเสียความสามารถในการจับคู่ข้อผิดพลาดแต่ละประเภทเข้ากับรหัสสถานะ HTTP ที่เหมาะสม แต่ควรนำมาใช้ภายในวาเรียนต์ AppError::Internal แทน
ใช้ประโยชน์จาก #[from] เพื่อการแปลงชนิดข้อมูลอัตโนมัติ แอตทริบิวต์ #[from] ของ thiserror จะช่วยสร้างโค้ดการอิมพลีเมนต์ From ให้โดยอัตโนมัติ ทำให้โอเปอเรเตอร์ ? สามารถแปลงข้อผิดพลาดข้ามชนิดข้อมูลได้ทันที ช่วยให้โค้ดในแฮนด์เลอร์ของคุณมีความกระชับและมุ่งเน้นไปที่เส้นทางการทำงานปกติ (happy path) ได้อย่างเต็มที่
เพิ่มข้อความบริบทด้วย .context() อย่างสม่ำเสมอในโค้ดเลเยอร์อินฟราสตรักเจอร์ ต้นทุนเพียงเล็กน้อยในการเขียนข้อความบริบทกำกับ จะมอบผลตอบแทนที่คุ้มค่าอย่างมหาศาลเวลาที่คุณต้องตื่นขึ้นมาดีบั๊กระบบ production ตอนตีสอง แล้วล็อกของระบบระบุชัดเจนว่า “failed to persist user registration” แทนที่จะเป็นเพียงแค่ข้อความแห้งๆ อย่าง “connection reset by peer” เชื่อผมเถอะครับว่ามันคุ้มค่าจริงๆ
เลเยอร์ฐานข้อมูล
หากคุณเคยทำงานในโปรเจกต์ที่มีคิวรี SQL กระจัดกระจายอยู่ตามฟังก์ชันแฮนด์เลอร์ต่างๆ คุณคงรู้ดีว่ามันกลายเป็นฝันร้ายได้เร็วขนาดไหน ในช่วงแรกมันอาจดูเหมือนทำงานได้รวดเร็ว ฟีเจอร์ต่างๆ ถูกปล่อยออกไปได้อย่างราบรื่น แต่เมื่อผ่านไปไม่กี่เดือน คุณกลับต้องมานั่งไล่ค้นหาไฟล์นับสิบเพื่อแก้ชื่อคอลัมน์เพียงจุดเดียว แถมชุดทดสอบยังต้องพึ่งพาฐานข้อมูลที่กำลังรันอยู่แทบทุกการทดสอบ ซึ่งผมเองก็เคยเจอปัญหานี้มาแล้ว และบอกได้เลยว่าไม่ใช่เรื่องน่าอภิรมย์เลย
ในบทนี้ เราจะมาสร้างเลเยอร์ฐานข้อมูลที่สะอาดและแยกความรับผิดชอบอย่างเป็นระเบียบด้วย SQLx ซึ่งเป็นตัวเลือกยอดนิยมที่สุดสำหรับแอปพลิเคชัน Axum อย่างไรก็ดี หลักการเหล่านี้สามารถนำไปประยุกต์ใช้ได้กับทุกเครตฐานข้อมูลที่คุณเลือกใช้
การตั้งค่าพูลการเชื่อมต่อ
เราคงไม่ต้องการให้ทุกคำขอที่ส่งเข้ามาต้องเปิดการเชื่อมต่อฐานข้อมูลใหม่ตั้งแต่ต้น เพราะนั่นหมายถึง overhead จากกระบวนการ TCP handshake, การเจรจา TLS และอาจรวมถึงการยืนยันตัวตน (authentication) ทั้งหมดนี้เกิดขึ้นก่อนที่คุณจะได้เริ่มรันคิวรีด้วยซ้ำ เราจึงต้องดูแลรักษาพูลการเชื่อมต่อ (connection pool) ที่สร้างเตรียมไว้ล่วงหน้า เพื่อให้แต่ละคำขอสามารถยืมการเชื่อมต่อไปใช้งานแล้วส่งคืนกลับเข้าพูลได้
#![allow(unused)]
fn main() {
use anyhow::Context;
use sqlx::postgres::{PgPool, PgPoolOptions};
use std::time::Duration;
pub async fn create_pool(database_url: &str) -> anyhow::Result<PgPool> {
let pool = PgPoolOptions::new()
.max_connections(10)
.min_connections(2)
.acquire_timeout(Duration::from_secs(3))
.idle_timeout(Duration::from_secs(600))
.connect(database_url)
.await
.context("failed to connect to the database")?;
Ok(pool)
}
}
เราควรกำหนดจำนวนการเชื่อมต่อไว้เท่าไรดี? คำตอบขึ้นอยู่กับระดับการทำงานพร้อมกัน (concurrency) ของระบบและขีดความสามารถที่เซิร์ฟเวอร์ฐานข้อมูลจะรับไหว โดยปกติ PostgreSQL จะมีขีดจำกัดเริ่มต้นที่ 100 การเชื่อมต่อ และแต่ละการเชื่อมต่อก็สิ้นเปลืองหน่วยความจำฝั่งเซิร์ฟเวอร์ จุดเริ่มต้นที่ดีคือการกำหนดไว้ที่ 2 ถึง 4 การเชื่อมต่อต่อ 1 คอร์ CPU บนแอปพลิเคชันเซิร์ฟเวอร์ของคุณ จากนั้นค่อยปรับจูนตามสัดส่วนเวลาจริงที่คำขอใช้รอผลลัพธ์จากฐานข้อมูลเทียบกับเวลาที่ใช้ประมวลผลงานอื่น ตัวอย่างเช่น บนอินสแตนซ์ขนาด 4 คอร์ทั่วไป คุณอาจเริ่มต้นที่ 8 ถึง 16 การเชื่อมต่อ และหากคุณรันหลายอินสแตนซ์อยู่หลัง Load Balancer อย่าลืมคำนวณจำนวนการเชื่อมต่อรวมทั้งหมดของทุกอินสแตนซ์ให้อยู่ต่ำกว่าขีดจำกัดสูงสุดของฐานข้อมูลเสมอ
ไมเกรชัน
ไฟล์ไมเกรชัน (migration) ของเราควรมีการกำหนดเวอร์ชัน ทำซ้ำได้ (reproducible) และในทางอุดมคติคือสามารถรันได้โดยอัตโนมัติตอนเริ่มต้นระบบ โดย SQLx มีระบบไมเกรชันในตัวที่จะอ่านไฟล์ .sql จากไดเรกทอรีที่กำหนดและนำไปประยุกต์ใช้ตามลำดับเวลา
migrations/
├── 20240101000000_create_users.sql
├── 20240102000000_create_posts.sql
└── 20240103000000_add_user_bio.sql
โครงสร้างไมเกรชันที่ดีควรมีหน้าตาอย่างไร? โดยส่วนตัวผมมักจะกำหนดค่าเริ่มต้น (default values) ที่สมเหตุสมผลให้กับคอลัมน์ใหม่เสมอ เลือกใช้ UUID แทนเลขจำนวนเต็มที่เพิ่มค่าอัตโนมัติ (auto-incrementing integers) สำหรับคีย์หลัก (ซึ่งช่วยให้การสุ่มเดา ID ทำได้ยากขึ้น แม้ว่าแท้จริงแล้วระบบตรวจสอบสิทธิ์ต่างหากที่เป็นปราการปกป้องข้อมูลของคุณ) และจัดเก็บไทม์สแตมป์พร้อมข้อมูลเขตเวลา (timezone) เสมอ:
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
email VARCHAR(255) UNIQUE NOT NULL,
name VARCHAR(100) NOT NULL,
password_hash VARCHAR(255) NOT NULL,
bio TEXT,
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_users_email ON users(email);
-- Automatically update the updated_at timestamp on row modification
CREATE OR REPLACE FUNCTION update_updated_at_column()
RETURNS TRIGGER AS $$
BEGIN
NEW.updated_at = NOW();
RETURN NEW;
END;
$$ LANGUAGE plpgsql;
CREATE TRIGGER update_users_updated_at
BEFORE UPDATE ON users
FOR EACH ROW
EXECUTE FUNCTION update_updated_at_column();
ทำไมจึงควรใช้ทริกเกอร์ของฐานข้อมูลในการจัดการ updated_at? เพราะวิธีนี้ช่วยรับประกันความถูกต้องสม่ำเสมอ ไม่ว่าโค้ดเส้นทางใดจะเข้ามาแก้ไขแถวข้อมูลก็ตาม แม้กระทั่งในกรณีที่มีคนรันคำสั่ง SQL แก้ไขข้อมูลในฐานข้อมูลโดยตรงด้วยมือ (ซึ่งเชื่อผมเถอะว่าเกิดขึ้นจริงแน่นอน) ไทม์สแตมป์ก็จะยังคงได้รับการอัปเดตอย่างถูกต้องเสมอ
การปั้นสกีมาอย่างประณีต
ไมเกรชันตัวอย่างด้านบนเป็นเพียงจุดเริ่มต้น ยังมีเทคนิคสำคัญอีกสองสามประการที่สามารถเพิ่มเข้าไปในไมเกรชันตั้งแต่ตอนนี้ได้อย่างง่ายดาย แต่หากปล่อยไว้แล้วต้องมาย้อนแก้ในภายหลังจะยุ่งยากและน่าปวดหัวอย่างมาก ผมจะขอสรุปเทคนิคที่พบว่ามีประโยชน์มากที่สุดดังนี้:
ความเป็นเอกลักษณ์โดยไม่คำนึงถึงตัวพิมพ์เล็กใหญ่ (Case-insensitive uniqueness) หากชื่อผู้ใช้และอีเมลต้องไม่ซ้ำกันโดยไม่สนใจตัวพิมพ์เล็กใหญ่ ควรกำหนดข้อจำกัดนี้ไว้ที่ระดับฐานข้อมูลโดยตรง การใช้ส่วนขยาย citext ของ PostgreSQL หรือใช้ ICU collation เช่น COLLATE "und-ci-ai-ks-kc" จะช่วยป้องกันไม่ให้ระบบยอมรับทั้ง “Alice” และ “alice” เข้ามาพร้อมกัน ผมเคยเจอบั๊กจากการพึ่งพาการแปลงสตริงเป็นตัวพิมพ์เล็กในเลเยอร์แอปพลิเคชันเพียงอย่างเดียวมาแล้ว เพราะการ insert ด้วยคำสั่ง SQL โดยตรงหรือการเข้าถึงจากเซอร์วิสอื่นสามารถข้ามการตรวจสอบนี้ไปได้อย่างสิ้นเชิง
ฟังก์ชันทริกเกอร์ที่นำกลับมาใช้ซ้ำได้ หากมีหลายตารางที่ต้องอัปเดตฟิลด์ updated_at ในลักษณะเดียวกัน ให้เขียนฟังก์ชันทริกเกอร์แยกไว้เพียงจุดเดียวแล้วนำไปผูกซ้ำกับตารางต่างๆ นั่นคือสิ่งที่ฟังก์ชัน update_updated_at_column() ด้านบนทำไว้ คุณเพียงแค่สร้างทริกเกอร์ไปผูกกับแต่ละตารางที่มีคอลัมน์ updated_at ก็เพียงพอ
เลือกประเภทดัชนี (Index) ให้เหมาะสม สำหรับคอลัมน์ชนิดอาร์เรย์ เช่น แท็ก การใช้อินเด็กซ์แบบ GIN จะช่วยให้คิวรีตรวจสอบการมีอยู่ของสมาชิก (@>, &&) ทำงานได้อย่างรวดเร็ว สำหรับคอลัมน์ค้นหาข้อความ ให้พิจารณาใช้ tsvector ร่วมกับอินเด็กซ์ GIN ส่วนอินเด็กซ์มาตรฐานแบบ B-tree จะเหมาะสมที่สุดสำหรับคิวรีเปรียบเทียบความเท่ากัน (equality) และการค้นหาแบบช่วง (range queries) บนคอลัมน์ข้อมูลทั่วไป
การเลือกประเภท ID อย่างรอบคอบ แม้ UUID จะเป็นตัวเลือกเริ่มต้นที่ผมแนะนำในคู่มือนี้ แต่ก็มีบางกรณีที่ ID แบบเรียงลำดับตัวเลข (bigserial) เหมาะสมกว่า เช่น เมื่อระบบภายนอกกำหนดให้ต้องใช้ตัวเลข หรือในตารางที่มีการเขียนข้อมูลสูงมาก (write-heavy) ซึ่งความสุ่มของ UUID ทั่วไปอาจส่งผลให้เกิดการแยกหน้า (page split) บนอินเด็กซ์ B-tree แต่สำหรับตารางที่เน้นการเขียน UUIDv7 คือทางเลือกที่น่าสนใจอย่างยิ่ง เพราะให้ทั้งความเป็นเอกลักษณ์ระดับสากลและยังเรียงลำดับตามเวลาได้ดีต่อการทำดัชนี (index-friendly) เนื่องจากมีการฝังไทม์สแตมป์ไว้ภายใน ทั้งนี้ PostgreSQL 18+ รองรับฟังก์ชัน uuidv7() ในตัว ส่วน PostgreSQL 17 หรือรุ่นก่อนหน้า คุณสามารถสร้างค่า UUIDv7 ในเลเยอร์แอปพลิเคชันผ่านเครต uuid (เปิดฟีเจอร์ v7) หรือติดตั้งส่วนขยายของฐานข้อมูลเพิ่มเติมได้
หากคุณต้องการดูตัวอย่างการนำแพตเทิร์นเหล่านี้ไปใช้จริงในแอปพลิเคชัน คลังโค้ด launchbadge/realworld-axum-sqlx มีคำอธิบายไมเกรชันที่เขียนไว้อย่างยอดเยี่ยมและคุ้มค่าแก่การศึกษาเป็นอย่างยิ่ง
การรันไมเกรชัน
โดยทั่วไป ผมนิยมรันไมเกรชันในจังหวะเริ่มต้นการทำงานของแอปพลิเคชัน:
#![allow(unused)]
fn main() {
sqlx::migrate!("./migrations")
.run(&pool)
.await
.context("failed to run database migrations")?;
}
แมโคร migrate! จะฝังไฟล์ไมเกรชันเข้าไปในไบนารีตั้งแต่ตอนคอมไพล์ ทำให้คุณไม่จำเป็นต้องคัดลอกไดเรกทอรีไมเกรชันตามไปพร้อมกับแอปพลิเคชัน ช่วยลดภาระและขั้นตอนที่ต้องกังวลในระหว่างการดีพลอยต์ลงไปได้หนึ่งอย่าง
การตรวจสอบควิวรีตอนคอมไพล์ใน CI
มีจุดหนึ่งที่อาจทำให้คุณสะดุดได้: แมโคร query! และ query_as! ของ SQLx จะตรวจสอบความถูกต้องของคำสั่ง SQL เทียบกับฐานข้อมูลจริงตั้งแต่ตอนคอมไพล์ นั่นหมายความว่าสภาพแวดล้อม CI ของคุณจะต้องสามารถเข้าถึงฐานข้อมูลได้ในระหว่างการบิลด์ ซึ่งเราสามารถจัดการปัญหานี้ได้ 2 แนวทาง
แนวทางที่ผมแนะนำสำหรับ CI คือการใช้ โหมดออฟไลน์ (offline mode) โดยให้รันคำสั่ง cargo sqlx prepare บนเครื่องของคุณ (คำสั่งนี้จะเชื่อมต่อไปยังฐานข้อมูลที่กำลังรันอยู่เพื่อสร้างไดเรกทอรี .sqlx/ ซึ่งเก็บแคชเมตาดาตาของคิวรีไว้) จากนั้นจึง commit ไดเรกทอรีดังกล่าวเข้าสู่ระบบควบคุมเวอร์ชัน (version control) และใน CI ให้ตั้งค่าตัวแปรสภาพแวดล้อม SQLX_OFFLINE=true ซึ่งจะทำให้แมโครหันมาใช้เมตาดาตาจากแคชแทนการเชื่อมต่อฐานข้อมูลจริง นอกจากนี้ควรเพิ่มขั้นตอน cargo sqlx prepare --check ใน CI pipeline เพื่อตรวจสอบว่าแคชเมตาดาตายังคงซิงก์ตรงกับคำสั่งคิวรีและไฟล์ไมเกรชันล่าสุดอยู่เสมอ
อีกทางเลือกหนึ่งคือการสตาร์ตฐานข้อมูลจำลองขึ้นมาใน CI (ผ่าน Docker หรือ service container ของ CI) แล้วกำหนด DATABASE_URL เพื่อให้แมโครเชื่อมต่อไปตรวจสอบได้โดยตรง วิธีนี้ตั้งค่าง่ายกว่า แต่อาจทำให้การบิลด์ช้าลงและเสี่ยงต่อปัญหาความไม่เสถียร (flaky) มากกว่า
หมายเหตุเรื่องไมเกรชันตอนเริ่มระบบ
การสั่งรันไมเกรชันตอนเริ่มต้นระบบทำงานได้ดีเยี่ยมสำหรับการดีพลอยต์แบบอินสแตนซ์เดี่ยวและในระหว่างการพัฒนา แต่หากคุณรันหลายอินสแตนซ์พร้อมกันบน Production คุณควรรู้ว่าทุกอินสแตนซ์จะพยายามรันไมเกรชันพร้อมกันตอนเปิดเครื่อง แม้ว่า SQLx จะป้องกันปัญหานี้ด้วยการใช้ Advisory Lock เพื่อให้มีเพียงอินสแตนซ์เดียวเท่านั้นที่ได้รันไมเกรชันจริง แต่ในบางสถานการณ์ (โดยเฉพาะการดีพลอยต์แบบ Rolling Update) การแยกกระบวนการไมเกรชันออกมาเป็นงานเดี่ยวๆ (Migration Job) หรือรันผ่าน Kubernetes Init Container จะช่วยให้ควบคุมกระบวนการและจัดการข้อผิดพลาดได้รัดกุมกว่า เราจะไปเจาะลึกประเด็นนี้กันต่อในบท การดีพลอยต์
แพตเทิร์นรีพอสิทอรี
นี่เป็นหนึ่งในแพตเทิร์นที่ผมชอบมากที่สุดในการจัดระเบียบตรรกะการเข้าถึงฐานข้อมูล รีพอสิทอรี (Repository) คือ struct ที่ทำหน้าที่เป็นเจ้าของและควบคุมการเข้าถึงฐานข้อมูลทั้งหมดสำหรับแนวคิดของโดเมนนั้นๆ โดยจะถือการอ้างอิงไปยังพูลการเชื่อมต่อ และมีเมธอดที่ตรงกับความต้องการทางธุรกิจจริงๆ เช่น การสร้างข้อมูล, การค้นหาตามเงื่อนไข, การอัปเดต และการลบ
#![allow(unused)]
fn main() {
#[derive(Clone)]
pub struct UserRepository {
pool: PgPool,
}
impl UserRepository {
pub fn new(pool: PgPool) -> Self {
Self { pool }
}
pub async fn create(&self, req: &CreateUserRequest) -> Result<User, CreateUserError> {
let row = sqlx::query_as!(
UserRow,
r#"
INSERT INTO users (id, email, name, password_hash)
VALUES ($1, $2, $3, $4)
RETURNING id, email, name, password_hash, bio, created_at, updated_at
"#,
Uuid::new_v4(),
req.email.as_str(),
req.name.as_str(),
&req.password_hash,
)
.fetch_one(&self.pool)
.await
.map_err(|e| match e {
sqlx::Error::Database(ref db_err) if db_err.is_unique_violation() => {
CreateUserError::Duplicate { email: req.email.clone() }
}
other => CreateUserError::Unknown(other.into()),
})?;
row.try_into()
.map_err(|e: anyhow::Error| CreateUserError::Unknown(e))
}
pub async fn find_by_id(&self, id: &UserId) -> anyhow::Result<Option<User>> {
let row = sqlx::query_as!(
UserRow,
r#"
SELECT id, email, name, password_hash, bio, created_at, updated_at
FROM users
WHERE id = $1
"#,
id.as_uuid(),
)
.fetch_optional(&self.pool)
.await
.context("failed to fetch user by id")?;
row.map(TryInto::try_into).transpose()
}
pub async fn find_by_email(&self, email: &Email) -> anyhow::Result<Option<User>> {
let row = sqlx::query_as!(
UserRow,
r#"
SELECT id, email, name, password_hash, bio, created_at, updated_at
FROM users
WHERE email = $1
"#,
email.as_str(),
)
.fetch_optional(&self.pool)
.await
.context("failed to fetch user by email")?;
row.map(TryInto::try_into).transpose()
}
pub async fn update(
&self,
id: &UserId,
name: Option<&UserName>,
bio: Option<&str>,
) -> anyhow::Result<Option<User>> {
let row = sqlx::query_as!(
UserRow,
r#"
UPDATE users
SET name = COALESCE($2, name),
bio = COALESCE($3, bio)
WHERE id = $1
RETURNING id, email, name, password_hash, bio, created_at, updated_at
"#,
id.as_uuid(),
name.map(|n| n.as_str()),
bio,
)
.fetch_optional(&self.pool)
.await
.context("failed to update user")?;
row.map(TryInto::try_into).transpose()
}
}
}
มีข้อสังเกตและแพตเทิร์นสำคัญหลายประการในโค้ดชุดนี้ที่ควรเน้นย้ำ:
คิวรีที่ตรวจสอบความถูกต้องตั้งแต่ตอนคอมไพล์ (Compile-time verified queries) แมโคร query_as! จะตรวจสอบความถูกต้องของคำสั่ง SQL เทียบกับสกีมาจริงในฐานข้อมูลตั้งแต่ตอนคอมไพล์ พร้อมสร้างโค้ดสำหรับแมปชนิดข้อมูลระหว่างคอลัมน์ผลลัพธ์กับฟิลด์ของ struct ให้โดยอัตโนมัติ โดยไม่ต้องอาศัยเทรต FromRow เพราะแมโครจะสร้างการแมปให้โดยตรงตามชื่อและชนิดข้อมูลของแต่ละคอลัมน์ หากคุณเปลี่ยนชื่อคอลัมน์ในไมเกรชันแต่ลืมตามไปแก้ในคิวรี โค้ดจะคอมไพล์ไม่ผ่านทันที ซึ่งผมมองว่านี่คือฟีเจอร์ที่ทรงพลังและมีประโยชน์ที่สุดของ SQLx (แต่หากคุณเลือกใช้ฟังก์ชัน query_as::<_, UserRow>(sql) แบบไม่ผ่านแมโคร การแมปข้อมูลจะใช้เทรต FromRow ณ เวลาทำงานหรือรันไทม์แทน)
แยกชนิดข้อมูลสำหรับแถวฐานข้อมูลออกจากโดเมน (Dedicated row types) struct UserRow มีโครงสร้างที่ตรงกับคอลัมน์ในตารางฐานข้อมูลโดยตรง การ derive sqlx::FromRow นั้นไม่จำเป็นเมื่อใช้ query_as! แต่การใส่ไว้ก็ไม่มีผลเสีย และยังมีประโยชน์หากคุณต้องการเรียกใช้ฟังก์ชันคิวรีแบบปกติในจุดอื่นด้วย ส่วนชนิดข้อมูลระดับโดเมนอย่าง User จะใช้ประโยชน์จากนิวไทป์ (newtype) สำหรับฟิลด์ต่างๆ และอาจมีชื่อฟิลด์ที่แตกต่างออกไป การสร้างการแปลงข้อมูลผ่าน TryFrom<UserRow> for User จึงทำหน้าที่เป็นสะพานเชื่อมระหว่างสองโลกนี้ ดังที่เราได้อธิบายไว้ในบท การสร้างแบบจำลองโดเมน ว่าทำไมเราจึงเลือกใช้ TryFrom แทน From เพราะข้อมูลในฐานข้อมูลเก่าอาจมีบางค่าที่ไม่สอดคล้องกับเงื่อนไขคงสภาพ (invariant) ของโดเมนในปัจจุบัน
เลือกใช้ fetch_optional สำหรับการค้นหา เมื่อค้นหาข้อมูลด้วย ID หรืออีเมล ควรเลือกใช้ fetch_optional แทน fetch_one เสมอ เนื่องจากการไม่พบเรคคอร์ดถือเป็นกรณีปกติทั่วไป ไม่ใช่ข้อผิดพลาดของระบบ การคืนค่าเป็น Option<User> จะเปิดโอกาสให้โค้ดส่วนที่เรียกใช้ตัดสินใจเองว่ากรณี ‘หาไม่พบ’ นั้นถือเป็นปัญหาในบริบทดังกล่าวหรือไม่
ใช้ COALESCE สำหรับการอัปเดตข้อมูลบางส่วน (Partial updates) ฟังก์ชัน SQL COALESCE จะช่วยรักษาค่าเดิมเอาไว้หากพารามิเตอร์ที่ส่งเข้ามาเป็น NULL ทำให้คุณสามารถทำ partial update ได้โดยไม่จำเป็นต้องอ่านข้อมูลเดิมขึ้นมาก่อน อย่างไรก็ดี มีข้อจำกัดสำคัญที่ต้องตระหนัก: วิธีนี้ไม่สามารถแยกความแตกต่างระหว่าง ‘ผู้ใช้เจตนาส่ง null มาเพื่อล้างข้อมูลในฟิลด์นั้น’ กับ ‘ผู้ใช้ไม่ได้ส่งฟิลด์นี้มาในคำขอ’ เพราะทั้งสองกรณีจะถูกแปลงเป็น None ในฝั่ง Rust และถูกมองว่าให้ ‘คงค่าเดิมไว้’ ทั้งสิ้น หาก API ของคุณจำเป็นต้องรองรับการล้างข้อมูลฟิลด์ที่ระบุ คุณอาจต้องใช้เทคนิคค่า sentinel, ส่งพารามิเตอร์ระบุรายชื่อฟิลด์ที่ต้องการล้างแยกต่างหาก หรือสร้างคำสั่ง SQL แบบไดนามิกที่เจาะจงชัดเจนยิ่งขึ้น
ใช้ Parameterized Queries เสมอ ทุกค่าที่รับมาจากผู้ใช้จะต้องส่งผ่านตัวแทนพารามิเตอร์ ($1, $2, ฯลฯ) ผ่าน .bind() เสมอ และต้องไม่มีการต่อสตริง (string interpolation) เข้าไปในคำสั่ง SQL เด็ดขาด ซึ่งจะช่วยป้องกันปัญหา SQL Injection ได้อย่างเด็ดขาดตั้งแต่การออกแบบ
แพตเทิร์น FromRef เพื่อการเข้าถึงที่สะดวก
คุณอาจพบว่าตัวเองต้องดึง AppState ทั้งก้อนออกมาในทุกๆ แฮนด์เลอร์ เพียงเพื่อจะหยิบพูลฐานข้อมูลหรือรีพอสิทอรีออกมาใช้งาน ซึ่งโค้ดจะเริ่มซ้ำซ้อนและดูเทอะทะอย่างรวดเร็ว แพตเทิร์น FromRef นำเสนอทางออกที่สะอาดตาและเป็นระเบียบกว่ามาก โดยเปิดทางให้คุณดึงเฉพาะคอมโพเนนต์ย่อยของ State ที่ต้องการออกมาได้โดยตรง
#![allow(unused)]
fn main() {
use axum::extract::FromRef;
#[derive(Clone)]
pub struct AppState {
pub db: PgPool,
pub user_repo: UserRepository,
// ... other fields
}
impl FromRef<AppState> for UserRepository {
fn from_ref(state: &AppState) -> Self {
state.user_repo.clone()
}
}
impl FromRef<AppState> for PgPool {
fn from_ref(state: &AppState) -> Self {
state.db.clone()
}
}
}
ตอนนี้แฮนด์เลอร์ของเราจึงสามารถดึงเฉพาะรีพอสิทอรีที่ต้องการออกมาใช้งานได้โดยตรง:
#![allow(unused)]
fn main() {
async fn get_user(
State(repo): State<UserRepository>,
Path(id): Path<Uuid>,
) -> AppResult<Json<UserResponse>> {
let user = repo.find_by_id(&UserId::from_uuid(id))
.await?
.ok_or(AppError::NotFound)?;
Ok(Json(user.into()))
}
}
สิ่งที่ทำให้ผมชอบแนวทางนี้มากคือ ลายเซ็นของฟังก์ชันแฮนด์เลอร์จะระบุเฉพาะสิ่งที่ฟังก์ชันนั้นต้องใช้งานจริงๆ อย่างชัดเจน แทนที่จะต้องผูกติดอยู่กับ State ก้อนใหญ่ของแอปพลิเคชันทั้งหมด
รีพอสิทอรีแบบเทรตเพื่อความสามารถในการทดสอบ
สำหรับกรณีทั่วไป การใช้ struct รูปธรรมอย่าง UserRepository ที่เรียกใช้ SQLx โดยตรงก็ทำงานได้ดีและเพียงพอแล้ว แต่หากคุณต้องการเขียน Unit Test ให้กับเลเยอร์เซอร์วิสโดยไม่ต้องสตาร์ตฐานข้อมูลจริงขึ้นมา คุณสามารถกำหนดรีพอสิทอรีให้อยู่ในรูปของเทรต (trait) แล้วสร้างทั้งอิมพลีเมนเทชันจริงสำหรับใช้งานและ mock สำหรับการทดสอบได้
เราได้อธิบายรายละเอียดเรื่องนี้ไว้อย่างเจาะลึกในบท แพตเทิร์นสถาปัตยกรรม หากสรุปให้กระชับคือ: กำหนดเทรตขึ้นในเลเยอร์โดเมน, อิมพลีเมนต์เทรตนั้นด้วย SQLx ในเลเยอร์อินฟราสตรัคเจอร์ แล้วส่งเข้ามายังเลเยอร์เซอร์วิสผ่าน Generic หรือ Trait Object ซึ่งจะทำให้ชุดทดสอบของคุณสามารถส่ง In-memory implementation ที่เก็บข้อมูลลงใน HashMap ธรรมดาเข้ามาแทนที่ได้อย่างง่ายดาย
ธุรกรรม
เมื่อคุณมีคำสั่งเขียนข้อมูลลงฐานข้อมูลหลายรายการที่จำเป็นต้องสำเร็จทั้งหมดหรือล้มเหลวร่วมกัน ให้ครอบการทำงานทั้งหมดไว้ภายในทรานแซกชัน (transaction):
#![allow(unused)]
fn main() {
pub async fn transfer_credits(
&self,
from: &UserId,
to: &UserId,
amount: i64,
) -> anyhow::Result<()> {
let mut tx = self.pool.begin().await.context("failed to begin transaction")?;
sqlx::query!(
"UPDATE accounts SET credits = credits - $1 WHERE user_id = $2",
amount,
from.as_uuid(),
)
.execute(&mut *tx)
.await
.context("failed to debit source account")?;
sqlx::query!(
"UPDATE accounts SET credits = credits + $1 WHERE user_id = $2",
amount,
to.as_uuid(),
)
.execute(&mut *tx)
.await
.context("failed to credit target account")?;
tx.commit().await.context("failed to commit transfer")?;
Ok(())
}
}
หากขั้นตอนใดเกิดความล้มเหลว (หรือฟังก์ชันส่งค่าคืนเร็วกว่าปกติจากโอเปอเรเตอร์ ?) ทรานแซกชันจะถูก rollback กลับโดยอัตโนมัติทันทีที่ตัวแปร tx หลุดพ้นขอบเขต (drop) โดยที่คุณไม่ต้องเขียนโค้ดเพื่อ cleanup แต่อย่างใด
และหากคุณต้องการให้การทำงานของแฮนด์เลอร์ทั้งฟังก์ชันอยู่ภายใต้ทรานแซกชันเดียวกัน โดยจะ commit เมื่อสำเร็จและ rollback เมื่อเกิดข้อผิดพลาดโดยอัตโนมัติ ลองศึกษาเครต axum-sqlx-tx ซึ่งมี extractor ช่วยจัดการวงจรชีวิตของทรานแซกชันให้คุณอย่างสะดวก เหมาะมากสำหรับทรานแซกชันที่มีขอบเขตเท่ากับหนึ่งคำขอ (request-scoped transactions)
การเลือกเครตฐานข้อมูล
หลายคนอาจสงสัยว่าควรเลือกใช้เครตฐานข้อมูลตัวใดดี ในระบบนิเวศของ Rust มีตัวเลือกที่แข็งแกร่งและเป็นที่นิยมอยู่หลายตัว ซึ่งแต่ละตัวมีข้อดีและข้อแลกเปลี่ยน (trade-offs) ที่แตกต่างกัน:
SQLx คือตัวเลือกที่ได้รับความนิยมสูงสุดเมื่อใช้งานร่วมกับ Axum รองรับ Asynchronous โดยกำเนิด ตรวจสอบความถูกต้องของคิวรีได้ตั้งแต่ตอนคอมไพล์ และทำงานกับคำสั่ง SQL ดิบโดยตรง คุณสามารถเขียน SQL ได้ด้วยตนเอง ซึ่งทำให้ควบคุมประสิทธิภาพได้เต็มที่และหมดปัญหาความไม่เข้ากันทางโครงสร้าง (object-relational impedance mismatch) ที่มักเกิดจาก ORM นอกจากนี้ การตรวจสอบตอนคอมไพล์ยังช่วยดักจับความไม่ตรงกันของชนิดข้อมูล, คอลัมน์ที่พิมพ์ผิดหรือไม่มีอยู่จริง และข้อผิดพลาดทางไวยากรณ์ ได้ก่อนที่โค้ดของคุณจะถูกนำไปรันจริง
Diesel เป็น ORM ที่มีประวัติยาวนานและสมบูรณ์ที่สุดในโลก Rust มี Query Builder ที่ปลอดภัยทางชนิดข้อมูล (type-safe) สูงมาก โดยสามารถตรวจจับข้อผิดพลาดได้ตั้งแต่ตอนคอมไพล์ผ่านระบบ Type System ของ Rust เอง โดยไม่ต้องต่อเชื่อมกับฐานข้อมูลจริง แม้เดิมที Diesel จะออกแบบมาสำหรับการทำงานแบบ Synchronous แต่ปัจจุบันมีเครต diesel-async ที่ช่วยรองรับงาน Asynchronous ได้อย่างยอดเยี่ยม เหมาะสำหรับผู้ที่ชื่นชอบการใช้ Query Builder มากกว่าการเขียน SQL ดิบ และต้องการการันตีความปลอดภัยระดับเข้มงวดจากคอมไพเลอร์
SeaORM นำเสนอแนวคิดที่ได้แรงบันดาลใจมาจาก ActiveRecord พร้อมรองรับ Async ในตัว สามารถสร้าง Entity structs จากสกีมาของฐานข้อมูลได้โดยอัตโนมัติ และมี High-level query API ที่ใช้งานง่าย เหมาะสำหรับการพัฒนาที่ต้องการความคล่องตัวและรวดเร็ว หรือโปรเจกต์ที่รู้สึกว่าการเขียน SQL ดิบซ้ำๆ เป็นเรื่องยุ่งยากเกินไป แม้อาจต้องแลกมาด้วยความยืดหยุ่นในการควบคุมแบบละเอียด (fine-grained control) ที่น้อยกว่า SQLx เล็กน้อย
สำหรับโปรเจกต์ Axum ใหม่ส่วนใหญ่ ผมยังคงแนะนำให้เลือกใช้ SQLx เป็นค่าเริ่มต้น เพราะสอดคล้องกับปรัชญาการออกแบบของ Axum ที่เน้นความชัดเจน ตรงไปตรงมา และการประกอบกันได้อย่างยืดหยุ่น (composable) มากกว่าการซ่อนความมหัศจรรย์ไว้เบื้องหลัง อีกทั้งฟีเจอร์การตรวจสอบคิวรีตอนคอมไพล์จะช่วยเพิ่ม productivity ในการพัฒนาขึ้นอย่างมหาศาลเมื่อคุณเริ่มคุ้นเคยกับมัน
การจัดการสถานะ
หากคุณเคยสร้างเว็บเซอร์วิส แม้จะเป็นเพียงโปรเจกต์ขนาดเล็ก คุณคงคุ้นเคยกับโจทย์นี้ดี: ฟังก์ชันแฮนด์เลอร์ของคุณจำเป็นต้องเข้าถึงทรัพยากรที่ใช้ร่วมกัน เช่น พูลฐานข้อมูล, ค่าคอนฟิกูเรชัน, อินสแตนซ์ของเซอร์วิส หรือแคชในหน่วยความจำ ทุกคำขอที่ส่งเข้ามาต่างต้องการสิ่งเหล่านี้ไม่มากก็น้อย และคุณต้องมีวิธีส่งข้อมูลเหล่านี้เข้าไปยังแฮนด์เลอร์โดยไม่ต้องส่งผ่านพารามิเตอร์ของฟังก์ชันทีละสิบกว่าตัว Axum มีวิธีจัดการเรื่องนี้ที่ปลอดภัยด้านชนิดข้อมูล (type-safe) ผ่านตัวแยกข้อมูล (extractor) State และเมื่อคุณเริ่มคุ้นเคยกับมันแล้ว คุณจะพบว่ามันใช้งานได้อย่างเป็นธรรมชาติและสะดวกอย่างยิ่ง
struct AppState
แพตเทิร์นที่ผมเลือกใช้เป็นประจำคือการสร้าง struct เดี่ยวๆ ขึ้นมาเพื่อเก็บทุกสิ่งที่แฮนด์เลอร์จำเป็นต้องใช้ จากนั้นส่ง struct นี้ให้กับเราเตอร์ผ่าน .with_state() แล้วปล่อยให้ Axum จัดการส่วนที่เหลือให้ทั้งหมด สิ่งสำคัญจุดหนึ่งที่ต้องจำไว้คือ struct นี้ต้อง implement Clone เสมอ เนื่องจาก Axum จะทำการ clone ค่านี้ทุกครั้งที่มีการเรียกใช้แฮนด์เลอร์
#![allow(unused)]
fn main() {
use sqlx::PgPool;
use std::sync::Arc;
#[derive(Clone)]
pub struct AppState {
pub config: Arc<Config>,
pub db: PgPool,
pub user_service: UserService<PostgresUserRepo>,
pub post_service: PostService<PostgresPostRepo>,
}
impl AppState {
pub fn new(config: Config, pool: PgPool) -> Self {
let user_repo = PostgresUserRepo::new(pool.clone());
let post_repo = PostgresPostRepo::new(pool.clone());
Self {
config: Arc::new(config),
db: pool,
user_service: UserService::new(user_repo),
post_service: PostService::new(post_repo),
}
}
}
}
มีข้อพิจารณาในการออกแบบที่น่าสนใจหลายจุดในโค้ดตัวอย่างนี้:
เราครอบ Config ไว้ด้วย Arc เนื่องจากคอนฟิกเป็นข้อมูลแบบอ่านอย่างเดียว (read-only) ภายหลังจากที่เริ่มต้นระบบเสร็จสิ้น และอาจมีขนาดข้อมูลค่อนข้างใหญ่ การใช้ Arc จะทำให้การ clone มีต้นทุนต่ำมาก (เพียงแค่เพิ่มตัวนับ reference count) แทนที่จะต้องทำ deep copy ข้อมูลคอนฟิกทั้งก้อนทุกครั้งที่ AppState ถูก clone ซึ่งความแตกต่างของต้นทุนนี้จะส่งผลอย่างมีนัยสำคัญเมื่อระบบต้องรองรับคำขอนับพันต่อวินาที
สำหรับ PgPool นั้นมีกลไก reference counting ภายในตัวอยู่แล้ว การ clone จึงมีต้นทุนต่ำมากเช่นกัน โดยคุณจะพบว่าชนิดข้อมูลพูลการเชื่อมต่อส่วนใหญ่ในระบบนิเวศของ Rust ล้วนออกแบบมาในลักษณะนี้
ส่วนเลเยอร์เซอร์วิสและรีพอสิทอรีจะถูกสร้างขึ้นเพียงครั้งเดียวในตอนเริ่มต้นระบบ จากนั้นจึงนำไปแชร์ใช้งานร่วมกันในทุกคำขอ ผมมองว่าจุดนี้ทำหน้าที่เป็น Composition Root ของแอปพลิเคชัน เป็นศูนย์กลางจุดเดียวที่เราประกอบเชื่อมต่อ (wiring) ดีเพนเดนซีทั้งหมดเข้าด้วยกัน และหากคุณต้องการสลับไปใช้ Test Double หรือ Mock สำหรับรีพอสิทอรีในการทดสอบ จุดนี้ก็คือจุดที่คุณจะเข้ามาปรับแต่ง
การดึงสถานะในแฮนด์เลอร์
แล้วแฮนด์เลอร์ของเราจะเข้าถึงสถานะได้อย่างไร? ผ่านตัวแยกข้อมูล State:
#![allow(unused)]
fn main() {
async fn list_users(
State(state): State<AppState>,
) -> AppResult<Json<Vec<UserResponse>>> {
let users = state.user_service.list_all().await?;
Ok(Json(users.into_iter().map(Into::into).collect()))
}
}
ดูตรงไปตรงมามากใช่ไหมครับ? แต่คุณอาจสังเกตเห็นว่าแฮนด์เลอร์ทุกตัวจะได้รับ AppState ไปทั้งก้อน แม้ว่าจะต้องการเข้าถึงเพียงฟิลด์เดียวก็ตาม สำหรับแอปพลิเคชันขนาดเล็ก แนวทางนี้ก็ถือว่าใช้ได้ดีและไม่มีปัญหาอะไร แต่เมื่อโปรเจกต์เติบโตขึ้นเรื่อยๆ คุณอาจต้องการความสามารถในการควบคุมที่ละเอียด (granular) ยิ่งกว่านี้
สถานะย่อยด้วย FromRef
นี่คือจังหวะที่เทรต FromRef จะเข้ามาช่วยแก้ปัญหา โดยจะเปิดทางให้คุณดึงเฉพาะฟิลด์ย่อยแต่ละตัวออกจาก State ได้โดยตรง ทำให้แฮนด์เลอร์ไม่จำเป็นต้องรู้จัก struct AppState ทั้งก้อนอีกต่อไป ซึ่งผมพบว่ามีประโยชน์อย่างยิ่งในการช่วยให้ลายเซ็นของแฮนด์เลอร์กระชับ ชัดเจน และช่วยจำกัดขอบเขตการเข้าถึงข้อมูลของแต่ละแฮนด์เลอร์ให้อยู่ในจุดที่จำเป็นจริงๆ
Axum มี derive macro ที่ช่วยสร้างโค้ดการอิมพลีเมนต์ FromRef สำหรับแต่ละฟิลด์ให้โดยอัตโนมัติ:
#![allow(unused)]
fn main() {
use axum::extract::FromRef;
#[derive(Clone, FromRef)]
pub struct AppState {
config: Arc<Config>,
db: PgPool,
user_service: UserService<PostgresUserRepo>,
post_service: PostService<PostgresPostRepo>,
}
}
การ derive เพียงครั้งเดียวจะช่วยลดภาระในการเขียนบล็อก impl FromRef<AppState> for ... ด้วยตัวเองในทุกๆ ฟิลด์ โดยระบบจะสร้างโค้ดอิมพลีเมนต์สำหรับชนิดข้อมูลของแต่ละฟิลด์ และหยิบฟิลด์จาก struct มาเชื่อมโยงให้อย่างถูกต้อง
คราวนี้ แฮนด์เลอร์ที่ต้องการใช้งานเพียงแค่เซอร์วิสผู้ใช้ ก็สามารถระบุความต้องการเฉพาะสิ่งนั้นได้ทันที:
#![allow(unused)]
fn main() {
async fn get_user(
State(user_service): State<UserService<PostgresUserRepo>>,
Path(id): Path<Uuid>,
) -> AppResult<Json<UserResponse>> {
let user = user_service.get_by_id(UserId::from_uuid(id))
.await?
.ok_or(AppError::NotFound)?;
Ok(Json(user.into()))
}
}
นอกจากนี้ แพตเทิร์นดังกล่าวยังทำงานร่วมกับตัวแยกข้อมูลแบบกำหนดเอง (Custom Extractor) ได้อย่างลงตัว ตัวอย่างเช่น ตัวแยกข้อมูล AuthUser ของเรา (ซึ่งเราจะไปสร้างกันในบท การยืนยันตัวตนและการอนุญาตสิทธิ์) สามารถดึง JWT secret ออกมาจาก State ผ่าน FromRef ได้โดยตรง โดยไม่จำเป็นต้องรับรู้ถึงฟิลด์อื่นๆ เลย ทำให้แต่ละส่วนแยกขาดจากกันอย่างเป็นระเบียบ (clean decoupling)
State เทียบกับ Extension
คุณอาจสงสัยว่าทำไม Axum จึงมีทั้ง State และ Extension ในการส่งต่อข้อมูลไปยังแฮนด์เลอร์ ผมเคยเห็นนักพัฒนาหลายคนหยิบใช้ Extension ด้วยความคุ้นเคยจากเฟรมเวิร์กอื่น ผมจึงขออธิบายข้อแตกต่างและแนวทางในการเลือกใช้ดังนี้:
State ได้รับการตรวจสอบความถูกต้องของชนิดข้อมูลตั้งแต่ตอนคอมไพล์ หากคุณลืมเรียก .with_state() หรือระบุชนิดข้อมูลไม่ตรงกัน คอมไพเลอร์จะแจ้งเตือนข้อผิดพลาดทันที ซึ่งข้อดีเพียงข้อนี้ก็เพียงพอแล้วที่จะทำให้ State เป็นตัวเลือกเริ่มต้นของผมเสมอ
Extension จะจัดเก็บข้อมูลไว้ใน Type-map ภายในคำขอ (Request) เอง ซึ่งจะถูกตรวจสอบเฉพาะ ณ เวลารันไทม์เท่านั้น นั่นหมายความว่าหากเกิดข้อผิดพลาดหรือหาข้อมูลไม่พบ ระบบจะแสดงผลเป็น HTTP 500 Internal Server Error เมื่อคำขอจริงวิ่งมาถึงแฮนด์เลอร์ ซึ่งไม่ใช่เรื่องที่ดีนัก อย่างไรก็ตาม Extension ก็มีประโยชน์และเหมาะสมอย่างยิ่งสำหรับข้อมูลที่มิดเดิลแวร์นำมาผูกไว้ในระดับรายคำขอ (request-scoped data) เช่น ข้อมูลผู้ใช้ที่ผ่านการยืนยันตัวตนแล้วซึ่งถูกแกะออกมาจาก JWT
หลักคิดง่ายๆ ที่ผมใช้คือ: เลือกใช้ State สำหรับดีเพนเดนซีระดับแอปพลิเคชันที่เตรียมไว้ตั้งแต่ตอนเริ่มต้นระบบ (คอนฟิก, พูลฐานข้อมูล, เซอร์วิส) และเลือกใช้ Extension สำหรับข้อมูลเฉพาะของแต่ละคำขอที่มิดเดิลแวร์สร้างหรือแนบขึ้นมาระหว่างการทำงาน (on the fly)
การหลีกเลี่ยงข้อผิดพลาดที่พบบ่อย
ก่อนที่เราจะไปยังบทถัดไป ผมขอแชร์บทเรียนสำคัญสองสามข้อที่ผม (หรือทีมงาน) เคยเจ็บปวดมาแล้วบน Production:
อย่าใส่ Mutex<T> ลงใน State เว้นแต่คุณจะไตร่ตรองมาอย่างรอบคอบจริงๆ ผมเคยเห็นบั๊กจากจุดนี้มานับไม่ถ้วน การถือ lock ของ Mutex ข้ามจุด .await อาจนำไปสู่ปัญหา Deadlock หรือเกิด Lock Contention อย่างรุนแรงในโค้ดที่เป็น Asynchronous หากคุณจำเป็นต้องมี Shared Mutable State (เช่น แคชในหน่วยความจำ) ให้เลือกใช้ tokio::sync::RwLock ที่เข้าใจกลไกของ Asynchronous หรือทางที่ดีกว่านั้นคือเลือกใช้เครตอย่าง moka หรือ dashmap ที่ออกแบบมาสำหรับรองรับการเข้าถึงพร้อมกัน (concurrent access) โดยเฉพาะ
พิจารณาอย่างรอบคอบว่าสิ่งใดควรอยู่ใน AppState เมื่อแอปพลิเคชันขยายใหญ่ขึ้น การโยนฟิลด์ใหม่ๆ เข้าไปใน State ไปเรื่อยๆ เป็นสิ่งที่ทำได้ง่ายและเย้ายวนใจมาก แต่ State struct ที่มีฟิลด์นับสิบๆ ฟิลด์จะทำให้โค้ดซับซ้อนและเข้าใจยากอย่างรวดเร็ว หาก State ของคุณเริ่มเทอะทะจนจัดการยาก นั่นเป็นสัญญาณเตือนว่าแอปพลิเคชันของคุณควรแยกออกเป็นโมดูลย่อยที่มีขอบเขตชัดเจน โดยแต่ละโมดูลจะมี State struct ของตนเอง แล้วจึงนำมาประกอบรวมกันในระดับเราเตอร์
สร้าง State เพียงครั้งเดียวในตอนเริ่มต้นระบบ อย่าสร้างอินสแตนซ์ใหม่ของเซอร์วิสหรือรีพอสิทอรีภายในฟังก์ชันแฮนด์เลอร์ หัวใจสำคัญของแพตเทิร์น AppState คือการประกอบเชื่อมต่อ (wiring) ดีเพนเดนซีทั้งหมดไว้เพียงจุดเดียวตั้งแต่ต้น (ในฟังก์ชัน main หรือฟังก์ชัน setup) จากนั้นแชร์อินสแตนซ์เหล่านั้นแบบอ่านอย่างเดียว (immutable) ไปยังทุกๆ คำขอ เมื่อคุณเข้าใจและยึดหลักการนี้ โครงสร้างแอปพลิเคชันของคุณจะอ่านและดูแลรักษาได้ง่ายขึ้นอย่างมหาศาล
การตั้งค่า
ผมเคยเห็นบั๊กที่เกิดจากการตั้งค่าคอนฟิกูเรชันผิดพลาดมามากเกินพอแล้วตลอดชีวิตการทำงาน ตั้งแต่ URL ฐานข้อมูลที่รันผ่านบนเครื่องตนเองแต่ใช้การไม่ได้บน Staging, ค่า JWT Secret ที่หลุดเข้าไปใน git commit, ไปจนถึง Environment Variable สำคัญที่ขาดหายไป แต่คุณกลับเพิ่งมารู้ตัวเอาสิบนาทีหลังจากการดีพลอยต์ เมื่อมีคำขอแรกวิ่งชนโค้ดในเส้นทางที่ต้องใช้ค่านั้น ปัญหาเหล่านี้ล้วนเป็นสิ่งที่หลีกเลี่ยงได้ และกลยุทธ์ที่เราจะใช้ในบทนี้จะช่วยป้องกันปัญหาดังกล่าวได้อย่างเบ็ดเสร็จ
แนวคิดหลักนั้นเรียบง่ายและตรงไปตรงมา: โหลดค่าคอนฟิกจากสภาพแวดล้อม ตรวจสอบความถูกต้องทันทีตั้งแต่ตอนเริ่มต้นระบบ (eager validation) และปกป้องข้อมูลที่เป็นความลับ (secrets) ในหน่วยความจำอย่างปลอดภัย มาดูกันว่าเราจะนำแนวคิดนี้ไปปฏิบัติจริงได้อย่างไร
struct การตั้งค่าแบบกำหนดชนิดชัดเจน
เราจะเริ่มต้นด้วยการสร้าง Rust struct ขึ้นมาเพื่อเป็นตัวแทนของค่าคอนฟิกทั้งหมดที่แอปพลิเคชันจำเป็นต้องใช้ นี่คือหนึ่งในจุดที่ระบบ Type System ของ Rust โดดเด่นอย่างแท้จริง: คุณจะได้รับการรับประกันตั้งแต่ตอนคอมไพล์ว่ามีฟิลด์ใดบ้างและแต่ละฟิลด์เป็นชนิดข้อมูลอะไร อีกทั้งยังสามารถตรวจสอบความถูกต้องของค่าต่างๆ ได้ทันทีตั้งแต่ตอนสร้าง struct แทนที่จะต้องมาคอยลุ้นว่าข้อมูลจะถูกต้องหรือไม่เมื่อมีคำขอเรียกใช้งานในภายหลัง
#![allow(unused)]
fn main() {
use secrecy::{SecretString, ExposeSecret};
use serde::Deserialize;
#[derive(Debug, Clone, Deserialize)]
pub struct Config {
#[serde(default = "default_port")]
pub port: u16,
#[serde(default = "default_environment")]
pub environment: Environment,
pub database_url: SecretString,
pub jwt_secret: SecretString,
#[serde(default = "default_log_level")]
pub log_level: String,
#[serde(default)]
pub cors_origins: Vec<String>,
}
#[derive(Debug, Deserialize, Clone, PartialEq)]
#[serde(rename_all = "lowercase")]
pub enum Environment {
Development,
Staging,
Production,
}
fn default_port() -> u16 { 3000 }
fn default_environment() -> Environment { Environment::Development }
fn default_log_level() -> String { "info".to_string() }
}
มีข้อพิจารณาในการออกแบบที่สำคัญหลายประการในโค้ดชุดนี้ที่ควรกล่าวถึง:
โปรดสังเกตว่าฟิลด์ database_url และ jwt_secret จะถูกห่อหุ้มด้วย SecretString จากเครต secrecy แทนที่จะเป็น String ธรรมดา ซึ่งให้ประโยชน์หลัก 2 ประการ: ประการแรก ค่าของความลับจะถูกปกปิด (redact) โดยอัตโนมัติเมื่อมีการสั่งพิมพ์ struct ผ่านการจัดรูปแบบ Debug (คุณจะเห็นเป็น [REDACTED] แทนค่าความลับจริง) และประการที่สอง ข้อมูลในหน่วยความจำจะถูกเขียนทับด้วยศูนย์ (zeroize) ทันทีที่ค่านั้นหลุดพ้นขอบเขต (drop) ผมเคยเห็นความลับบน Production หลุดเข้าไปใน Log Files มาบ่อยจนไม่อยากจะนึกถึง การป้องกันในระดับนี้จึงมีคุณค่ามหาศาล
enum Environment ถูกสร้างขึ้นเป็นชนิดข้อมูลเฉพาะตัวแทนการใช้สตริงธรรมดา ทำให้คุณสามารถตรวจสอบเงื่อนไขผ่าน match ได้อย่างครอบคลุมทุกกรณี (exhaustively) โดยคอมไพเลอร์จะแจ้งเตือนทันทีหากคุณลืมจัดการกรณีใดกรณีหนึ่ง นอกจากนี้ยังช่วยดักจับข้อผิดพลาดจากการพิมพ์ผิด เช่น prodduction ได้ตั้งแต่ขั้นตอนการแปลงข้อมูล (parsing) แทนที่จะปล่อยให้ผ่านไปเงียบๆ
เรายังกำหนดค่าเริ่มต้น (default values) ให้กับฟิลด์ที่สมเหตุสมผล วิธีนี้ช่วยให้คุณสามารถเปิดรันแอปพลิเคชันได้โดยใช้การตั้งค่าเพียงเล็กน้อยในระหว่างการพัฒนา แต่ยังคงบังคับให้ต้องระบุค่าสำคัญอย่างชัดเจน เช่น ข้อมูลสิทธิ์การเข้าถึงฐานข้อมูล (credentials)
การโหลดจากตัวแปรสภาพแวดล้อม
เครต config มีระบบที่ยืดหยุ่นสำหรับการโหลดการตั้งค่าจากหลากหลายแหล่งข้อมูลและนำมาผสานรวมกัน แต่สำหรับแอปพลิเคชันส่วนใหญ่ การโหลดจากตัวแปรสภาพแวดล้อม (Environment Variables) ก็เพียงพอและตอบโจทย์ได้เป็นอย่างดีแล้ว:
#![allow(unused)]
fn main() {
impl Config {
pub fn from_env() -> anyhow::Result<Self> {
// In development, load from a .env file if present.
// The .ok() is intentional: in production there is no .env file,
// and that is fine.
dotenvy::dotenv().ok();
let config = config::Config::builder()
.add_source(
config::Environment::default()
.separator("__")
)
.build()
.context("failed to build configuration")?;
let parsed: Config = config
.try_deserialize()
.context("failed to deserialize configuration")?;
parsed.validate()?;
Ok(parsed)
}
fn validate(&self) -> anyhow::Result<()> {
if self.jwt_secret.expose_secret().len() < 48 {
anyhow::bail!(
"JWT_SECRET must be at least 48 characters for adequate security"
);
}
Ok(())
}
}
}
การกำหนดตัวคั่น __ ช่วยให้คุณสามารถตั้งค่าฟิลด์ที่มีโครงสร้างซ้อนกัน (nested configuration) ได้โดยใช้เครื่องหมายขีดล่างสองตัว (double-underscore) ในชื่อตัวแปรสภาพแวดล้อม เช่น หากคุณมีฟิลด์ย่อย database.max_connections คุณสามารถกำหนดค่าผ่าน DATABASE__MAX_CONNECTIONS ได้อย่างง่ายดาย
สำหรับเมธอด validate จะทำหน้าที่ตรวจสอบเงื่อนไขเพิ่มเติมที่ไม่สามารถแสดงออกผ่านระบบชนิดข้อมูลเพียงอย่างเดียวได้ ในที่นี้คือการตรวจสอบว่า JWT secret มีความยาวเพียงพอที่จะต้านทานการโจมตีแบบ Brute-force หรือไม่ หากการตรวจสอบไม่ผ่าน แอปพลิเคชันจะหยุดการทำงานทันทีพร้อมแจ้งข้อความข้อผิดพลาดที่ชัดเจน ซึ่งดีกว่าการปล่อยให้ระบบเปิดทำงานได้อย่างราบรื่นแล้วไปพังเอาตอนที่มีผู้ใช้พยายามล็อกอินเข้าสู่ระบบ เพียงเพราะระบบเพิ่งตรวจพบว่า JWT secret มีความยาวแค่ 3 ตัวอักษร
ไฟล์ .env สำหรับการพัฒนา
ในระหว่างการพัฒนาบนเครื่อง Local การเก็บค่าคอนฟิกไว้ในไฟล์ .env จะช่วยเพิ่มความสะดวกอย่างมาก เพราะคุณไม่ต้องคอยสั่ง export ตัวแปรสภาพแวดล้อมด้วยตัวเองทุกครั้งที่เริ่มรันแอปพลิเคชัน:
DATABASE_URL=postgres://localhost:5432/myapp_dev
JWT_SECRET=this-is-a-local-dev-secret-that-is-long-enough-for-validation
LOG_LEVEL=debug
ENVIRONMENT=development
ไฟล์นี้จะต้องถูกระบุไว้ใน .gitignore เสมอ และห้าม commit เข้าสู่ระบบควบคุมเวอร์ชันโดยเด็ดขาด แม้ว่าจะมีเพียงความลับที่ใช้เฉพาะในสภาพแวดล้อมการพัฒนาก็ตาม จากประสบการณ์ของผม ความเคยชินในการ commit ไฟล์ .env มักจะลงเอยด้วยการที่มีใครสักคนเผลอ push ความลับของระบบ Production ขึ้นไปโดยไม่ตั้งใจในที่สุด ทางออกที่ดีคือการจัดเตรียมไฟล์ .env.example เพื่อเป็นคู่มืออ้างอิงว่าระบบต้องการตัวแปรใดบ้าง:
# Copy this file to .env and fill in the values
DATABASE_URL=postgres://localhost:5432/myapp_dev
JWT_SECRET=<generate a random string of at least 48 characters>
LOG_LEVEL=info
ENVIRONMENT=development
การใช้ความลับอย่างปลอดภัย
เครต secrecy เป็นไลบรารีขนาดเล็กแต่เปี่ยมด้วยประสิทธิภาพ เมื่อคุณห่อหุ้มค่าใดๆ ไว้ใน SecretString คุณจะได้รับการปกป้องถึง 3 ชั้นด้วยกัน:
-
การปกปิดค่าอัตโนมัติใน Debug (Redaction) ไม่ว่าโค้ดส่วนใดจะสั่งพิมพ์ struct คอนฟิกออกมา ไม่ว่าจะตั้งใจหรือเผลอทำโดยไม่รู้ตัว สิ่งที่ปรากฏจะเป็นข้อความ
[REDACTED]เสมอแทนที่จะเป็นความลับจริง ประเด็นนี้มีความสำคัญอย่างยิ่ง เพราะระบบ Structured Logging หรือ Error Reporting อาจเผลอ serialize struct คอนฟิกทั้งก้อนออกมาได้หากไม่ได้ระวัง -
การล้างหน่วยความจำเป็นศูนย์อย่างปลอดภัย (Secure Zeroization) เมื่อตัวแปร
SecretStringหลุดพ้นขอบเขตการทำงาน (drop) พื้นที่หน่วยความจำของมันจะถูกเขียนทับด้วยเลขศูนย์ทั้งหมดทันทีก่อนที่จะคืนหน่วยความจำกลับสู่ระบบ ซึ่งช่วยลดความเสี่ยงที่ข้อมูลความลับจะค้างอยู่ใน Memory Dump ลงได้อย่างมาก -
การเปิดเผยข้อมูลอย่างตั้งใจและชัดเจน (Explicit Exposure) ในการนำค่าความลับออกมาใช้งานจริง คุณจะต้องเรียกใช้เมธอด
.expose_secret()ซึ่งจะส่งคืนค่าการอ้างอิงไปยังสตริงภายในออกมาอย่างชัดเจน ทำให้ทุกจุดที่มีการเข้าถึงความลับสังเกตเห็นได้ง่าย และสามารถค้นหาด้วยคำสั่ง grep ได้อย่างสะดวกรวดเร็วในระหว่างการรีวิวโค้ด
#![allow(unused)]
fn main() {
// When you need to use the secret, you explicitly expose it.
// Keep the exposed value's lifetime as short as possible.
let decoding_key = DecodingKey::from_secret(
config.jwt_secret.expose_secret().as_bytes()
);
}
กฎเหล็กที่ควรจำไว้: เรียกใช้ expose_secret() เฉพาะ ณ จุดที่จะใช้งานจริงเท่านั้น อย่าเรียกใช้ล่วงหน้า อย่าเก็บค่าที่เปิดเผยแล้วไว้ในตัวแปรที่มีอายุการใช้งานยาวนานเกินความจำเป็น และห้ามพิมพ์ค่านั้นลงในไฟล์ Log โดยเด็ดขาด
การดีพลอยต์ใน production
เมื่อขึ้นสู่ระบบ Production ค่าคอนฟิกูเรชันทั้งหมดควรถูกส่งเข้ามาผ่านระบบจัดการความลับ (Secrets Management) ของแพลตฟอร์มการดีพลอยต์โดยตรง ไม่ใช่การอ่านจากไฟล์ในเครื่อง ซึ่งอาจอยู่ในรูปแบบต่างๆ เช่น:
- Kubernetes Secrets ที่ถูก mount เข้ามาเป็นตัวแปรสภาพแวดล้อม
- Environment block ของ Docker ในไฟล์ Compose หรือคอนฟิกของ Container Orchestrator
- บริการจัดการความลับของผู้ให้บริการคลาวด์ เช่น AWS Secrets Manager, GCP Secret Manager ฯลฯ
จุดเด่นของแนวทางนี้คือ โค้ดของแอปพลิเคชันไม่จำเป็นต้องเปลี่ยนแปลงเลยไม่ว่าจะรันอยู่ในสภาพแวดล้อมใด เพราะแอปพลิเคชันจะอ่านค่าจากตัวแปรสภาพแวดล้อมเสมอ ความแตกต่างเพียงจุดเดียวคือวิธีการป้อนค่าตัวแปรเหล่านั้นเข้ามา: โดยในสภาพแวดล้อมการพัฒนาจะอ่านจากไฟล์ .env ส่วนใน Production จะรับมาจากระบบจัดการความลับของแพลตฟอร์ม
ล้มเหลวเร็ว (Fail fast)
หากมีกฎเหล็กเพียงข้อเดียวที่ผมอยากจะเน้นย้ำกับทุกทีมพัฒนา กฎข้อนั้นคือ: จงสั่งให้ระบบล้มเหลวทันทีและส่งเสียงดังๆ (Fail fast and loud) ตั้งแต่ตอนเริ่มระบบ หากพบว่าการตั้งค่าที่จำเป็นขาดหายไปหรือไม่ถูกต้อง การที่ระบบพังตั้งแต่ตอนเริ่มต้นพร้อมแจ้งข้อความข้อผิดพลาดที่ชัดเจนและตรงไปตรงมา (เช่น “JWT_SECRET environment variable is not set”) นั้นย่อมดีกว่าการปล่อยให้ระบบเปิดทำงานได้ แล้วไปพังเอาสิบนาทีหลังจากนั้นเมื่อมีคำขอยืนยันตัวตนเข้ามาครั้งแรก แล้วเพิ่งมารู้ตัวว่าไม่มีค่า JWT secret
นี่คือเหตุผลที่ฟังก์ชัน Config::from_env() ของเราทำการ Deserialize และตรวจสอบความถูกต้องอย่างเข้มงวดตั้งแต่ตอนเริ่มระบบ (eager validation) ทำให้มั่นใจได้ว่าเมื่อใดก็ตามที่แอปพลิเคชันเริ่มเปิดรับคำขอ การตั้งค่าทั้งหมดจะมีอยู่ครบถ้วน ถูกต้องตามชนิดข้อมูล และผ่านการตรวจสอบความถูกต้องแล้วทั้งหมด จึงหมดกังวลเรื่องบั๊กการตั้งค่าแอบแฝงที่จะโผล่มาสร้างความประหลาดใจตอนตีสองในคืนวันเสาร์ เมื่อรากฐานด้านการตั้งค่าของเรามั่นคงแล้ว ในบทถัดไปเราจะไปดูกันว่าเราจะจัดการกับข้อผิดพลาดในส่วนอื่นๆ ของแอปพลิเคชันอย่างไร
การกำหนดเส้นทางและแฮนด์เลอร์
คำขอ HTTP ทุกคำขอที่ส่งเข้ามายังแอปพลิเคชันของคุณจำเป็นต้องมีปลายทางสำหรับประมวลผล และใน Axum ปลายทางที่ว่านั้นก็คือ ‘แฮนด์เลอร์ (Handler)’ แฮนด์เลอร์เป็นเพียงฟังก์ชัน asynchronous ธรรมดาที่รับตัวแยกข้อมูล (extractor) ตั้งแต่ศูนย์ตัวขึ้นไปเป็นพารามิเตอร์ แล้วส่งคืนค่าชนิดใดก็ตามที่ implement เทรต IntoResponse โดย Axum จะคอยจัดการงานเบื้องหลัง (plumbing) ให้ทั้งหมด ไม่ว่าจะเป็นการ Deserialize ข้อมูลจากคำขอเข้ามาเป็นชนิดข้อมูลของ extractor และ Serialize ค่าที่ส่งคืนกลับออกไปเป็น HTTP Response
หลักการสำคัญประการแรกที่ผมอยากให้คุณยึดมั่นไว้ตั้งแต่ต้นบทคือ: แฮนด์เลอร์ต้องบาง (Thin Handlers) หน้าที่ของแฮนด์เลอร์มีเพียงการดึงข้อมูลออกจากคำขอ, ส่งต่องานไปให้เซอร์วิสหรือรีพอสิทอรี และแปลงผลลัพธ์ที่ได้ให้อยู่ในรูปของการตอบกลับ HTTP หากคุณพบว่าตัวเองเริ่มเขียน Business Logic, รันคิวรีฐานข้อมูล หรือมีเงื่อนไขแตกกิ่งซับซ้อนอยู่ภายในแฮนด์เลอร์ นั่นคือสัญญาณว่าโค้ดเหล่านั้นกำลังอยู่ผิดที่ผิดทาง เราจะมาคุยกันอย่างละเอียดว่าโค้ดแต่ละส่วนควรไปอยู่ที่ใดในบทว่าด้วยโดเมนและอินฟราสตรักเจอร์ แต่สำหรับตอนนี้ ขอให้จำกฎข้อนี้ไว้เสมอ: แฮนด์เลอร์ต้องบางเสมอ
การนิยามเส้นทาง
เราเตอร์ (Router) ของ Axum ใช้รูปแบบการต่อเมธอดเป็นลูกโซ่ (Method Chaining) ซึ่งเมื่อใช้งานไปสักพักจะรู้สึกเป็นธรรมชาติและอ่านเข้าใจได้ง่ายมาก คุณสามารถกำหนดเส้นทางทีละเส้นด้วย .route(), จัดกลุ่มเส้นทางที่เกี่ยวข้องกันไว้ภายใต้ URL Prefix เดียวกันด้วย .nest() และผสานเราเตอร์หลายๆ ตัวเข้าด้วยกันด้วย .merge()
#![allow(unused)]
fn main() {
use axum::{routing::{get, post, put, delete}, Router};
pub fn router(state: AppState) -> Router {
Router::new()
.nest("/api/v1", api_routes())
.route("/health", get(health_check))
.route("/health/ready", get(readiness_check))
.with_state(state)
}
fn api_routes() -> Router<AppState> {
Router::new()
.nest("/users", user_routes())
.nest("/posts", post_routes())
}
fn user_routes() -> Router<AppState> {
Router::new()
.route("/", get(list_users).post(create_user))
.route("/{id}", get(get_user).patch(update_user).delete(delete_user))
}
fn post_routes() -> Router<AppState> {
Router::new()
.route("/", get(list_posts).post(create_post))
.route("/{id}", get(get_post).patch(update_post).delete(delete_post))
}
}
ผมชอบแยกคำนิยามของเส้นทางออกเป็นฟังก์ชันเฉพาะ (หรือแยกออกเป็นไฟล์ย่อยๆ เลย) เพราะจะช่วยให้เราเตอร์อ่านง่ายและเป็นระเบียบเมื่อแอปพลิเคชันเริ่มขยายตัวขึ้น โดยแต่ละฟังก์ชันจะคืนค่าเป็น Router<AppState> แล้วให้เราเตอร์หลักนำพวกมันมาประกอบรวมกัน และจุดนี้เองก็เป็นตำแหน่งที่คุณสามารถผูกมิดเดิลแวร์เฉพาะเส้นทางได้ด้วย ซึ่งเราจะไปพูดถึงกันในบท มิดเดิลแวร์
การเขียนแฮนด์เลอร์
แล้วแฮนด์เลอร์ที่มีโครงสร้างที่ดีจริงๆ มีหน้าตาเป็นอย่างไร? จากประสบการณ์ของผม แฮนด์เลอร์ที่ดีล้วนมีจังหวะการทำงานแบบเดียวกันทั้งสิ้น: ดึงข้อมูลออกมา (extract), ส่งต่องาน (delegate) และส่งการตอบกลับ (respond)
#![allow(unused)]
fn main() {
use axum::{extract::{State, Path}, http::StatusCode, Json};
async fn create_user(
State(state): State<AppState>,
ValidatedJson(payload): ValidatedJson<CreateUserDto>,
) -> AppResult<(StatusCode, Json<UserResponse>)> {
let name = UserName::parse(&payload.name)
.map_err(|e| AppError::Validation(e.to_string()))?;
let email = Email::parse(&payload.email)
.map_err(|e| AppError::Validation(e.to_string()))?;
let user = state.user_service
.register(name, email, &payload.password)
.await?;
Ok((StatusCode::CREATED, Json(user.into())))
}
async fn get_user(
State(state): State<AppState>,
Path(id): Path<Uuid>,
) -> AppResult<Json<UserResponse>> {
let user = state.user_service
.get_by_id(UserId::from_uuid(id))
.await?
.ok_or(AppError::NotFound)?;
Ok(Json(user.into()))
}
async fn list_users(
State(state): State<AppState>,
Query(pagination): Query<PaginationParams>,
) -> AppResult<Json<PaginatedResponse<UserResponse>>> {
let (users, total) = state.user_service
.list(pagination.page, pagination.per_page)
.await?;
let response = PaginatedResponse {
data: users.into_iter().map(Into::into).collect(),
meta: PaginationMeta {
page: pagination.page,
per_page: pagination.per_page,
total,
total_pages: (total as f64 / pagination.per_page as f64).ceil() as u32,
},
};
Ok(Json(response))
}
async fn delete_user(
State(state): State<AppState>,
Path(id): Path<Uuid>,
) -> AppResult<StatusCode> {
state.user_service
.delete(UserId::from_uuid(id))
.await?;
Ok(StatusCode::NO_CONTENT)
}
}
ลองสังเกตแบบแผน (conventions) ที่ใช้ในโค้ดชุดนี้: เมื่อสร้างข้อมูลสำเร็จ เราจะส่งคืน StatusCode::CREATED (201) พร้อมกับทรัพยากรที่เพิ่งสร้างใหม่ใน Response Body, เมื่อลบข้อมูลสำเร็จ เราจะส่งคืน StatusCode::NO_CONTENT (204) โดยไม่มี Body เพราะไม่มีข้อมูลใดต้องแสดงผลอีก และหากค้นหาข้อมูลไม่พบ เราจะส่งคืน AppError::NotFound ซึ่งโค้ดการอิมพลีเมนต์ IntoResponse บน AppError ของเราจะแปลงค่านั้นเป็น HTTP 404 ที่สมบูรณ์ให้โดยอัตโนมัติ คุณจะเห็นได้ว่าแฮนด์เลอร์แต่ละตัวมีโค้ดสั้นและทำงานน้อยมาก ซึ่งนั่นคือเป้าหมายหลักที่เราต้องการ
ตัวแยกข้อมูล (Extractors)
ตัวแยกข้อมูล (extractor) คือกลไกที่ Axum ใช้เพื่อดึงข้อมูลจากคำขอขาเข้ามาให้กับฟังก์ชันของคุณ เบื้องหลังการทำงาน Extractor จะอิมพลีเมนต์เทรต FromRequest (หากต้องอ่านข้อมูลจาก Request Body) หรือเทรต FromRequestParts (หากต้องการอ่านเพียง Headers, Query Parameters, Path Parameters หรือ Metadata อื่นๆ โดยไม่แตะต้อง Body)
ตัวแยกข้อมูลที่มาพร้อมกับ Axum ในตัวนั้นครอบคลุมรูปแบบการใช้งานส่วนใหญ่ในชีวิตประจำวันอย่างครบถ้วน:
#![allow(unused)]
fn main() {
use axum::extract::{State, Path, Query, Json};
// Path parameters: /users/{id}
async fn get_user(Path(id): Path<Uuid>) -> ... { }
// Query parameters: /users?page=2&per_page=20
async fn list_users(Query(params): Query<PaginationParams>) -> ... { }
// JSON body
async fn create_user(Json(body): Json<CreateUserDto>) -> ... { }
// Application state
async fn handler(State(state): State<AppState>) -> ... { }
}
คุณสามารถใส่ตัวแยกข้อมูลหลายตัวในฟังก์ชันแฮนด์เลอร์เดียวกันได้อย่างแน่นอน โดยมีข้อจำกัดสำคัญเพียงข้อเดียวที่ต้องจำไว้คือ: ตัวแยกข้อมูลที่ต้องอ่านข้อมูลจาก Request Body (เช่น Json) จะมีได้มากที่สุดเพียงตัวเดียว และต้องวางไว้เป็นพารามิเตอร์ตัวสุดท้ายในรายการเสมอ หากคุณวางลำดับผิด คอมไพเลอร์จะแจ้งเตือนข้อผิดพลาดทันที
มาโคร #[debug_handler]
หากคุณเคยพบปัญหาคอมไพล์ฟังก์ชันแฮนด์เลอร์ไม่ผ่านเนื่องจากติด Trait Bound คุณคงรู้ดีว่ามันชวนปวดหัวขนาดไหน ข้อความ Error จากคอมไพเลอร์ในสถานการณ์นี้มักจะอ่านยากและเข้าใจซับซ้อนมาก และผมเองก็เคยเสียเวลาไปกับการนั่งแกะ Error เหล่านี้มานับไม่ถ้วน แต่ Axum มีแมโคร #[debug_handler] ที่จะช่วยให้ทุกอย่างชัดเจนและเข้าใจง่ายขึ้นอย่างมาก:
#![allow(unused)]
fn main() {
#[axum::debug_handler]
async fn my_handler(
State(state): State<AppState>,
Json(body): Json<CreateUserDto>,
) -> AppResult<Json<UserResponse>> {
// ...
}
}
สิ่งที่แมโครนี้ทำคือการเพิ่มการตรวจสอบชนิดข้อมูลแบบเจาะจง ซึ่งจะแสดงข้อความแจ้งเตือนที่มนุษย์อ่านเข้าใจได้ง่าย เช่น “argument #2 must implement FromRequest” แทนที่จะพ่นกำแพงข้อความข้อผิดพลาดของ Trait Bound ออกมาเต็มหน้าจอ แมโครนี้ไม่มีต้นทุนใดๆ ณ เวลารันไทม์ (Zero Runtime Cost) คุณจึงสามารถเปิดทิ้งไว้บน Production ได้โดยไม่มีผลกระทบ แม้บางทีมจะนิยมลบมันออกหลังจากโค้ดคอมไพล์ผ่านแล้ว แต่โดยส่วนตัวผมแนะนำให้คงไว้ เพราะนี่คือหนึ่งในตัวช่วยเล็กๆ ที่จะช่วยประหยัดเวลาของคุณได้อย่างมหาศาลเมื่อต้องกลับมาแก้ไขแฮนด์เลอร์ในอีกหกเดือนข้างหน้า
ชนิดข้อมูลการตอบกลับ
Axum มีความยืดหยุ่นสูงมากเกี่ยวกับชนิดข้อมูลที่แฮนด์เลอร์สามารถส่งคืนกลับไปได้ โดยค่าใดก็ตามที่ implement เทรต IntoResponse จะสามารถนำมาใช้ได้ทันที ซึ่งมีชนิดข้อมูลมาตรฐานที่รองรับมาในตัวมากมาย นี่คือแพตเทิร์นที่ผมหยิบมาใช้งานบ่อยที่สุด:
#![allow(unused)]
fn main() {
// Just a status code
async fn health_check() -> StatusCode {
StatusCode::OK
}
// A tuple of status code and body
async fn create_resource() -> (StatusCode, Json<Resource>) {
(StatusCode::CREATED, Json(resource))
}
// A Result for fallible operations
async fn get_resource() -> Result<Json<Resource>, AppError> {
Ok(Json(resource))
}
// Headers and body together
async fn with_headers() -> (StatusCode, [(HeaderName, &'static str); 1], Json<Data>) {
(
StatusCode::OK,
[(header::CACHE_CONTROL, "max-age=3600")],
Json(data),
)
}
}
ในความเป็นจริง คุณมักจะใช้ Result เป็นชนิดข้อมูลสำหรับส่งคืนกลับเกือบตลอดเวลา เพราะการทำงานของแฮนด์เลอร์ส่วนใหญ่ย่อมมีโอกาสเกิดข้อผิดพลาดได้เสมอ การเลือกใช้ Result<T, AppError> ร่วมกับการแปลง Error อย่างเป็นระบบที่เราจะไปสร้างกันในบท การจัดการข้อผิดพลาด จะช่วยให้โค้ดภายในแฮนด์เลอร์ของคุณสะอาดและมุ่งเน้นไปที่เส้นทางการทำงานปกติ (happy path) ได้อย่างเต็มที่
การทำให้แฮนด์เลอร์บาง
แม้ผมจะได้กล่าวถึงเรื่องนี้ไปแล้วในตอนต้น แต่ก็คุ้มค่าอย่างยิ่งที่จะย้ำเตือนอีกครั้ง เพราะผมเห็นปัญหานี้เกิดขึ้นซ้ำๆ มานับไม่ถ้วนในหลากหลายภาษาและเฟรมเวิร์ก เมื่อใดก็ตามที่ฟังก์ชันแฮนด์เลอร์ของคุณเริ่มมีความยาวเกิน 15 หรือ 20 บรรทัด นั่นมักเป็นสัญญาณเตือนว่าเริ่มมีตรรกะทางธุรกิจแอบแฝงเข้ามาอยู่ในจุดที่ไม่ถูกต้องแล้ว
อะไรที่ควรอยู่ในแฮนด์เลอร์:
- การดึงข้อมูลจากคำขอ (ผ่านตัวแยกข้อมูลของ Axum)
- การแปลงอินพุตดิบให้เป็นชนิดข้อมูลโดเมน (เรียก
UserName::parse(),Email::parse()ฯลฯ) - การเรียกเมธอดของเซอร์วิสเพียงหนึ่งเมธอด
- การเปลี่ยนผลลัพธ์ให้เป็นการตอบกลับ HTTP
อะไรที่ไม่ควรอยู่ในแฮนด์เลอร์:
- ควิวรีฐานข้อมูล
- การบังคับใช้กฎทางธุรกิจ
- การเรียกเซอร์วิสหลายตัวที่ต้องประสานงานกัน
- ตรรกะเงื่อนไขที่ซับซ้อน
- การส่งอีเมล การเผยแพร่อีเวนต์ หรือไซด์เอฟเฟกต์อื่นๆ
ถ้าแฮนด์เลอร์ของคุณต้องทำหลายสิ่งแบบประสานงานกัน ตรรกะการประสานงานนั้นควรอยู่ในเมธอดของเซอร์วิส เราจะดูวิธีจัดโครงสร้างเซอร์วิสพวกนั้นในบทถัดไป
มิดเดิลแวร์
เว็บแอปพลิเคชันแทบทุกตัวล้วนต้องมีตรรกะกลุ่มหนึ่งที่ไม่ใช่ความรับผิดชอบของแฮนด์เลอร์ตัวใดตัวหนึ่งโดยเฉพาะ แต่จำเป็นต้องทำงานครอบคลุมหลายคำขอ (หรือแทบทุกคำขอ) เช่น การบันทึก Log, การยืนยันตัวตน (Authentication), การบีบอัดข้อมูล (Compression), การจำกัดอัตราการเรียกใช้ (Rate Limiting), การกำหนด Request ID และการจำกัดเวลาประมวลผล (Timeout) ใน Axum เราจัดการงานเหล่านี้ทั้งหมดผ่าน ‘มิดเดิลแวร์ (Middleware)’ และด้วยความที่ระบบมิดเดิลแวร์ของ Axum ถูกสร้างขึ้นบน Tower เราจึงสามารถเข้าถึงระบบนิเวศอันกว้างใหญ่ของคอมโพเนนต์สำเร็จรูป พร้อมทั้งมีวิธีที่สะอาดและเป็นระเบียบในการสร้างมิดเดิลแวร์ขึ้นใช้งานเอง
จุดที่มักทำให้นักพัฒนาสะดุดบ่อยที่สุดไม่ใช่ขั้นตอนการเขียนมิดเดิลแวร์ แต่เป็นการจัดเรียงลำดับมิดเดิลแวร์ให้ถูกต้อง เราจึงจะมาเริ่มต้นทำความเข้าใจจากจุดนี้กันก่อน
โมเดลเลเยอร์ของ Tower
Tower มองมิดเดิลแวร์ในรูปแบบของ ‘เลเยอร์ (Layer)’ ที่ซ้อนห่อหุ้มเซอร์วิสไว้ เมื่อมีคำขอส่งเข้ามา คำขอนั้นจะเดินทางผ่านแต่ละเลเยอร์ตามลำดับ จากชั้นนอกสุดเข้าไปยังชั้นในสุด (ซึ่งก็คือฟังก์ชันแฮนด์เลอร์ของคุณ) จากนั้นข้อมูลการตอบกลับ (Response) ก็จะเดินทางย้อนกลับออกมาผ่านเลเยอร์เดิมในลำดับย้อนกลับ ดังนั้นเลเยอร์แรกที่คุณเพิ่มเข้าไปจึงเป็นด่านแรกที่ได้รับ Request ขาเข้า และเป็นด่านสุดท้ายที่ได้ประมวลผล Response ขาออก
Request → Compression → Tracing → Timeout → Auth → Handler
Response ← Compression ← Tracing ← Timeout ← Auth ← Handler
การจัดเรียงลำดับนี้มีความสำคัญมากกว่าที่คุณคิด หากคุณต้องการให้ Tracing บันทึกระยะเวลาการประมวลผลทั้งหมดของคำขอ ซึ่งรวมถึงเวลาที่ใช้ในการยืนยันตัวตนด้วย เลเยอร์ Tracing จะต้องอยู่ด้านนอกของเลเยอร์ Auth เสมอ หากวางสลับลำดับกัน ข้อมูลระยะเวลาของคุณจะคลาดเคลื่อนไปในแบบที่สังเกตได้ยากและชวนปวดหัวอย่างยิ่งในการตรวจสอบปัญหา
สแตกมิดเดิลแวร์ที่แนะนำ
ลองมาดูชุดมิดเดิลแวร์ (Middleware Stack) ตัวอย่างที่ผมมักเลือกใช้ในแอปพลิเคชันระดับ Production ซึ่งประกอบขึ้นอย่างเป็นระเบียบด้วย ServiceBuilder:
#![allow(unused)]
fn main() {
use tower::ServiceBuilder;
use tower_http::{
compression::CompressionLayer,
cors::CorsLayer,
limit::RequestBodyLimitLayer,
request_id::{MakeRequestUuid, SetRequestIdLayer, PropagateRequestIdLayer},
timeout::TimeoutLayer,
trace::TraceLayer,
};
use std::time::Duration;
let app = Router::new()
.merge(api_routes())
.layer(
ServiceBuilder::new()
// Layers execute top-to-bottom on the request path.
.layer(CompressionLayer::new())
.layer(SetRequestIdLayer::x_request_id(MakeRequestUuid))
.layer(TraceLayer::new_for_http())
.layer(PropagateRequestIdLayer::x_request_id())
.layer(TimeoutLayer::new(Duration::from_secs(30)))
.layer(RequestBodyLimitLayer::new(1024 * 1024)) // 1 MB
.layer(cors_layer())
)
.with_state(state);
}
เรามาไล่ดูแต่ละเลเยอร์ว่ามีหน้าที่อะไร และเพราะเหตุใดจึงต้องวางไว้ในตำแหน่งนั้นๆ:
CompressionLayer ทำหน้าที่บีบอัดข้อมูลใน Response Body ด้วย gzip (หรือ brotli หรือ deflate ขึ้นอยู่กับสิ่งที่ไคลเอนต์ระบุว่ารองรับ) พร้อมทั้งกำหนด Header Content-Encoding ให้โดยอัตโนมัติ เราวางไว้ในตำแหน่งนอกสุดเพื่อให้ทำหน้าที่บีบอัด Response Body ในขั้นตอนสุดท้าย หลังจากที่เลเยอร์ชั้นในทั้งหมดประมวลผลข้อมูลเสร็จสิ้นเรียบร้อยแล้ว (ข้อควรสังเกต: การบีบอัดจะกระทำกับ Body เท่านั้น โดยไม่แตะต้อง HTTP Headers)
SetRequestIdLayer ทำหน้าที่สร้าง UUID เฉพาะตัวและแนบเข้าไปกับคำขอขาเข้า เราวางเลเยอร์นี้ไว้ก่อนหน้า TraceLayer เพื่อให้มั่นใจว่า Request ID จะพร้อมใช้งานทันทีในจังหวะที่ Tracing Span ถูกสร้างขึ้น
TraceLayer ทำหน้าที่บันทึก Structured Logs สำหรับทุกๆ คำขอ ไม่ว่าจะเป็น HTTP Method, URL Path, Status Code และระยะเวลาที่ใช้ในการประมวลผล เนื่องจากเลเยอร์นี้ทำงานหลังจากมีการกำหนด Request ID แล้ว Tracing Span จึงมีข้อมูล Request ID ผูกติดไปด้วยเสมอ ซึ่งมีประโยชน์อย่างยิ่งในการสืบค้น Log ในภายหลัง
PropagateRequestIdLayer ทำหน้าที่คัดลอก Request ID ไปใส่ไว้ใน Response Header ขาออก เลเยอร์นี้จะอยู่ถัดจาก TraceLayer เพื่อให้ Response Header ได้รับการตั้งค่าเรียบร้อยก่อนที่ Tracing จะปิด Span ของฝั่งการตอบกลับ การเรียงลำดับในรูปแบบนี้ (สร้าง ID -> Tracing -> ส่งต่อ ID) เป็นไปตามแนวทางปฏิบัติที่แนะนำในเอกสารของ tower-http เพื่อให้ Request ID ปรากฏตรงกันอย่างสม่ำเสมอทั้งใน Log ของคำขอและใน Response Header
TimeoutLayer ทำหน้าที่ยกเลิกคำขอที่ใช้เวลาประมวลผลนานเกินกว่าที่กำหนดไว้ ซึ่งเป็นกลไกป้องกันสำคัญสำหรับรับมือกับไคลเอนต์ที่ส่งข้อมูลช้าผิดปกติ, คิวรีฐานข้อมูลที่ค้างหรือไม่คืนผลลัพธ์ หรือคำขอที่ติดบล็อกจนทำให้ระบบค้างคา
RequestBodyLimitLayer ทำหน้าที่ปฏิเสธ Request Body ที่มีขนาดเกินกว่าที่ระบบอนุญาต ซึ่งทำหน้าที่เป็นปราการด่านแรกในการป้องกันการโจมตีแบบ Denial-of-Service (DoS) จากการที่ผู้ไม่หวังดีส่งเพย์โหลดขนาดใหญ่เกินไปเข้ามาบั่นทอนทรัพยากรของเซิร์ฟเวอร์
CorsLayer ทำหน้าที่จัดการ Headers ที่เกี่ยวข้องกับ Cross-Origin Resource Sharing (CORS) แม้ตำแหน่งที่แน่นอนในสแตกจะไม่เคร่งครัดเท่าตัวอื่นๆ แต่จำเป็นต้องนำไปผูกไว้กับทุกเส้นทางที่ให้บริการ API
การตั้งค่า CORS
เรื่อง CORS สมควรที่จะแยกอธิบายเป็นหัวข้อเฉพาะ เพราะการตั้งค่า CORS ผิดพลาดคือหนึ่งในปัญหาที่ชวนปวดหัวที่สุดสำหรับนักพัฒนาเว็บ คุณคงคุ้นเคยกับอาการนี้ดี: การส่งคำขอผ่าน Postman ทำงานได้ราบรื่นสมบูรณ์ แต่กลับพังอย่างลึกลับเมื่อเรียกผ่านเว็บเบราว์เซอร์ และในทางตรงกันข้าม การเปิดอนุญาตทุก Origin อย่างหละหลวมบน Production ก็ถือเป็นช่องโหว่ด้านความปลอดภัยร้ายแรง
#![allow(unused)]
fn main() {
use tower_http::cors::CorsLayer;
use http::{Method, header};
fn cors_layer(config: &Config) -> CorsLayer {
if config.environment == Environment::Development {
CorsLayer::permissive()
} else {
let origins: Vec<HeaderValue> = config.cors_origins
.iter()
.map(|o| o.parse().expect("invalid CORS origin in config"))
.collect();
CorsLayer::new()
.allow_origin(origins)
.allow_methods([
Method::GET,
Method::POST,
Method::PUT,
Method::DELETE,
])
.allow_headers([
header::CONTENT_TYPE,
header::AUTHORIZATION,
])
.allow_credentials(true)
}
}
}
มีประเด็นสำคัญจุดหนึ่งที่ผมอยากเน้นย้ำ: เราควรกำหนดนโยบาย CORS จากค่าคอนฟิก ณ เวลารันไทม์เสมอ ไม่ใช่กำหนดตามบิลด์โปรไฟล์ของคอมไพเลอร์ การใช้เงื่อนไขอย่าง cfg!(debug_assertions) ในจุดนี้ถือว่าไม่ถูกต้อง เพราะในความเป็นจริง ไบนารีที่เป็น Release Build ที่ถูกนำไปดีพลอยต์บนสภาพแวดล้อม Staging ก็อาจยังต้องการนโยบาย CORS ที่ผ่อนปรน ในขณะที่ Debug Build ที่ใช้รันทดสอบเทียบกับข้อมูล Production ก็ควรต้องใช้นโยบายที่เข้มงวด ข้อมูลสภาพแวดล้อมและรายชื่อ Origin ที่ได้รับอนุญาตจึงควรมาจาก struct Config ที่เราสร้างขึ้นในบท การตั้งค่า
การเขียนมิดเดิลแวร์เองด้วย from_fn
ในหลายๆ กรณี คุณอาจไม่จำเป็นต้องสร้างมิดเดิลแวร์ที่ซับซ้อนเพื่อนำไปแชร์ข้ามหลายๆ โปรเจกต์ แต่เพียงแค่ต้องการตรรกะบางอย่างให้ทำงานกับคำขอในแอปพลิเคชันนี้เท่านั้น สำหรับโจทย์ดังกล่าว Axum มีฟังก์ชัน middleware::from_fn ที่ช่วยให้คุณสามารถเขียนมิดเดิลแวร์ขึ้นมาเป็นฟังก์ชัน async ธรรมดาๆ ได้ทันที ซึ่งง่ายกว่าการเขียนอิมพลีเมนต์เทรต Layer และ Service ของ Tower แบบเต็มรูปแบบมาก และจากประสบการณ์ของผม วิธีนี้ครอบคลุมความต้องการมิดเดิลแวร์ที่สร้างขึ้นเองได้เกือบทั้งหมด
#![allow(unused)]
fn main() {
use axum::{
extract::Request,
middleware::Next,
response::Response,
};
async fn timing_middleware(req: Request, next: Next) -> Response {
let start = std::time::Instant::now();
let method = req.method().clone();
let uri = req.uri().clone();
let response = next.run(req).await;
let duration = start.elapsed();
tracing::info!(
method = %method,
uri = %uri,
status = %response.status(),
duration_ms = %duration.as_millis(),
"request completed"
);
response
}
}
การนำมิดเดิลแวร์นี้ไปผูกกับเราเตอร์ของคุณก็ทำได้อย่างตรงไปตรงมา:
#![allow(unused)]
fn main() {
use axum::middleware;
let app = Router::new()
.merge(api_routes())
.layer(middleware::from_fn(timing_middleware))
.with_state(state);
}
แต่หากมิดเดิลแวร์ของคุณจำเป็นต้องเข้าถึง State ของแอปพลิเคชันด้วยล่ะ เช่น ต้องการดึง JWT Secret ออกมาใช้ในการตรวจสอบยืนยันตัวตน? นั่นคือจังหวะที่ฟังก์ชัน from_fn_with_state จะเข้ามาช่วย:
#![allow(unused)]
fn main() {
async fn auth_middleware(
State(state): State<AppState>,
mut req: Request,
next: Next,
) -> Result<Response, AppError> {
let token = req.headers()
.get(header::AUTHORIZATION)
.and_then(|v| v.to_str().ok())
.and_then(|v| v.strip_prefix("Bearer "))
.ok_or(AppError::Unauthorized)?;
let claims = decode_jwt(token, state.config.jwt_secret.expose_secret())
.map_err(|_| AppError::Unauthorized)?;
// Store the authenticated user in request extensions so handlers can access it
req.extensions_mut().insert(AuthUser::from(claims));
Ok(next.run(req).await)
}
// Apply to specific routes
let protected_routes = Router::new()
.route("/profile", get(get_profile))
.route("/settings", put(update_settings))
.route_layer(middleware::from_fn_with_state(state.clone(), auth_middleware));
}
route_layer เทียบกับ layer
ความแตกต่างตรงนี้เป็นจุดที่หลายคนมักพลาดบ่อยมาก และมันส่งผลต่อความถูกต้องของการทำงานโดยตรง
.layer() จะครอบมิดเดิลแวร์กับทุกเส้นทางบนเราเตอร์ รวมถึง fallback handler สำหรับ path ที่ไม่ตรงกับ route ใดๆ ด้วย หากคุณใส่ middleware ยืนยันตัวตนไว้ตรงนี้ แม้แต่การตอบกลับ 404 สำหรับ path ที่ไม่มีอยู่จริงก็ยังต้องผ่านการยืนยันตัวตนก่อน ซึ่งแทบไม่เคยเป็นสิ่งที่คุณต้องการ และจะทำให้เกิดพฤติกรรมที่ชวนสับสนตรงที่ผู้ใช้ที่ยังไม่ได้ยืนยันตัวตนจะได้รับ 401 แทนที่จะเป็น 404 เมื่อเรียก path ที่ไม่มีอยู่จริง
.route_layer() จะครอบมิดเดิลแวร์เฉพาะกับเส้นทางที่จับคู่ route ได้สำเร็จเท่านั้น ส่วน path ที่ไม่ตรงกับ route ใดๆ จะส่งต่อไปยัง fallback handler โดยไม่ผ่าน middleware นี้เลย ซึ่งนี่คือสิ่งที่คุณต้องการสำหรับการยืนยันตัวตน (Authentication) และการตรวจสอบสิทธิ์ (Authorization)
#![allow(unused)]
fn main() {
let app = Router::new()
// Public routes
.route("/health", get(health_check))
.route("/api/v1/auth/login", post(login))
// Protected routes
.nest("/api/v1", protected_routes)
// Global middleware (applied to everything)
.layer(TraceLayer::new_for_http())
.with_state(state);
let protected_routes = Router::new()
.nest("/users", user_routes())
.nest("/posts", post_routes())
// Auth middleware only applies to matched routes
.route_layer(middleware::from_fn_with_state(state, auth_middleware));
}
เครตมิดเดิลแวร์ที่มีให้ใช้
ก่อนที่คุณจะเริ่มลงมือเขียน middleware ขึ้นมาเอง แนะนำให้ลองเช็กดูก่อนว่ามีคนแก้ปัญหานี้ไว้แล้วหรือยัง เพราะ ecosystem ของ Tower และ tower-http นั้นมีเครื่องมือให้ใช้อย่างครบครันมาก:
- tower-http มี
CorsLayer,CompressionLayer,TraceLayer,TimeoutLayer,RequestBodyLimitLayer,SetRequestIdLayerและอื่นๆ อีกมากมาย - tower-governor รองรับ rate limiting โดยอิงตามอัลกอริทึม governor
- tower-sessions จัดการ session ฝั่งเซิร์ฟเวอร์
- tower-cookies จัดการ cookie
- axum-csrf-sync-pattern อิมพลีเมนต์ OWASP CSRF Synchronizer Token Pattern
จากประสบการณ์ของผม ระบบนิเวศ Tower ครอบคลุมสิ่งที่จำเป็นต่อการใช้งานส่วนใหญ่แบบพร้อมใช้ทันที ซึ่งนี่เป็นหนึ่งในเหตุผลที่ดีที่สุดในการเลือกใช้ Axum ตั้งแต่แรก เมื่อเราไปถึงบท การรวมทุกอย่างเข้าด้วยกัน คุณจะได้เห็นว่ามิดเดิลแวร์ทุกเลเยอร์เหล่านี้ประกอบเข้าด้วยกันในแอปพลิเคชันที่สมบูรณ์ได้อย่างไร
การตรวจสอบความถูกต้องของคำขอ
ถ้าคุณเคยส่งฟอร์มขึ้น production โดยไม่มีการ validation ฝั่งเซิร์ฟเวอร์เพราะคิดว่าฝั่งฟรอนต์เอนด์ “ตรวจให้แล้ว” คุณคงรู้ดีว่าจุดจบมักเป็นอย่างไร การทำ client-side validation ช่วยเรื่อง UX ให้ใช้งานได้ลื่นไหล แต่มันไม่ใช่แนวป้องกันด้านความปลอดภัย (security boundary) เลย เพราะใครก็ตามที่ใช้ curl ย่อมไม่สนใจโค้ด JavaScript ของคุณอยู่แล้ว ดังนั้นเราจึงต้องทำ validation ฝั่งเซิร์ฟเวอร์เสมอ
จากประสบการณ์ของผม การ validation ในแอปพลิเคชันที่มีโครงสร้างดีจะแบ่งออกเป็น 2 ระดับอย่างเป็นธรรมชาติ ที่ API layer เราจะตรวจสอบโครงสร้างและรูปแบบของข้อมูลที่ส่งเข้ามา: มีฟิลด์ที่จำเป็นครบถ้วนไหม? ฟิลด์อีเมลดูเหมือนอีเมลจริงไหม? รหัสผ่านยาวพอไหม? จากนั้นที่ Domain layer เราจะบังคับใช้กฎทางธุรกิจ (business invariants) ผ่านระบบ type system ซึ่งผมได้อธิบายไว้แล้วในบท การสร้างแบบจำลองโดเมน
บทนี้จะเน้นไปที่ระดับแรก นั่นคือการ validation ที่ API layer โดยเราจะใช้ crate validator และสร้าง custom extractor ของ Axum ขึ้นมาเพื่อให้ทุกอย่างทำงานประสานกันได้อย่างไร้รอยต่อ
การตรวจสอบความถูกต้องด้วยเครต validator
crate validator มี derive macro ที่ช่วยให้เรากำหนดกฎ validation บนฟิลด์ของ struct ได้โดยตรง เพียงคุณเรียก .validate() บน instance ของ struct ตัว crate จะตรวจสอบทุกกฎที่กำหนดไว้ และส่ง structured error กลับมาหากมีจุดใดไม่ผ่านเกณฑ์ มาดูกันว่าเวลาใช้งานจริงมีหน้าตาเป็นอย่างไร
#![allow(unused)]
fn main() {
use serde::Deserialize;
use validator::Validate;
#[derive(Debug, Deserialize, Validate)]
pub struct CreateUserDto {
#[validate(length(min = 2, max = 50, message = "name must be between 2 and 50 characters"))]
pub name: String,
#[validate(email(message = "must be a valid email address"))]
pub email: String,
#[validate(length(min = 8, message = "password must be at least 8 characters"))]
pub password: String,
}
#[derive(Debug, Deserialize, Validate)]
pub struct UpdateUserDto {
#[validate(length(min = 2, max = 50, message = "name must be between 2 and 50 characters"))]
pub name: Option<String>,
#[validate(length(max = 500, message = "bio cannot exceed 500 characters"))]
pub bio: Option<String>,
#[validate(url(message = "must be a valid URL"))]
pub avatar_url: Option<String>,
}
}
crate validator มาพร้อมตัวตรวจสอบ (validators) ในตัวที่ครอบคลุมมาก: email, url, length, range, contains, must_match (สะดวกมากสำหรับการยืนยันรหัสผ่าน) และอื่นๆ อีกมากมาย แต่หากคุณต้องการเงื่อนไขเฉพาะทางที่ไม่ตรงกับตัวตรวจสอบที่มีให้ คุณก็เขียนฟังก์ชัน validation ขึ้นมาเองได้เช่นกัน
extractor ValidatedJson ที่กำหนดเอง
ตัวแยกข้อมูล Json ในตัวของ Axum จัดการเรื่อง deserialization ให้เราก็จริง แต่มันไม่ได้รัน validation ใดๆ ให้เลย คุณอาจเลือกเรียก .validate() ด้วยตนเองที่จุดเริ่มต้นของทุก handler แต่วิธีนี้จะกลายเป็นเรื่องน่าเบื่ออย่างรวดเร็ว และมีโอกาสเผลอลืมได้ง่ายมาก สิ่งที่ผมพบว่าได้ผลดีกว่ามากคือการสร้าง custom extractor ที่รวมทั้งการ deserialize และ validate เข้าด้วยกันในขั้นตอนเดียว
#![allow(unused)]
fn main() {
use axum::{
extract::{FromRequest, Request},
Json,
};
use validator::Validate;
pub struct ValidatedJson<T>(pub T);
impl<T, S> FromRequest<S> for ValidatedJson<T>
where
T: serde::de::DeserializeOwned + Validate,
S: Send + Sync,
{
type Rejection = AppError;
async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
let Json(value) = Json::<T>::from_request(req, state)
.await
.map_err(|e| AppError::Validation(format!("invalid JSON: {e}")))?;
value.validate().map_err(|e| {
AppError::ValidationFields(format_validation_errors(&e))
})?;
Ok(Self(value))
}
}
fn format_validation_errors(
errors: &validator::ValidationErrors,
) -> HashMap<String, Vec<String>> {
errors
.field_errors()
.iter()
.map(|(field, errs)| {
let messages = errs
.iter()
.map(|e| {
e.message
.as_ref()
.map(|m| m.to_string())
.unwrap_or_else(|| format!("{} is invalid", field))
})
.collect();
(field.to_string(), messages)
})
.collect()
}
}
ตอนนี้ handler ของเราสามารถรับ ValidatedJson<CreateUserDto> แทน Json<CreateUserDto> ได้แล้ว และการ validation จะเกิดขึ้นก่อนที่ body ของ handler จะเริ่มทำงานด้วยซ้ำ หากการตรวจสอบล้มเหลว ไคลเอนต์จะได้รับ response 400 พร้อมข้อความข้อผิดพลาดที่ชัดเจนซึ่งระบุว่าฟิลด์ไหนบ้างที่ผิดพลาดและผิดเพราะอะไร โดยที่เราไม่ต้องเขียนโค้ดเพิ่มใน handler เลย
#![allow(unused)]
fn main() {
async fn create_user(
State(state): State<AppState>,
ValidatedJson(payload): ValidatedJson<CreateUserDto>,
) -> AppResult<(StatusCode, Json<UserResponse>)> {
// By this point, we know:
// - The JSON was well-formed
// - name is between 2 and 50 characters
// - email is a valid email format
// - password is at least 8 characters
//
// The handler can focus on business logic.
let user = state.user_service.register(payload).await?;
Ok((StatusCode::CREATED, Json(user.into())))
}
}
การตรวจสอบความถูกต้องของพารามิเตอร์ควิวรี
เราสามารถนำแนวทางเดียวกันนี้มาใช้กับ query parameters ได้เช่นกัน โดยสร้าง extractor ValidatedQuery ที่รวมการดึงข้อมูล Query เข้ากับการตรวจสอบความถูกต้อง:
#![allow(unused)]
fn main() {
use axum::extract::Query;
pub struct ValidatedQuery<T>(pub T);
impl<T, S> FromRequestParts<S> for ValidatedQuery<T>
where
T: serde::de::DeserializeOwned + Validate,
S: Send + Sync,
{
type Rejection = AppError;
async fn from_request_parts(
parts: &mut http::request::Parts,
state: &S,
) -> Result<Self, Self::Rejection> {
let Query(value) = Query::<T>::from_request_parts(parts, state)
.await
.map_err(|e| AppError::Validation(format!("invalid query parameters: {e}")))?;
value.validate().map_err(|e| {
AppError::ValidationFields(format_validation_errors(&e))
})?;
Ok(Self(value))
}
}
}
การตอบกลับข้อผิดพลาดแบบมีโครงสร้าง
หาก API ของคุณมีนักพัฒนาคนอื่นนำไปใช้งานต่อ (ซึ่งโดยทั่วไปก็เป็นเช่นนั้น) คุณย่อมต้องการส่ง validation error กลับไปในรูปแบบที่มีโครงสร้างชัดเจนเพื่อให้ฝั่งผู้เรียกสามารถ parse ข้อมูลไปใช้งานต่อได้จริง ไม่ใช่สตริงข้อความเดี่ยวยาวๆ ผมชอบส่งข้อผิดพลาดกลับไปเป็น JSON object ที่แจกแจงรายการข้อผิดพลาดแยกตามรายฟิลด์:
{
"error": {
"type": "validation_error",
"message": "request validation failed",
"fields": {
"email": ["must be a valid email address"],
"password": ["password must be at least 8 characters"]
}
}
}
เพื่อให้ใช้งานแบบนี้ได้ เราต้องขยาย enum AppError ของเราให้เก็บข้อผิดพลาดรายฟิลด์แบบมีโครงสร้าง และปรับการอิมพลีเมนต์ IntoResponse เพื่อจัดรูปแบบข้อมูล รูปแบบที่แน่นอนขึ้นอยู่กับข้อตกลงที่ API ของคุณใช้ แต่หลักการสำคัญเหมือนกัน: ให้ข้อมูลกับไคลเอนต์มากพอที่จะแก้ไขทุกอย่างได้จบในรอบเดียว ไม่มีใครอยากแก้ทีละฟิลด์ ส่งใหม่ แล้วเพิ่งมาเจอข้อผิดพลาดของฟิลด์ถัดไปเรื่อยๆ
extractor การตรวจสอบความถูกต้องที่สร้างไว้แล้ว
หากคุณรู้สึกว่าการเขียน custom extractor ขึ้นมาเองดูมี boilerplate มากเกินไป ใน ecosystem ก็มี crate ทางเลือกให้พร้อมใช้:
- axum-valid รองรับการผสานงานกับทั้ง
validator,gardeและvalidifyโดยมี extractor อย่างValid<Json<T>>,Valid<Query<T>>และValid<Form<T>>ให้ใช้ - axum-validated-extractors มี
ValidatedJson,ValidatedQueryและValidatedFormให้พร้อมใช้ได้ทันที
crate เหล่านี้ช่วยคุณประหยัด boilerplate ที่เราเขียนกันข้างบนได้ ถึงอย่างนั้น ผมมักจะชอบเขียนเองมากกว่า เพราะช่วยให้เราควบคุมรูปแบบและพฤติกรรมของข้อผิดพลาดได้เต็มที่ ซึ่งสำคัญมากเมื่อคุณต้องการกำหนดมาตรฐานการตอบกลับข้อผิดพลาดของ API ให้ตรงใจ (และเชื่อเถอะว่าคุณจะต้องอยากปรับแน่นอน)
การตรวจสอบความถูกต้องสองระดับ
ก่อนจะไปต่อ ผมอยากเน้นย้ำความแตกต่างระหว่างการตรวจสอบความถูกต้องที่ระดับ API layer กับ Domain layer ให้ชัดเจนมาก เพราะการเอาทั้งสองมารวมปนกันมักนำไปสู่ตรรกะซ้ำซ้อนหรือเกิดช่องโหว่ในระบบรักษาความปลอดภัยของคุณ ผมเคยเห็นทั้งสองแบบมาแล้ว และไม่มีแบบไหนที่ตามแก้ได้สนุกเลย
การตรวจสอบความถูกต้องที่ระดับ API layer (สิ่งที่เรากล่าวถึงในบทนี้) จะตรวจสอบโครงสร้างและรูปแบบของอินพุต: ฟิลด์ที่จำเป็นมีครบไหม? ความยาวสตริงถูกต้องตามเกณฑ์ไหม? ฟิลด์อีเมลดูเหมือนอีเมลจริงไหม? ทั้งหมดนี้เป็นเรื่องของรูปแบบข้อมูลตอนที่เดินทางมาถึงผ่านเครือข่าย (over the wire)
การตรวจสอบความถูกต้องที่ระดับ Domain layer (ซึ่งเรากล่าวถึงในบท การสร้างแบบจำลองโดเมน) จะทำหน้าที่บังคับใช้กฎเกณฑ์และเงื่อนไขทางธุรกิจ (business invariants): เช่น ชื่อผู้ใช้ต้องไม่มีอักขระต้องห้าม, อีเมลต้องถูกแปลงเป็นตัวพิมพ์เล็กทั้งหมด, ยอดเงินของออเดอร์ต้องเป็นบวก การตรวจสอบความถูกต้องนี้จะเกิดขึ้นตอนที่คุณสร้างชนิดข้อมูลโดเมน เช่น UserName::parse() หรือ Email::parse()
การตรวจสอบทั้งสองระดับนี้ทำงานประสานกันได้อย่างลงตัว API layer จะช่วยสกัดอินพุตที่ผิดรูปแบบอย่างชัดเจนได้ตั้งแต่เนิ่นๆ พร้อมส่งข้อความแจ้งข้อผิดพลาดที่เป็นประโยชน์ ส่วน Domain layer จะรับประกันว่ากฎทางธุรกิจถูกบังคับใช้อย่างสม่ำเสมอ ไม่ว่าข้อมูลจะมาจากคำขอ HTTP, คิวข้อความ, การนำเข้าไฟล์ CSV หรือชุดทดสอบ และเมื่อมีครบทั้งสองระดับ เราก็จะมีรากฐานที่แข็งแกร่งสำหรับแพตเทิร์นการจัดการข้อผิดพลาดที่เราจะดูกันต่อไป
การยืนยันตัวตนและการอนุญาตสิทธิ์
เว็บแอปพลิเคชันเกือบทุกตัวจะต้องตอบคำถามพื้นฐาน 2 ข้อให้ได้เสมอ: “ใครเป็นคนส่ง request นี้มา?” และ “พวกเขามีสิทธิ์ทำสิ่งที่ร้องขอหรือไม่?” ข้อแรกคือการยืนยันตัวตน (Authentication) ส่วนข้อหลังคือการตรวจสอบสิทธิ์ (Authorization) และหากแอปพลิเคชันของคุณมีการจัดการข้อมูลผู้ใช้หรือมีส่วนที่ต้องควบคุมการเข้าถึง คุณย่อมจำเป็นต้องมีทั้งสองอย่างนี้อย่างแน่นอน
สิ่งที่ผมประทับใจเป็นพิเศษเกี่ยวกับ Axum ในเรื่องนี้คือระบบ extractor เพราะเราสามารถสร้าง custom extractor เพื่อตรวจเช็ก credentials และสิทธิ์ของผู้ใช้ได้โดยตรง ทำให้การเพิ่มระบบ auth เข้าไปใน handler ง่ายดายเพียงแค่ใส่ extractor ที่เหมาะสมลงไปในพารามิเตอร์ของฟังก์ชัน มาดูกันว่าแนวทางนี้ทำงานอย่างไร
การเลือกกลยุทธ์การยืนยันตัวตน
แนวทางที่เหมาะสมจะขึ้นอยู่กับว่าไคลเอนต์ของคุณคือใครเป็นหลัก:
แอปพลิเคชันบนเบราว์เซอร์แบบ First-party ควรเลือกใช้ server-side sessions ร่วมกับ cookie โดยคุณควรเก็บ session ID ไว้ใน cookie ที่ตั้งค่า HttpOnly, Secure, SameSite=Strict ซึ่งหมายความว่าโค้ด JavaScript จะไม่สามารถเข้าถึง cookie นี้ได้ ช่วยลดความเสี่ยงจากการถูกขโมย cookie ผ่านการโจมตี XSS ได้อย่างมีนัยสำคัญ ทั้งนี้ผมต้องขอชี้แจงว่า HttpOnly ไม่ได้ป้องกันช่องโหว่ XSS โดยตรง เพราะ script ที่ถูกฝังเข้ามายังอาจแอบทำ action แทนผู้ใช้หรือขโมยข้อมูลอื่นบนหน้าเว็บได้ แต่มันช่วยตัดทางโจมตีที่พบบ่อยที่สุดอย่างการขโมย session token ออกไปโดยตรง ซึ่งนี่คือเหตุผลที่ทั้ง OWASP และ MDN ต่างแนะนำแนวทางนี้ ฝั่งเซิร์ฟเวอร์จะเก็บสถานะของ session (user ID, สิทธิ์การใช้งาน, วันหมดอายุ) ไว้ในฐานข้อมูลหรือ Redis เพื่อให้สามารถสั่งเพิกถอนสิทธิ์ (revoke) ได้ทันที โดย crate tower-sessions มี middleware สำหรับจัดการ session บน Axum และ axum-login จะช่วยวางเลเยอร์การระบุตัวตน ยืนยันตัวตน และตรวจสอบสิทธิ์ครอบทับอีกชั้น หากคุณเลือกใช้ session ร่วมกับ cookie คุณจำเป็นต้องมีมาตรการป้องกัน CSRF ตามที่อธิบายไว้ในบท ความปลอดภัย ด้วยเสมอ
API แบบ Service-to-service และการเชื่อมต่อกับ Third-party เป็นจุดที่ stateless JWT โดดเด่นเป็นพิเศษ ไคลเอนต์จะแนบ token มาใน header Authorization: Bearer และเซิร์ฟเวอร์สามารถตรวจสอบความถูกต้องได้ทันทีโดยไม่ต้อง query ฐานข้อมูล วิธีนี้สะดวกอย่างยิ่งสำหรับ machine clients ที่ไม่มี browser cookies และยัง scale แนวนอนได้ง่ายเพราะไม่มี session state ฝั่งเซิร์ฟเวอร์ให้ต้องแชร์กัน ข้อแลกเปลี่ยนคือ JWT จะไม่สามารถยกเลิกก่อนเวลาหมดอายุได้ เว้นแต่คุณจะสร้าง infrastructure เพิ่มเติมเข้ามารองรับ (เช่น denylist หรือการใช้อายุ token สั้นๆ ควบคู่กับ refresh token)
Public API สำหรับบุคคลภายนอก มักเลือกใช้ OAuth2/OIDC โดยจะมี Identity Provider คอยออก token ให้ แล้ว API ของคุณทำหน้าที่ตรวจสอบความถูกต้อง crate อย่าง jwt-authorizer จะช่วยรองรับทั้ง OIDC discovery และการหมุนเวียนคีย์ (key rotation) แบบอัตโนมัติสำหรับกรณีการใช้งานลักษณะนี้
สำหรับเนื้อหาที่เหลือในบทนี้ เราจะเน้นไปที่แนวทาง JWT เนื่องจากเป็นแพตเทิร์นที่นิยมใช้กันมากที่สุดสำหรับ API service และยังแสดงให้เห็นถึงพลังของระบบ extractor ใน Axum ได้อย่างชัดเจน แต่หากคุณกำลังพัฒนาเว็บแอปพลิเคชันที่มีผู้ใช้เข้าใช้งานผ่านเบราว์เซอร์เป็นหลัก ผมแนะนำให้เริ่มต้นด้วย tower-sessions และ axum-login แทน
การยืนยันตัวตนแบบ JWT ด้วย extractor ที่กำหนดเอง
JWT ตอบโจทย์ได้ดีมากกับการยืนยันตัวตนบน API แบบ stateless โดยมี flow การทำงานที่ตรงไปตรงมา: ไคลเอนต์ยืนยันตัวตน (โดยทั่วไปใช้อีเมลและรหัสผ่าน) แล้วรับ JWT กลับไป จากนั้นก็นำมาแนบใน header Authorization สำหรับทุกๆ request ถัดไป ฝั่งเซิร์ฟเวอร์จะตรวจสอบความถูกต้องของ token ในแต่ละ request ได้ทันทีโดยไม่ต้องเสียเวลาค้นหาข้อมูลใน database
หัวใจสำคัญที่ทำให้โครงสร้างนี้เป็นระเบียบเรียบร้อยใน Axum คือการสร้าง custom extractor ที่อิมพลีเมนต์ FromRequestParts เมื่อคุณใส่ extractor นี้ไว้ใน signature ของ handler ตัว Axum จะรันขั้นตอนตรวจสอบ token ให้อัตโนมัติก่อนที่ code logic ภายใน handler จะเริ่มทำงานด้วยซ้ำ มาดูกันว่าโค้ดจริงมีหน้าตาเป็นอย่างไร:
#![allow(unused)]
fn main() {
use axum::{
extract::FromRequestParts,
http::request::Parts,
};
use axum_extra::{
headers::{Authorization, authorization::Bearer},
TypedHeader,
};
use jsonwebtoken::{decode, Algorithm, DecodingKey, Validation};
/// Represents an authenticated user. Including this in a handler's
/// signature automatically requires and validates a JWT.
#[derive(Debug, Clone)]
pub struct AuthUser {
pub user_id: Uuid,
pub email: String,
pub role: Role,
}
#[derive(Debug, Clone, Deserialize, Serialize)]
pub struct Claims {
pub sub: Uuid, // subject (user ID)
pub email: String,
pub role: Role,
pub iss: String, // issuer
pub aud: String, // audience
pub exp: usize, // expiration time
pub iat: usize, // issued at
}
impl<S> FromRequestParts<S> for AuthUser
where
AppState: FromRef<S>,
S: Send + Sync,
{
type Rejection = AppError;
async fn from_request_parts(
parts: &mut Parts,
state: &S,
) -> Result<Self, Self::Rejection> {
let app_state = AppState::from_ref(state);
// Extract the Authorization: Bearer <token> header
let TypedHeader(Authorization(bearer)) = parts
.extract::<TypedHeader<Authorization<Bearer>>>()
.await
.map_err(|_| AppError::Unauthorized)?;
// Decode and validate the JWT with explicit validation rules.
// Validation::default() uses HS256 and checks exp, but you should
// be explicit about what you accept in production.
let mut validation = Validation::new(Algorithm::HS256);
validation.set_issuer(&["myapp"]);
validation.set_audience(&["myapp-api"]);
validation.leeway = 30; // 30 seconds of clock skew tolerance
let token_data = decode::<Claims>(
bearer.token(),
&DecodingKey::from_secret(
app_state.config.jwt_secret.expose_secret().as_bytes()
),
&validation,
)
.map_err(|_| AppError::Unauthorized)?;
Ok(AuthUser {
user_id: token_data.claims.sub,
email: token_data.claims.email,
role: token_data.claims.role,
})
}
}
}
การนำไปใช้งานใน handler นั้นง่ายเพียงแค่เพิ่มพารามิเตอร์เข้าไปใน function signature:
#![allow(unused)]
fn main() {
async fn get_my_profile(
user: AuthUser,
State(state): State<AppState>,
) -> AppResult<Json<ProfileResponse>> {
let profile = state.user_service
.get_by_id(UserId::from_uuid(user.user_id))
.await?
.ok_or(AppError::NotFound)?;
Ok(Json(profile.into()))
}
}
หากไม่มี JWT แนบมา, token หมดอายุแล้ว, หรือไม่ถูกต้อง ตัว extractor ของเราจะคืน AppError::Unauthorized และโค้ดใน handler จะไม่ถูกรันเลยแม้แต่น้อย ไม่มีโค้ดตรวจเช็ก auth ปะปนอยู่ในตัว handler ซึ่งเป็นการแบ่งแยกหน้าที่ (separation of concerns) ที่ชัดเจนและสวยงามมาก
การยืนยันตัวตนแบบไม่บังคับด้วย MaybeAuthUser
บาง endpoint อาจมีพฤติกรรมแตกต่างกันขึ้นอยู่กับว่าผู้เรียกเข้าสู่ระบบแล้วหรือยัง โดยไม่ได้บังคับว่าต้องล็อกอินเสมอไป เช่น endpoint ดึงฟีดข่าวที่แสดงผลเฉพาะบุคคลสำหรับผู้ใช้ที่เข้าสู่ระบบแล้ว แต่จะแสดงเนื้อหาทั่วไปสำหรับผู้เยี่ยมชมที่ไม่ระบุตัวตน
คุณอาจอยากใช้แค่ Option<AuthUser> ตรงจุดนี้ แต่การทำแบบนั้นจะทำให้เราสูญเสียความแตกต่างที่สำคัญมากไป เพราะค่า None อาจหมายถึง “ไม่ได้ส่ง Authorization header มาเลย” (เป็น anonymous user จริงๆ) หรืออาจหมายถึง “ส่ง Authorization header มา แต่ token นั้นผิดพลาดหรือใช้การไม่ได้” (ซึ่งควรได้ 401 ไม่ใช่การถอยกลับไปเป็นพฤติกรรมแบบ anonymous user ไปเงียบๆ) สถานการณ์สองแบบนี้แตกต่างกันอย่างสิ้นเชิง
การสร้าง custom extractor อย่าง MaybeAuthUser ช่วยให้เราแยกแยะสองกรณีนี้ออกจากกันได้อย่างชัดเจน:
#![allow(unused)]
fn main() {
pub struct MaybeAuthUser(pub Option<AuthUser>);
impl<S> FromRequestParts<S> for MaybeAuthUser
where
AppState: FromRef<S>,
S: Send + Sync,
{
type Rejection = AppError;
async fn from_request_parts(
parts: &mut Parts,
state: &S,
) -> Result<Self, Self::Rejection> {
// If there is no Authorization header at all, that is fine.
let Some(auth_header) = parts.headers.get(header::AUTHORIZATION) else {
return Ok(Self(None));
};
// But if a header IS present, it must be valid.
// An invalid token is an error, not anonymous access.
let token = auth_header
.to_str()
.ok()
.and_then(|v| v.strip_prefix("Bearer "))
.ok_or(AppError::Unauthorized)?;
let app_state = AppState::from_ref(state);
let mut validation = Validation::new(Algorithm::HS256);
validation.set_issuer(&["myapp"]);
validation.set_audience(&["myapp-api"]);
let token_data = decode::<Claims>(
token,
&DecodingKey::from_secret(
app_state.config.jwt_secret.expose_secret().as_bytes()
),
&validation,
)
.map_err(|_| AppError::Unauthorized)?;
Ok(Self(Some(AuthUser {
user_id: token_data.claims.sub,
email: token_data.claims.email,
role: token_data.claims.role,
})))
}
}
}
ผมได้แพตเทิร์นนี้มาจาก reference implementation ใน launchbadge/realworld-axum-sqlx ซึ่งระบุไว้ชัดเจนว่าเป็นความตั้งใจในการออกแบบ แม้จะเป็นรายละเอียดเล็กๆ แต่ก็ช่วยป้องกันหมวดหมู่บั๊กด้าน auth ที่ตรวจจับได้ยาก นั่นคือกรณีที่ไคลเอนต์ส่ง token ผิดรูปเข้ามาแล้วระบบกลับทำงานแบบ anonymous user ไปเงียบๆ แทนที่จะแจ้ง error ออกมาให้ชัดเจน
การออกโทเคน
ทีนี้มาดูอีกด้านหนึ่งกันบ้าง: โค้ดฝั่งสร้างและออก token ทำงานอย่างไรจริงๆ? endpoint ล็อกอินจะทำการตรวจสอบ credentials ของผู้ใช้ แล้วจึงออก JWT ให้ดังนี้:
#![allow(unused)]
fn main() {
use jsonwebtoken::{encode, EncodingKey, Header};
async fn login(
State(state): State<AppState>,
Json(credentials): Json<LoginDto>,
) -> AppResult<Json<TokenResponse>> {
let user = state.user_service
.authenticate(&credentials.email, &credentials.password)
.await?
.ok_or(AppError::Unauthorized)?;
let now = chrono::Utc::now();
let claims = Claims {
sub: *user.id().as_uuid(),
email: user.email().as_str().to_string(),
role: user.role().clone(),
iss: "myapp".to_string(),
aud: "myapp-api".to_string(),
iat: now.timestamp() as usize,
// Short-lived access tokens limit damage if compromised.
// For longer sessions, implement a refresh token mechanism.
exp: (now + chrono::TimeDelta::try_minutes(15).expect("valid duration"))
.timestamp() as usize,
};
let token = encode(
&Header::default(),
&claims,
&EncodingKey::from_secret(
state.config.jwt_secret.expose_secret().as_bytes()
),
)
.map_err(|e| AppError::Internal(e.into()))?;
Ok(Json(TokenResponse { token }))
}
}
มีข้อควรพิจารณาสำคัญสำหรับ production หลายข้อที่มักถูกมองข้ามได้ง่าย:
อายุของโทเคน (Token lifetime) ตัวอย่างข้างต้นใช้ access token ที่มีอายุเพียง 15 นาที การกำหนดอายุ token ให้สั้นจะช่วยจำกัดความเสียหายหาก token หลุดรอดไป สำหรับแอปพลิเคชันที่ต้องการให้ผู้ใช้ล็อกอินค้างไว้ได้นานขึ้น คุณควรมีกลไก refresh token แยกต่างหาก โดยเก็บ refresh token ไว้ใน HttpOnly cookie ที่ปลอดภัย และสามารถสั่ง revoke ฝั่งเซิร์ฟเวอร์ได้
การตรึงอัลกอริทึม (Algorithm pinning) ควรกำหนดอัลกอริทึมที่ยอมรับอย่างชัดเจนเสมอ (ในที่นี้คือ Algorithm::HS256) แทนที่จะเชื่อค่าใน header alg ที่ส่งมากับตัว token โดยตรง การยอมรับอัลกอริทึมตามที่ตัว token ระบุมาถือเป็นช่องทางการโจมตีที่เป็นที่รู้จักกันดี และผมเคยเห็นหลายทีมต้องเจ็บปวดกับเรื่องนี้เพราะคิดว่าตัวเองกำลังเขียนโค้ดให้ยืดหยุ่น
ผู้ออกและผู้รับโทเคน (Issuer and Audience) การระบุ claim iss และ aud พร้อมตรวจสอบค่าเหล่านี้ตอน decode จะช่วยป้องกันไม่ให้ token ที่สร้างขึ้นสำหรับ service หนึ่งถูกนำไปสวมรอยใช้กับอีก service หนึ่ง ซึ่งจุดนี้สำคัญมากเมื่อระบบของคุณมีหลาย service ที่ใช้ secret ร่วมกันหรือเชื่อมต่อกับ Identity Provider เดียวกัน
Role claims กับการเพิกถอนสิทธิ์ (Revocation) เรื่องนี้มักสร้างความประหลาดใจให้หลายคน: การฝัง role ไว้ใน JWT แปลว่าเมื่อมีการเปลี่ยนสิทธิ์ผู้ใช้ (เช่น ปลดสิทธิ์ admin หรือระงับบัญชี) การเปลี่ยนแปลงนั้นจะยังไม่มีผลจนกว่า token เดิมจะหมดอายุและมีการออก token ใหม่ หากระบบของคุณจำเป็นต้องตัดสิทธิ์ได้ทันที คุณจะต้องเลือกใช้อายุ token ที่สั้นมากๆ หรือตรวจสอบ token version เทียบกับฐานข้อมูล หรือสร้าง denylist ขึ้นมาช่วย
การแฮชรหัสผ่าน
ทุกคนย่อมทราบดีอยู่แล้วว่าไม่ควรเก็บรหัสผ่านเป็น plain text แต่การเลือกอัลกอริทึมสำหรับ hash รหัสผ่านก็สำคัญไม่แพ้กัน สำหรับโปรเจกต์ใหม่ แนะนำให้เลือกใช้ Argon2 ซึ่งชนะการแข่งขัน Password Hashing Competition เมื่อปี 2015 และยังคงเป็นตัวเลือกที่ดีและปลอดภัยที่สุดในปัจจุบัน โปรดหลีกเลี่ยงการใช้ SHA-256, MD5 หรือแม้กระทั่ง bcrypt สำหรับโปรเจกต์ใหม่
#![allow(unused)]
fn main() {
use argon2::{
Argon2,
PasswordHash,
PasswordHasher,
PasswordVerifier,
password_hash::SaltString,
};
use argon2::password_hash::rand_core::OsRng;
pub fn hash_password(password: &str) -> anyhow::Result<String> {
let salt = SaltString::generate(&mut OsRng);
// Use Argon2id, which is the variant recommended by OWASP.
// The default() configuration uses Argon2id with reasonable parameters,
// but for production you should tune memory cost and iterations based
// on your hardware and OWASP's current minimum recommendations.
let hasher = Argon2::default(); // Argon2id with default params
let hash = hasher
.hash_password(password.as_bytes(), &salt)
.map_err(|e| anyhow::anyhow!("failed to hash password: {}", e))?
.to_string();
Ok(hash)
}
pub fn verify_password(password: &str, hash: &str) -> anyhow::Result<bool> {
let parsed_hash = PasswordHash::new(hash)
.map_err(|e| anyhow::anyhow!("failed to parse password hash: {}", e))?;
Ok(Argon2::default()
.verify_password(password.as_bytes(), &parsed_hash)
.is_ok())
}
}
ข้อสำคัญที่ต้องพึงระลึกไว้เสมอคือ: การแฮชรหัสผ่านนั้นถูกออกแบบมาให้ทำงานช้าโดยเจตนา เพื่อทำให้การโจมตีแบบ brute-force ทำได้ยากจนไม่คุ้มค่า แต่ในบริบทของ async programming การทำงานที่กิน CPU หนักและใช้เวลานานแบบนี้หมายความว่าคุณควรโยนงานไปรันบน blocking thread pool เพื่อไม่ให้ไปบล็อกการทำงานของ async runtime:
#![allow(unused)]
fn main() {
let hash = tokio::task::spawn_blocking(move || hash_password(&password))
.await
.context("password hashing task failed")??;
}
การอนุญาตสิทธิ์ตามบทบาท
เมื่อเราทำให้การยืนยันตัวตนทำงานได้แล้ว การอนุญาตสิทธิ์คือขั้นถัดไปตามธรรมชาติ วิธีที่ง่ายที่สุดคือการเช็กบทบาทของผู้ใช้ในแฮนด์เลอร์:
#![allow(unused)]
fn main() {
async fn admin_only_endpoint(
user: AuthUser,
State(state): State<AppState>,
) -> AppResult<Json<AdminData>> {
if user.role != Role::Admin {
return Err(AppError::Forbidden);
}
// ... admin logic
}
}
วิธีนี้ใช้งานได้ดี แต่หากคุณพบว่าตัวเองต้องเขียนโค้ดตรวจสอบ role ซ้ำๆ ในหลาย handler เราสามารถปรับปรุงให้ดีขึ้นได้ด้วยการสร้าง custom extractor ที่ฝังเงื่อนไข role เข้าไปในตัวเลย:
#![allow(unused)]
fn main() {
pub struct RequireAdmin(pub AuthUser);
impl<S> FromRequestParts<S> for RequireAdmin
where
AppState: FromRef<S>,
S: Send + Sync,
{
type Rejection = AppError;
async fn from_request_parts(
parts: &mut Parts,
state: &S,
) -> Result<Self, Self::Rejection> {
let user = AuthUser::from_request_parts(parts, state).await?;
if user.role != Role::Admin {
return Err(AppError::Forbidden);
}
Ok(Self(user))
}
}
// Usage: just include it in the handler signature
async fn admin_endpoint(RequireAdmin(user): RequireAdmin) -> AppResult<Json<AdminData>> {
// If we get here, the user is authenticated AND has the admin role
// ...
}
}
การยืนยันตัวตนผ่านมิดเดิลแวร์
ยังมีอีกวิธีหนึ่งในการจัดการเรื่องนี้: แทนที่จะใส่ extractor ไว้ในแต่ละ handler คุณสามารถใช้ middleware ยืนยันตัวตนครอบ route ทั้งกลุ่มได้เลย วิธีนี้สะดวกมากเมื่อคุณมีกลุ่ม route ขนาดใหญ่ที่ต้องการ auth เหมือนกันทั้งหมด และไม่อยากเขียน AuthUser ซ้ำๆ ใน signature ของทุก handler
#![allow(unused)]
fn main() {
let public_routes = Router::new()
.route("/health", get(health_check))
.route("/api/v1/auth/login", post(login))
.route("/api/v1/auth/register", post(register));
let protected_routes = Router::new()
.nest("/api/v1/users", user_routes())
.nest("/api/v1/posts", post_routes())
.route_layer(middleware::from_fn_with_state(
state.clone(),
auth_middleware,
));
let app = Router::new()
.merge(public_routes)
.merge(protected_routes)
.with_state(state);
}
แล้วควรเลือกใช้แนวทางไหนดี? จากประสบการณ์ของผม extractor มีความยืดหยุ่นสูงกว่า เพราะแต่ละ handler สามารถเลือกใช้งานได้อย่างอิสระและเข้าถึงข้อมูล AuthUser ได้โดยตรง ส่วน middleware จะสะดวกกว่าเมื่อกลุ่มของ route ทั้งหมดมีเงื่อนไขการยืนยันตัวตนเหมือนกันทุกประการ นอกจากนี้คุณยังสามารถผสานทั้งสองวิธีเข้าด้วยกันได้ โดยใช้ middleware เป็นด่านแรกในการคัดกรอง และใช้ extractor สำหรับการตรวจสอบเงื่อนไขที่ละเอียดขึ้นภายใน handler แต่ละตัว
เครตในระบบนิเวศ
ก่อนจะจบบทนี้ ควรทำความรู้จักเครื่องมือใน ecosystem เพิ่มเติมไว้ เพราะคุณไม่จำเป็นต้องเขียนโค้ดขึ้นมาเองทั้งหมด:
- axum-login ให้ระบบยืนยันตัวตนแบบ session พร้อมรองรับ backend storage หลากหลายรูปแบบ
- axum-gate รวมการตรวจสอบ JWT เข้ากับการตรวจสอบสิทธิ์ตามบทบาท (role-based authorization)
- axum-session จัดการ session ที่จัดเก็บไว้ในฐานข้อมูล
- jwt-authorizer รองรับการตรวจสอบ JWT พร้อมทั้ง OIDC discovery
- axum-csrf-sync-pattern อิมพลีเมนต์การป้องกัน CSRF สำหรับระบบยืนยันตัวตนแบบ session
สำหรับแอปพลิเคชันสไตล์ API ส่วนใหญ่ ผมคิดว่าแนวทาง custom extractor อย่าง AuthUser ที่เราสร้างขึ้นข้างต้นให้ความสมดุลที่ดีเยี่ยมระหว่างความเรียบง่ายและการควบคุม แต่เมื่อระบบต้องการฟีเจอร์ที่ซับซ้อนขึ้น เช่น session management, OAuth2 flows หรือการผสานเข้ากับ OIDC crate เหล่านี้จะช่วยประหยัดเวลาและลดภาระการพัฒนาไปได้มาก
การออกแบบ API
หากคุณเคยต้องเชื่อมต่อกับ API ที่แต่ละ endpoint ส่งข้อมูลกลับมาในรูปแบบที่แตกต่างกันคนละทิศคนละทาง คุณคงเข้าใจดีว่ามันน่าหงุดหงิดเพียงใด เพราะคุณต้องเสียเวลาไปกับการอ่านเอกสาร (หรือนั่งเดา) มากกว่าการลงมือพัฒนาฟีเจอร์จริงๆ เสียอีก แน่นอนว่าเราคงไม่อยากสร้างประสบการณ์แบบนั้นให้ใคร รวมถึงตัวเราเองในอนาคตด้วย ในบทนี้ เราจะมาดูข้อตกลงในการออกแบบ REST, แพตเทิร์นโครงสร้างของ response, กลยุทธ์การทำ pagination และแนวทางการทำ API documentation ที่จะช่วยให้ Axum API ของเรามีความสม่ำเสมอ คาดเดาได้ง่าย และน่าใช้งาน
ข้อตกลงของ REST
REST ไม่ใช่มาตรฐานที่มีข้อกำหนดตายตัวแบบเป็นทางการ แต่เป็นชุดแนวปฏิบัติหรือข้อตกลงร่วม (conventions) ที่ผู้ใช้งาน API ส่วนใหญ่คุ้นเคยและคาดหวังว่าจะได้เห็น มาดูข้อตกลงสำคัญที่สุดกัน:
ใช้คำนามพหูพจน์สำหรับ resource เช่น /api/v1/users ไม่ใช่ /api/v1/user โดยชื่อ resource ควรเป็นตัวแทนของ collection และข้อมูลแต่ละรายการภายใน collection นั้นจะถูกเข้าถึงผ่าน ID ของมัน
ใช้ HTTP methods สื่อความหมายของการกระทำ เช่น GET สำหรับดึงข้อมูล, POST สำหรับสร้าง resource ใหม่, PUT สำหรับแทนที่ข้อมูลทั้งชุด, PATCH สำหรับอัปเดตข้อมูลบางฟิลด์ และ DELETE สำหรับลบข้อมูล แม้หลักการนี้จะฟังดูตรงไปตรงมา แต่ผมยังเห็น API จำนวนไม่น้อยที่ใช้ POST กับทุกสิ่งทุกอย่าง
เลือกใช้ HTTP Status Code ให้ถูกต้องและเหมาะสม บอกตามตรงว่านี่คือหนึ่งในจุดที่ยกระดับความน่าใช้งานของ API ได้มากที่สุด: เมื่อไคลเอนต์สร้าง resource สำเร็จ ควรส่ง 201 Created กลับไป ไม่ใช่ 200 OK, เมื่อลบข้อมูลสำเร็จ ควรตอบกลับด้วย 204 No Content, เมื่อไคลเอนต์ส่งข้อมูลไม่ถูกต้อง ควรตอบด้วย 400 Bad Request พร้อมระบุรายละเอียดข้อผิดพลาด และเมื่อค้นหาข้อมูลไม่พบ ควรใช้ 404 Not Found
ตารางสรุป HTTP Status Codes ที่คุณจะได้ใช้งานบ่อยที่สุด:
| รหัส | ความหมาย | เมื่อใดควรใช้ |
|---|---|---|
| 200 | OK | อ่านหรืออัปเดตข้อมูลสำเร็จ |
| 201 | Created | สร้าง resource ใหม่สำเร็จ |
| 204 | No Content | ดำเนินการสำเร็จโดยไม่มีเนื้อหาใน response body (เช่น การลบข้อมูล) |
| 400 | Bad Request | ข้อมูล input ไม่ถูกต้อง หรือ validation ล้มเหลว |
| 401 | Unauthorized | ไม่ได้แนบข้อมูลยืนยันตัวตนมา หรือข้อมูลไม่ถูกต้อง |
| 403 | Forbidden | ยืนยันตัวตนผ่านแล้ว แต่ไม่มีสิทธิ์เข้าถึง resource นี้ |
| 404 | Not Found | ไม่พบ resource ที่ร้องขอ |
| 409 | Conflict | ขัดต่อกฎทางธุรกิจ (เช่น อีเมลซ้ำในระบบ) |
| 422 | Unprocessable Entity | รูปแบบข้อมูลถูกต้องตาม syntax แต่ผิดเงื่อนไขเชิงความหมาย (semantic) |
| 500 | Internal Server Error | เกิดข้อผิดพลาดที่ไม่คาดคิดขึ้นที่ฝั่งเซิร์ฟเวอร์ |
การกำหนดเวอร์ชัน API
หากคุณกำลังพัฒนา Public API หรือ Platform Service แนะนำให้วางแผนเรื่องการทำ versioning ไว้ตั้งแต่เริ่มต้น เพราะการมาเพิ่ม version ทีหลังมักจะนำไปสู่ breaking changes หรือไม่ก็ต้องใช้วิธีแก้ปัญหาแบบชั่วคราวที่ไม่น่าดู ในขณะที่ต้นทุนของการใส่ prefix /v1 ลงใน route ตั้งแต่วันแรกนั้นแทบจะเป็นศูนย์
แต่สำหรับ internal service ที่ deploy ไปพร้อมๆ กับระบบผู้เรียกใช้งาน การทำ path-based versioning อาจมีความจำเป็นน้อยกว่า จากประสบการณ์จริง การมีวินัยในการพัฒนา schema อย่างต่อเนื่อง (เช่น การเพิ่มฟิลด์ใหม่แบบ additive, การกำหนดระยะเวลา deprecation ที่ชัดเจน, การทำ contract testing) มักจะสำคัญกว่าการตั้ง version prefix เสียอีก ดังนั้นอย่าทำ versioning เพียงเพราะมีใครบอกให้ทำ แต่จงทำเมื่อผู้ใช้งานระบบของคุณต้องการการรับประกันความเสถียร (stability guarantees) ที่ไม่สามารถจัดการได้ด้วยการประสานงานภายในทีมเพียงอย่างเดียว
แนวทางที่ง่ายและนิยมใช้งานกันแพร่หลายที่สุดคือการกำหนดเวอร์ชันผ่าน URL path:
#![allow(unused)]
fn main() {
fn api_routes() -> Router<AppState> {
Router::new()
.nest("/api/v1", v1_routes())
}
fn v1_routes() -> Router<AppState> {
Router::new()
.nest("/users", user_routes())
.nest("/posts", post_routes())
}
}
และเมื่อถึงวันที่คุณจำเป็นต้องปล่อย API v2 สำหรับบาง endpoint คุณก็สามารถเปิดใช้งานควบคู่ไปกับ v1 ได้ทันทีโดยไม่กระทบต่อผู้ใช้งานเดิม:
#![allow(unused)]
fn main() {
fn api_routes() -> Router<AppState> {
Router::new()
.nest("/api/v1", v1_routes())
.nest("/api/v2", v2_routes())
}
}
ข้อควรระวังประการหนึ่งคือ: พยายามออกแบบ handler implementation ให้ decoupled ออกจาก version prefix เพื่อให้ route ของทั้ง v1 และ v2 สามารถแชร์ service logic เบื้องหลังร่วมกันได้ ในจุดที่พฤติกรรมการทำงานยังคงเหมือนเดิม
รูปทรงการตอบกลับที่สม่ำเสมอ
คุณอาจสงสัยว่าทำไมเราต้องครอบทุก response ด้วยชนิดข้อมูลมาตรฐาน เหตุผลง่ายๆ คือ: เมื่อทุก endpoint ส่งข้อมูลกลับมาในโครงสร้างที่คาดเดาได้ ฝั่งไคลเอนต์จะสามารถเขียนโค้ด parsing กลางชุดเดียวมาประมวลผลได้ทันที แทนที่จะต้องเขียนโค้ดดักเคสพิเศษแยกเป็นราย endpoint มาลองกำหนด wrapper type มาตรฐานกันสัก 2-3 ตัว:
#![allow(unused)]
fn main() {
#[derive(Serialize)]
pub struct ApiResponse<T: Serialize> {
pub data: T,
}
#[derive(Serialize)]
pub struct PaginatedResponse<T: Serialize> {
pub data: Vec<T>,
pub meta: PaginationMeta,
}
#[derive(Serialize)]
pub struct PaginationMeta {
pub page: u32,
pub per_page: u32,
pub total: u64,
pub total_pages: u32,
}
}
สำหรับ error response เราจะใช้รูปแบบเดียวกับที่อธิบายไว้ในบท การจัดการข้อผิดพลาด เพื่อให้ไคลเอนต์สามารถตรวจสอบฟิลด์ error เพื่อตัดสินได้เสมอว่าคำขอนั้นสำเร็จหรือไม่
การแบ่งหน้า
endpoint ใดก็ตามที่คืนค่าเป็นรายการ resource ควรจะต้องรองรับการทำ pagination เสมอ หากไม่มีระบบนี้ เพียงแค่เจอชุดข้อมูลขนาดใหญ่เพียงครั้งเดียว เซิร์ฟเวอร์ของคุณก็อาจเจอปัญหา timeout, out-of-memory error หรือทำให้ผู้ใช้งานไม่พอใจได้ทันที เชื่อผมเถอะว่าการใส่ระบบ pagination ไว้ตั้งแต่ตอนนี้ ย่อมง่ายกว่าการตามมาแก้ไขทีหลังเมื่อตาราง users ของคุณเติบโตไปถึงระดับหลายแสนแถว
การแบ่งหน้าแบบอิง Offset (Offset-based pagination) เป็นวิธีที่เรียบง่ายที่สุด และทำงานได้ดีเมื่อปริมาณข้อมูลยังไม่มหาศาลมากนัก และไม่มีการเพิ่มหรือลบ record ถี่ๆ ในระหว่างที่ผู้ใช้กำลังเปิดดูหน้าถัดไป:
#![allow(unused)]
fn main() {
#[derive(Debug, Deserialize)]
pub struct PaginationParams {
#[serde(default = "default_page")]
pub page: u32,
#[serde(default = "default_per_page")]
pub per_page: u32,
}
fn default_page() -> u32 { 1 }
fn default_per_page() -> u32 { 20 }
async fn list_users(
State(state): State<AppState>,
Query(params): Query<PaginationParams>,
) -> AppResult<Json<PaginatedResponse<UserResponse>>> {
let per_page = params.per_page.clamp(1, 100); // at least 1, at most 100
let offset = (params.page.saturating_sub(1)) * per_page;
let (users, total) = state.user_service
.list(offset, per_page)
.await?;
Ok(Json(PaginatedResponse {
data: users.into_iter().map(Into::into).collect(),
meta: PaginationMeta {
page: params.page,
per_page,
total,
total_pages: total.div_ceil(per_page as u64) as u32,
},
}))
}
}
การแบ่งหน้าแบบอิง Cursor (Cursor-based pagination) เหมาะสมกว่ามากสำหรับชุดข้อมูลขนาดใหญ่หรือข้อมูลที่มีการเปลี่ยนแปลงอยู่ตลอดเวลา โดยแทนที่จะใช้ offset ฝั่งไคลเอนต์จะส่ง cursor (โดยทั่วไปคือ ID หรือ timestamp ของข้อมูลตัวสุดท้ายที่เพิ่งได้รับ) แล้วเซิร์ฟเวอร์จะคืนข้อมูลหน้าถัดไปโดยเริ่มต่อจาก cursor นั้น วิธีนี้ช่วยขจัดปัญหา “record เลื่อนหรือกระโดดข้าม” ซึ่งมักเกิดกับ offset-based pagination เมื่อข้อมูลมีการเพิ่มหรือลบระหว่างการเปิดหน้า
หากคุณไม่อยากเขียนตรรกะ cursor ด้วยตัวเอง crate อย่าง paginator-axum มีระบบ cursor-based pagination สำเร็จรูปพร้อม metadata ฟิลด์ next_cursor และ prev_cursor มาให้ ซึ่งถือเป็นจุดเริ่มต้นที่ดีมาก
การกรองและการเรียงลำดับ
สำหรับ endpoint แบบรายการที่ต้องรองรับการกรองข้อมูล เราสามารถรับค่าตัวกรองผ่าน query parameters ได้อย่างตรงไปตรงมา:
#![allow(unused)]
fn main() {
#[derive(Debug, Deserialize)]
pub struct UserListParams {
#[serde(default = "default_page")]
pub page: u32,
#[serde(default = "default_per_page")]
pub per_page: u32,
pub role: Option<Role>,
pub search: Option<String>,
#[serde(default = "default_sort")]
pub sort_by: String,
#[serde(default = "default_sort_direction")]
pub sort_direction: SortDirection,
}
}
ข้อควรระวัง: ควรจำกัดและเลือกฟิลด์ที่อนุญาตให้เรียงลำดับ (sort) อย่างรอบคอบ และตรวจสอบให้แน่ใจว่าคอลัมน์เหล่านั้นมีการทำ index ในฐานข้อมูลแล้ว เพราะการเปิดให้ผู้ใช้สั่ง sort ตามคอลัมน์ที่ไม่มี index คือสูตรสำเร็จของ slow query ที่จะสร้างปัญหาใหญ่ให้คุณบน production อย่างแน่นอน
เอกสารประกอบ OpenAPI
เราทุกคนต่างเคยพบเจอปัญหาเอกสาร API ที่เขียนไว้อย่างถูกต้องสมบูรณ์แบบเมื่อหกเดือนก่อน แล้วค่อยๆ ล้าสมัยจนเชื่อถือไม่ได้อีกต่อไปนับจากนั้น สิ่งที่ผมพบว่าได้ผลดีกว่ามากคือการ generate เอกสารออกมาจากโค้ดโดยตรง ซึ่ง crate อย่าง utoipa ทำหน้าที่นี้ได้อย่างสมบูรณ์แบบ โดยจะสร้างสเปก OpenAPI จาก type ใน Rust และ annotation บน handler ของคุณโดยตรง และเนื่องจากเอกสารสร้างมาจากโค้ดจริง มันจึงไม่มีวันล้าสมัย
#![allow(unused)]
fn main() {
use utoipa::{OpenApi, ToSchema};
#[derive(Serialize, ToSchema)]
pub struct UserResponse {
pub id: Uuid,
pub name: String,
pub email: String,
pub created_at: DateTime<Utc>,
}
#[utoipa::path(
post,
path = "/api/v1/users",
request_body = CreateUserDto,
responses(
(status = 201, description = "User created successfully", body = UserResponse),
(status = 400, description = "Validation error", body = ErrorResponse),
(status = 409, description = "User with this email already exists", body = ErrorResponse),
),
tag = "users"
)]
async fn create_user(
State(state): State<AppState>,
ValidatedJson(payload): ValidatedJson<CreateUserDto>,
) -> AppResult<(StatusCode, Json<UserResponse>)> {
// ...
}
}
สำหรับการเปิดให้บริการ Swagger UI ควบคู่ไปกับ API เราสามารถเชื่อมต่อระบบได้ดังนี้:
#![allow(unused)]
fn main() {
use utoipa::OpenApi;
use utoipa_swagger_ui::SwaggerUi;
#[derive(OpenApi)]
#[openapi(
paths(create_user, get_user, list_users, update_user, delete_user),
components(schemas(UserResponse, CreateUserDto, UpdateUserDto, ErrorResponse)),
tags((name = "users", description = "User management endpoints"))
)]
struct ApiDoc;
let app = Router::new()
.merge(api_routes())
.merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", ApiDoc::openapi()))
.with_state(state);
}
เพียงเท่านี้ นักพัฒนาคนอื่นก็สามารถเปิดดูเอกสาร API ของเราผ่าน /swagger-ui และทดลองยิง request จากเบราว์เซอร์ได้โดยตรง สเปกทั้งหมดถูกสร้างขึ้นตั้งแต่ตอนคอมไพล์จาก data type และ handler จริง จึงรับประกันได้ว่าจะตรงกับโค้ดที่รันอยู่ 100% เสมอ ซึ่งเป็นคุณสมบัติที่ยอดเยี่ยมมาก
เอนด์พอยต์ health check
Production API ทุกตัวจำเป็นต้องมี health check endpoint เสมอ เพื่อให้ Load Balancer และ Container Orchestrator มีช่องทางตรวจสอบว่าเซอร์วิสของเรายังมีชีวิตอยู่และพร้อมรับ traffic หรือไม่ มาดูวิธีติดตั้งกัน:
#![allow(unused)]
fn main() {
/// Liveness probe: is the process running and able to handle requests?
async fn health_live() -> StatusCode {
StatusCode::OK
}
/// Readiness probe: is the application ready to serve traffic?
/// Checks that all dependencies (database, cache, etc.) are reachable.
async fn health_ready(State(state): State<AppState>) -> StatusCode {
match sqlx::query("SELECT 1").execute(&state.db).await {
Ok(_) => StatusCode::OK,
Err(_) => StatusCode::SERVICE_UNAVAILABLE,
}
}
}
เราจะติดตั้ง endpoint เหล่านี้ไว้นอก route API ที่มี versioning เพื่อให้ URL คงที่เสมอแม้ API หลักจะมีการปรับเปลี่ยนเวอร์ชันก็ตาม:
#![allow(unused)]
fn main() {
let app = Router::new()
.route("/health", get(health_live))
.route("/health/ready", get(health_ready))
.merge(api_routes()) // api_routes() already nests under /api/v1
.with_state(state);
}
Liveness probe ควรทำงานได้อย่างรวดเร็วและไม่มีเงื่อนไขซับซ้อน เพราะหน้าที่ของมันมีเพียงแค่บอก orchestrator ว่า “ใช่ process ยังทำงานอยู่” ในขณะที่ Readiness probe จะทำหน้าที่ตรวจเช็กความพร้อมของ dependencies ต่างๆ (เช่น database, cache) เพื่อให้ orchestrator มั่นใจว่า instance นี้พร้อมที่จะรับ traffic ได้อย่างปลอดภัย การสับสนระหว่างสองตัวนี้เป็นข้อผิดพลาดที่พบได้บ่อยมาก และมักส่งผลให้ container ที่ทำงานปกติดีถูก restart โดยไม่จำเป็น เพียงเพราะ database เกิดความล่าช้าชั่วคราว
การออกแบบ API ด้วยแนวทางเหล่านี้จะทำให้เราได้รากฐานที่มั่นคง: URL ที่เป็นมาตรฐาน, รูปแบบ response ที่คาดเดาได้, ระบบ pagination ที่รองรับการขยายตัว, เอกสาร API ที่ตรงกับโค้ดจริงเสมอ และ health check ที่คอยรายงานสถานะให้อินฟราสตรักเจอร์ทราบอย่างแม่นยำ ลำดับถัดไป เราจะมาดูวิธีจัดการกับข้อผิดพลาดที่ย่อมต้องเกิดขึ้นอย่างแน่นอนเมื่อระบบเหล่านี้ถูกนำไปรันบน production
การสังเกตการณ์ (Observability)
คุณอาจเคยเจอกับสถานการณ์ที่มีอะไรบางอย่างพังบน production แล้วคุณต้องมานั่งจ้องกำแพงของ log ที่แทบไม่ได้ช่วยอะไรเลย พยายามปะติดปะต่อว่าเกิดอะไรขึ้นกันแน่ ผมเองก็เคยผ่านจุดนั้นมาแล้ว นี่คือสิ่งที่ Observability จะเข้ามาช่วยป้องกัน เพราะมันคือแนวทางที่ทำให้เรารู้ว่าแอปพลิเคชันของเรากำลังทำอะไรอยู่จริงๆ เมื่อถูกรันอยู่ในโลกความเป็นจริง โดยไม่จำเป็นต้องพยายามจำลองปัญหานั้นขึ้นมาใหม่บนเครื่องของเรา
ecosystem ของ Rust ได้เลือกให้ crate tracing เป็นมาตรฐานหลักสำหรับการบันทึกข้อมูลแบบมีโครงสร้างพร้อมบริบท (structured, contextual logging) เมื่อคุณนำมันมาผสานเข้ากับ OpenTelemetry สำหรับการทำ distributed tracing และการเก็บ metrics คุณก็จะได้ observability stack ที่แข็งแกร่งและครอบคลุมเกือบทุกอย่างที่เราจำเป็นต้องใช้
การบันทึกข้อมูลแบบมีโครงสร้างด้วย tracing
หากคุณเคยใช้ log หรือ env_logger มาก่อน tracing อาจดูคุ้นเคยในแวบแรก แต่มันทำงานแตกต่างกันอย่างสิ้นเชิงภายใต้ฝากระโปรง: แทนที่จะปล่อยข้อความสตริงแบบแบนๆ ออกมา มันจะส่งเหตุการณ์แบบมีโครงสร้าง (structured events) พร้อม typed fields ออกมาแทน นั่นหมายความว่าเครื่องมือวิเคราะห์ log ของคุณจะสามารถกรอง รวมกลุ่ม และ query ตามฟิลด์เฉพาะเจาะจงได้จริงๆ แทนที่จะต้องมานั่งเขียน regex แกะข้อมูลออกจากสตริง นอกจากนี้ยังรองรับ Span ซึ่งใช้แทนช่วงเวลาของการทำงาน (เช่น ระยะเวลาของ HTTP request หรือ database query) และคอยเก็บ context ที่จะถูกแนบไปกับทุกๆ เหตุการณ์ที่เกิดขึ้นภายใน span นั้นโดยอัตโนมัติ
การตั้งค่าซับสไครเบอร์
Subscriber ของ tracing ทำหน้าที่ควบคุมว่าเหตุการณ์ต่างๆ จะถูกจัดรูปแบบอย่างไรและถูกส่งไปที่ปลายทางไหน ในระหว่างการพัฒนา เราย่อมต้องการ output ที่มนุษย์อ่านเข้าใจง่ายพร้อมสีสัน เพื่อให้เราอ่านสิ่งที่เกิดขึ้นใน terminal ได้สะดวก ส่วนใน production เราต้องการ output แบบ JSON ที่ระบบรวบรวม log สามารถ parse ประมวลผลต่อได้
#![allow(unused)]
fn main() {
use tracing_subscriber::{
fmt, layer::SubscriberExt, util::SubscriberInitExt, EnvFilter,
};
pub fn init_tracing(log_level: &str) {
let env_filter = EnvFilter::try_from_default_env()
.unwrap_or_else(|_| EnvFilter::new(log_level));
// Use runtime configuration rather than build profile to control
// log format. A release build in staging should still be readable,
// and a debug build against production data should still emit JSON.
let json_output = std::env::var("LOG_JSON")
.map(|v| v == "true" || v == "1")
.unwrap_or(false);
let fmt_layer = if json_output {
fmt::layer().json().boxed()
} else {
fmt::layer().pretty().boxed()
};
tracing_subscriber::registry()
.with(env_filter)
.with(fmt_layer)
.init();
}
}
EnvFilter ช่วยให้เราควบคุมระดับ log level ได้ตอนรันไทม์ผ่าน environment variable RUST_LOG คุณสามารถตั้งระดับที่ต่างกันแยกเป็นรายโมดูลได้ ซึ่งช่วยได้มากเวลาที่เราต้องการเพิ่มความละเอียดเฉพาะบางคอมโพเนนต์โดยไม่ต้องจมอยู่ใน log จากส่วนอื่นไปทั้งหมด:
RUST_LOG=info,my_app::infra=debug,sqlx=warn
การเทรซคำขอด้วย TraceLayer
TraceLayer จาก tower-http จะสร้าง span ให้กับแต่ละ HTTP request โดยอัตโนมัติ พร้อมทั้งบันทึกเมธอด, URI, status code และระยะเวลาที่ใช้ เมื่อเรานำมันมาจับคู่กับ request ID เราก็จะสามารถตามรอยคำขอหนึ่งคำขอผ่านรายการ log ทั้งหมดที่มันสร้างขึ้นได้ มาดูกันว่าหน้าตาเป็นแบบไหน:
#![allow(unused)]
fn main() {
use tower_http::trace::TraceLayer;
let trace_layer = TraceLayer::new_for_http()
.make_span_with(|request: &http::Request<_>| {
let request_id = request
.headers()
.get("x-request-id")
.and_then(|v| v.to_str().ok())
.unwrap_or("unknown");
// Prefer the matched route pattern (e.g., "/api/v1/users/{id}")
// over the raw URI (e.g., "/api/v1/users/550e8400-...").
// Raw URIs create high-cardinality span fields that can overwhelm
// metrics backends and make aggregation impossible.
let matched_path = request.extensions()
.get::<axum::extract::MatchedPath>()
.map(|p| p.as_str().to_string())
.unwrap_or_else(|| request.uri().path().to_string());
tracing::info_span!(
"http_request",
method = %request.method(),
path = %matched_path,
request_id = %request_id,
)
});
}
ทุก log event ที่เกิดขึ้นระหว่างการประมวลผลคำขอนั้นจะถูกแนบฟิลด์ method, path และ request_id ไปด้วยโดยอัตโนมัติ เพราะ span จะทำหน้าที่เป็น ambient context ครอบคลุมการทำงานทั้งหมดที่เกิดขึ้นภายใน นี่คือหนึ่งในรายละเอียดที่ดูเหมือนเล็กน้อยแต่สร้างความแตกต่างอย่างมหาศาล เพราะเมื่อแอปพลิเคชันต้องรองรับคำขอพร้อมกันหลายร้อยรายการ คุณจะยังคงค้นหา log ทุกบรรทัดที่เกี่ยวข้องกับคำขอเฉพาะเจาะจงนั้นได้ในทันที เพียงแค่กรองด้วย request ID
การใส่เครื่องมือวัดให้แฮนด์เลอร์และเซอร์วิส
เราสามารถใช้ attribute #[tracing::instrument] เพื่อสร้าง span ให้กับแต่ละฟังก์ชันโดยอัตโนมัติ ซึ่งผมพบว่ามีประโยชน์อย่างยิ่งเมื่อนำไปใช้กับ service method และ repository call เพราะช่วยให้เราเห็น timeline และภาพรวมการทำงานได้อย่างชัดเจนโดยไม่ต้องมานั่งเขียนโค้ดสร้าง span ด้วยตัวเองในทุกๆ ที่
#![allow(unused)]
fn main() {
#[tracing::instrument(
skip(state, payload),
)]
async fn create_user(
State(state): State<AppState>,
ValidatedJson(payload): ValidatedJson<CreateUserDto>,
) -> AppResult<(StatusCode, Json<UserResponse>)> {
tracing::info!("creating new user");
let user = state.user_service.register(payload).await?;
tracing::info!(user_id = %user.id().as_uuid(), "user created successfully");
Ok((StatusCode::CREATED, Json(user.into())))
}
}
คำสั่ง skip(state, payload) จะบอกให้ macro ไม่ต้องนำ state หรือ request payload เข้าไปรวมไว้ในฟิลด์ของ span และเมื่อ service ทำงานสำเร็จ เราจึงค่อยบันทึก user_id เป็น structured field สังเกตว่าเราเลือกใช้ user_id ที่เป็นค่ารหัสสุ่ม (opaque ID) แทนที่จะบันทึก user.email ลงใน span ซึ่งนี่คือความตั้งใจในการออกแบบ จากประสบการณ์จริง การเลือกใช้ identifier ที่มีความเสี่ยงต่ำต่อข้อมูลส่วนบุคคล (เช่น user ID, tenant ID, request ID) ย่อมปลอดภัยกว่าการใส่ข้อมูลระบุตัวตนบุคคล (PII เช่น email หรือชื่อจริง) ลงใน trace output โดยตรง หากคุณจำเป็นต้องเชื่อมโยง trace เข้ากับ email เพื่อการ debug คุณก็สามารถนำ user ID ไปค้นหาต่อในฐานข้อมูลได้ คุณคงไม่อยากให้ log ทุกบรรทัดในระบบจัดเก็บ log กลายเป็นแหล่งรวมข้อมูลส่วนบุคคลที่เสี่ยงต่อการละเมิดความเป็นส่วนตัว
แนวปฏิบัติที่ดีที่สุดในการบันทึกข้อมูล
ใช้ Structured Fields แทนการต่อสตริง แทนที่จะเขียน tracing::info!("Created user {}", user_id) ให้เปลี่ยนมาเขียน tracing::info!(user_id = %user_id, "user created") รูปแบบที่มีโครงสร้างเช่นนี้จะทำให้ระบบ log aggregation สามารถทำ index และ filter ตามฟิลด์ user_id ได้ทันที ซึ่งมีประโยชน์ในการค้นหามากกว่าการพยายามแกะข้อความสตริงธรรมดาหลายเท่า
เลือกระดับ Log Level ให้ถูกต้องและเหมาะสม แม้จะฟังดูเป็นเรื่องพื้นฐาน แต่ก็คุ้มค่าที่จะย้ำให้ชัดเจน: ใช้ error กับปัญหาที่บ่งชี้ถึงบั๊กหรือความล้มเหลวของระบบที่ต้องมีคนเข้ามาตรวจสอบแก้ไข, ใช้ warn กับเหตุการณ์ผิดปกติแต่ระบบยังจัดการได้เอง (เช่น request โดน rate limit หรือเกิด cache miss), ใช้ info กับเหตุการณ์ทางธุรกิจที่สำคัญ (เช่น สร้างผู้ใช้สำเร็จ, มีการสั่งซื้อสินค้า), และใช้ debug กับข้อมูลการทำงานเชิงลึกที่เป็นประโยชน์ในระหว่างการพัฒนาหรือไล่หาสาเหตุของปัญหา การแยกระดับให้ชัดเจนมีความสำคัญอย่างยิ่ง เพราะเมื่อเกิดเหตุการณ์ฉุกเฉินตอนตีสอง คุณย่อมต้องการให้ระบบ alert แจ้งเตือนเฉพาะเรื่องที่วิกฤตจริงๆ เท่านั้น
ห้ามบันทึกความลับ (Secrets) ลงใน Log โดยเด็ดขาด หากคุณใช้ crate secrecy ในการจัดการ config (ตามที่อธิบายไว้ในบท การตั้งค่า) implementation ของ Debug จะช่วยซ่อนค่า sensitive ให้โดยอัตโนมัติ แต่คุณยังต้องระมัดระวังเป็นพิเศษกับ request body, header และข้อมูลอื่นๆ ที่อาจมี token, รหัสผ่าน หรือข้อมูลส่วนบุคคลแนบมาด้วย
OpenTelemetry
เมื่อแอปพลิเคชันเติบโตขึ้นจนกลายเป็น Distributed System ที่คำขอหนึ่งรายการอาจต้องเดินทางผ่านหลายไมโครเซอร์วิส เราจึงจำเป็นต้องมีวิธีติดตามเส้นทางของคำขอนั้นข้ามขอบเขตของเซอร์วิสต่างๆ ซึ่งนี่คือบทบาทของ OpenTelemetry ที่เข้ามามอบมาตรฐานกลางในการทำ context propagation และเก็บรวบรวมข้อมูล telemetry
เครตหลักๆ คือ:
- opentelemetry และ opentelemetry_sdk สำหรับคอร์ API และ SDK
- opentelemetry-otlp สำหรับส่งออกเทรซไปยังแบ็กเอนด์ที่รองรับ OTLP (Jaeger, Tempo, Datadog ฯลฯ)
- tracing-opentelemetry สำหรับเชื่อมสแปนของเครต
tracingเข้ากับสแปนของ OpenTelemetry - axum-tracing-opentelemetry สำหรับการแพร่กระจายบริบทเทรซอัตโนมัติใน Axum
ด้วยสแตกนี้ ทุกคำขอจะได้รับเทรซ ID ที่ติดตามมันข้ามพรมแดนระหว่างเซอร์วิส เมื่อผู้ใช้รายงานปัญหา เราสามารถค้นเทรซด้วย ID แล้วเห็นภาพทั้งหมด: มีเซอร์วิสใดเกี่ยวข้องบ้าง แต่ละขั้นตอนใช้เวลานานเท่าไร และมีอะไรผิดพลาดตรงไหน
เมตริก
เมตริกให้เลนส์ที่ต่างจากล็อกและเทรซ ในขณะที่รายการล็อกบอกเราเกี่ยวกับคำขอหนึ่งคำขอที่เฉพาะเจาะจง เมตริกให้ข้อมูลอนุกรมเวลาแบบรวมว่าแอปพลิเคชันของเราทำงานโดยรวมอย่างไร เมตริกตอบคำถามเช่น: ความหน่วงที่เปอร์เซ็นไทล์ที่ 99 เริ่มไต่ขึ้นเรื่อยๆ หรือเปล่า? อัตราข้อผิดพลาดเพิ่มเป็นสองเท่าในห้านาทีที่ผ่านมาหรือไม่? พูลการเชื่อมต่อฐานข้อมูลกำลังรับภาระหนักเกินไปหรือเปล่า?
- axum-otel-metrics ให้เมตริกแบบ OpenTelemetry พร้อมการส่งออกไปยัง Prometheus
- axum-prometheus ให้เมตริก HTTP ที่เข้ากันได้กับนิเวศของ metrics.rs
การตั้งค่าทั่วไปจะเปิดเผยเอนด์พอยต์ /metrics ให้ Prometheus เข้าไปเก็บข้อมูลเป็นช่วงเวลาปกติ จากประสบการณ์ของผม เมตริกที่มีประโยชน์ที่สุดสำหรับเว็บแอปพลิเคชันคือจำนวนคำขอ (แยกตามเมธอด เส้นทาง และรหัสสถานะ) ฮิสโทแกรมของระยะเวลาคำขอ และอัตราข้อผิดพลาด คุณอาจสงสัยว่าจำเป็นต้องมีทั้งสามอย่างตั้งแต่วันแรกหรือไม่ พูดตรงๆ ว่าแค่ระยะเวลาคำขอและอัตราข้อผิดพลาดก็จับปัญหาส่วนใหญ่ได้ก่อนที่ผู้ใช้จะสังเกตเห็นแล้ว
การรวมทุกอย่างเข้าด้วยกัน
การตั้งค่าการสังเกตการณ์ที่พร้อมใช้ใน production ผสานทั้งสามอย่างนี้เข้าด้วยกัน ล็อกแบบมีโครงสร้างให้ข้อมูลละเอียดเกี่ยวกับเหตุการณ์แต่ละเหตุการณ์ เทรซให้เราเดินตามคำขอผ่านหลายเซอร์วิสเพื่อหาคอขวด และเมตริกให้ภาพรวมของสุขภาพระบบและแนวโน้มประสิทธิภาพ
การตั้งค่าทั้งหมดนี้อาจดูเหมือนงานใหญ่ที่ต้องทำล่วงหน้า และมันก็เป็นงานพอสมควรจริงๆ แต่มันคืนทุนให้ตัวเองตั้งแต่วันแรกที่คุณต้องดีบักปัญหาใน production แทนที่จะเดาว่าเกิดอะไรขึ้นแล้วดีพลอยต์แพตช์ลองผิดลองถูก คุณดูที่ข้อมูลแล้วเห็นสิ่งที่เกิดขึ้นจริงๆ ซึ่งเป็นจุดที่คุณอยากอยู่มากกว่า
เมื่อเรามีรากฐานด้านการสังเกตการณ์ที่มั่นคงแล้ว ลำดับถัดไปมาดูกันว่าเราจะจัดการข้อผิดพลาดและสื่อสารกับผู้ใช้งาน API ของเราอย่างชัดเจนได้อย่างไร
ความปลอดภัย
หากมีสิ่งหนึ่งที่ผมอยากให้คุณได้รับไปจากหนังสือเล่มนี้มากที่สุด นั่นคือ: ความปลอดภัยไม่ใช่ฟีเจอร์ที่คุณจะมาติดตั้งเพิ่มเติมทีหลังในตอนท้าย แต่เป็นชุดแนวทางปฏิบัติที่ต้องแทรกซึมอยู่ในทุกๆ เลเยอร์ของแอปพลิเคชัน ตั้งแต่วิธีการจัดการอินพุตจากผู้ใช้ ไปจนถึงขั้นตอนการตั้งค่าการ deploy เราได้แตะเรื่องความปลอดภัยกันมาเรื่อยๆ ในบทก่อนหน้า ดังนั้นบทนี้จึงรวบรวมประเด็นทั้งหมดมาไว้เป็นเอกสารอ้างอิงฉบับสมบูรณ์ในที่เดียว พร้อมทั้งเสริมหัวข้อสำคัญอื่นๆ ที่ยังไม่ได้กล่าวถึงก่อนหน้านี้ด้วย
การจัดการอินพุต
แนวป้องกันด่านแรกของเรานั้นเรียบง่ายมาก: จงถือว่าอินพุตภายนอกทั้งหมดเป็นสิ่งที่ไม่น่าไว้วางใจ คุณอาจคิดว่านี่เป็นเรื่องที่รู้กันดีอยู่แล้ว แต่ในความเป็นจริงเรามักจะเผลอการ์ดตกได้ง่ายมาก โดยเฉพาะเมื่อเราเป็นผู้ควบคุมโค้ดทั้งฝั่งไคลเอนต์และเซิร์ฟเวอร์เอง อย่าทำเช่นนั้นเด็ดขาด
ใช้ Parameterized Queries เท่านั้น ห้ามสร้างคำสั่ง SQL ด้วยการต่อสตริงโดยเด็ดขาด ทุกๆ query ในฐานข้อมูลจะต้องใช้ parameter placeholders ($1, $2, ฯลฯ) ร่วมกับการ bind ค่าเสมอ ซึ่ง macro query! และ query_as! ของ SQLx จะบังคับเรื่องนี้ตั้งแต่ตอนคอมไพล์ และบอกตามตรงว่านี่คือหนึ่งในเหตุผลสำคัญที่สุดที่ควรเลือกใช้ SQLx
ทำ Validation ที่ขอบเขตของ API เสมอ เราได้อธิบายเรื่องนี้อย่างละเอียดในบท การตรวจสอบความถูกต้องของคำขอ ไปแล้ว หัวใจสำคัญคือการปฏิเสธอินพุตที่ผิดรูปแบบทิ้งไปทันทีก่อนที่มันจะหลุดเข้าไปถึง business logic: ตรวจสอบความยาวของสตริง, รูปแบบของข้อมูล และเช็กฟิลด์ที่จำเป็นต้องมีตั้งแต่ตรงขอบเขตของ API
แปลงข้อมูลดิบให้เป็น Domain Type (Parse, don’t validate) หากคุณได้อ่านบท การสร้างแบบจำลองโดเมน แล้ว คุณคงคุ้นเคยกับหลักการนี้เป็นอย่างดี: จงแปลงอินพุตดิบให้กลายเป็น domain type โดยเร็วที่สุดเท่าที่จะทำได้ เช่น เมื่อสร้าง UserName ผ่านฟังก์ชัน parse สำเร็จแล้ว ค่าข้างในจะไม่มีวันมีอักขระต้องห้ามได้อย่างแน่นอนตามโครงสร้างของ type system ให้ระบบ type ทำงานหนักแทนเรา
จำกัดขนาดของ Request Body ใช้ RequestBodyLimitLayer เพื่อปฏิเสธ payload ที่มีขนาดใหญ่เกินไปตั้งแต่เนิ่นๆ ก่อนที่มันจะเข้ามาสูบหน่วยความจำจนหมด โดยขนาดจำกัดที่ 1 MB ถือว่าเหมาะสมอย่างยิ่งสำหรับ JSON API ส่วนใหญ่
การยืนยันตัวตนและความลับ
แฮชรหัสผ่านด้วย Argon2 เสมอ เราได้พูดถึงเรื่องนี้ในบท การยืนยันตัวตนและการอนุญาตสิทธิ์ แล้ว แต่มันคุ้มค่าที่จะเน้นย้ำอีกครั้ง: Argon2 คือมาตรฐานที่ดีที่สุดในปัจจุบันสำหรับการ hash รหัสผ่าน และต้องสร้าง salt แบบสุ่มใหม่สำหรับรหัสผ่านทุกๆ รายการเสมอ
ใช้ JWT Secret ที่มีความยาวและเป็นค่าสุ่มจริง JWT secret ของคุณควรเป็นสตริงสุ่มที่มีความยาวอย่างน้อย 48 ตัวอักษร เพราะ secret ที่สั้นเกินไปจะเสี่ยงต่อการถูกโจมตีแบบ brute-force และคุณคงไม่อยากมารู้ตัวเมื่อสายเกินแก้ ควรเก็บ secret ไว้ใน SecretString จาก crate secrecy และตรวจสอบความยาวของมันตั้งแต่ตอนเริ่มต้นระบบ (startup)
กำหนดอายุของ Token ให้เหมาะสม การกำหนดให้ Access Token มีอายุสั้น (เช่น 15 นาทีถึงไม่กี่ชั่วโมง) จะช่วยจำกัดขอบเขตความเสียหายหาก token นั้นหลุดรอดไป หากระบบของคุณต้องการ session ที่ยาวนานขึ้น ให้ใช้กลไก Refresh Token ควบคู่กัน โดยจัดเก็บ refresh token ไว้อย่างปลอดภัยและสามารถสั่งเพิกถอนสิทธิ์ได้
ห้ามเก็บ Token ใน localStorage เด็ดขาด สำหรับไคลเอนต์บนเว็บเบราว์เซอร์ ให้ใช้ cookie ที่ตั้งค่า HttpOnly, Secure และ SameSite=Strict แทน เพราะ cookie เหล่านี้ JavaScript จะไม่สามารถเข้าถึงได้ ช่วยป้องกันการขโมย token ผ่านช่องโหว่ XSS ได้โดยตรง
CORS
คุณอาจเคยพบเจอกับ CORS error มาบ้างในระหว่างการพัฒนา: Cross-Origin Resource Sharing เป็นกลไกความปลอดภัยของเบราว์เซอร์ที่ใช้ควบคุมว่ามี origin ใดบ้างที่ได้รับอนุญาตให้ส่งคำขอมายัง API ของเรา การตั้งค่านโยบาย CORS ผิดพลาดเป็นหนึ่งในปัญหาด้านความปลอดภัยที่พบบ่อยที่สุดในเว็บ API ส่วนหนึ่งเป็นเพราะทางแก้แบบด่วนๆ ในระหว่างพัฒนา (“เปิดอนุญาตให้หมดไปก่อน”) มักจะเผลอหลุดรอดขึ้นไปอยู่บน production อยู่เป็นประจำ
#![allow(unused)]
fn main() {
// Production: explicit allow list
CorsLayer::new()
.allow_origin([
"https://myapp.com".parse().unwrap(),
])
.allow_methods([Method::GET, Method::POST, Method::PUT, Method::DELETE])
.allow_headers([header::CONTENT_TYPE, header::AUTHORIZATION])
.allow_credentials(true)
}
ในระหว่างการพัฒนา การใช้ CorsLayer::permissive() นั้นสะดวกสบายก็จริง แต่ต้องตรวจสอบให้แน่ใจว่าจะไม่มีวันหลุดไปถึง production เด็ดขาด เพราะนโยบาย CORS แบบเปิดกว้างทั้งหมดจะยอมให้ origin ใดๆ ก็ตามสามารถยิงคำขอมาที่ API ของคุณได้ ไม่ว่าคำขอนั้นจะแนบ credentials (cookie หรือ Authorization header) มาด้วยหรือไม่ก็ตาม (ขึ้นอยู่กับโหมด credentials ของเบราว์เซอร์และการตั้งค่า allow_credentials ของคุณ) แต่ถึงแม้จะไม่มี credentials นโยบายที่เปิดกว้างเกินไปก็ทำให้ API surface ของคุณถูกสำรวจและโจมตีข้าม origin ได้ ยิ่งไปกว่านั้น CorsLayer::very_permissive() ยังอันตรายกว่ามากเพราะมันเปิดให้ส่ง credentials ได้ด้วย ดังนั้นจงจำกัด origin ให้ชัดเจนบน production เสมอ
การป้องกัน CSRF
หาก API ของคุณใช้ cookie ในการยืนยันตัวตน (ต่างจากการใช้ Bearer token) คุณจำเป็นต้องป้องกันการโจมตีแบบ Cross-Site Request Forgery (CSRF) ด้วย crate axum-csrf-sync-pattern ได้อิมพลีเมนต์แพตเทิร์น Synchronizer Token Pattern ตามคำแนะนำของ OWASP ซึ่งมีหลักการทำงานดังนี้:
- เซิร์ฟเวอร์จะสร้าง CSRF token แบบสุ่มขึ้นมา แล้วส่งกลับไปให้ไคลเอนต์ใน custom response header
- ไคลเอนต์จะต้องแนบ token นั้นกลับมาใน custom request header สำหรับทุกๆ request ที่มีการเปลี่ยนแปลงสถานะ (state-changing requests)
- เซิร์ฟเวอร์จะตรวจสอบว่า token ใน request header ตรงกับ token ที่เซิร์ฟเวอร์เป็นผู้ออกให้หรือไม่
ทำไมวิธีนี้ถึงได้ผล? เพราะเว็บไซต์ไม่ประสงค์ดีสามารถสั่งให้เบราว์เซอร์ส่ง cookie แนบไปโดยอัตโนมัติได้ก็จริง แต่มันจะไม่สามารถอ่านหรือกำหนด custom header ในการส่งคำขอข้าม origin ได้ (ตราบใดที่นโยบาย CORS ของคุณไม่ได้เปิดช่องให้ทำเช่นนั้น)
การจำกัดอัตราการเรียก
Rate Limiting มักเป็นสิ่งที่เราคิดว่ายังไม่จำเป็น จนกระทั่งวันหนึ่งมีคนเริ่มยิงถล่ม endpoint ล็อกอินของเรา มันช่วยป้องกันการโจมตีแบบ brute-force, credential stuffing และความพยายามทำ Denial of Service (DoS) โดย crate tower-governor มี Tower middleware ที่ช่วยจำกัดคำขอโดยอิงตาม IP address ของไคลเอนต์:
#![allow(unused)]
fn main() {
use tower_governor::{GovernorConfigBuilder, GovernorLayer};
let governor_config = GovernorConfigBuilder::default()
.per_second(2)
.burst_size(10)
.finish()
.unwrap();
let app = Router::new()
.merge(api_routes())
.layer(GovernorLayer { config: governor_config })
.with_state(state);
}
สำหรับ authentication endpoints (เช่น ล็อกอิน หรือรีเซ็ตรหัสผ่าน) ผมแนะนำให้ตั้งค่าขีดจำกัดที่เข้มงวดเป็นพิเศษ เช่น กำหนดไว้ที่ 5 ครั้งต่อนาทีต่อหนึ่ง IP ซึ่งจะช่วยตัดโอกาสการทำ credential stuffing ได้อย่างมีประสิทธิภาพ
ข้อสำคัญที่ต้องพึงระลึกไว้คือ: หากคุณรันแอปพลิเคชันหลาย instance บน production การทำ rate limiting ตาม IP ในระดับแอปพลิเคชันเพียงอย่างเดียวย่อมไม่เพียงพอ เพราะแต่ละ instance จะนับตัวเลขแยกจากกัน ในกรณีนี้คุณควรเลือกใช้ rate limiter ที่มี Redis อยู่เบื้องหลัง หรือย้ายการจัดการ rate limit ไปไว้ที่ระดับ Load Balancer หรือ API Gateway แทน
ส่วนหัวด้านความปลอดภัย
HTTP Security Headers เป็นคำสั่งที่บอกให้เบราว์เซอร์เปิดใช้กลไกการป้องกันความปลอดภัยต่างๆ ส่วนหัวที่คุณจำเป็นต้องใช้นั้นขึ้นอยู่กับว่าแอปพลิเคชันของคุณทำหน้าที่เสิร์ฟ HTML หรือเป็นเพียง JSON API: สำหรับเว็บที่เสิร์ฟหน้า HTML ส่วนหัวอย่าง Content-Security-Policy และ X-Frame-Options ถือว่าขาดไม่ได้ ส่วนสำหรับ API ที่คืนค่าเป็น JSON ล้วน บางส่วนหัวอาจมีความจำเป็นน้อยลงเพราะไม่มีบริบทการ render ของเบราว์เซอร์ให้ต้องปกป้องโดยตรง แต่ถึงอย่างนั้นผมก็ยังแนะนำให้ตั้งค่าส่วนหัวเหล่านี้ไว้ในเชิงป้องกัน (defensive) เสมอ เพราะไม่มีผลเสียอะไรและช่วยป้องกันปัญหาในอนาคตได้ดีกว่า
มาดูตัวอย่างการนำไปใช้เป็น middleware layer กัน:
#![allow(unused)]
fn main() {
use axum::http::{HeaderName, HeaderValue};
async fn security_headers(req: Request, next: Next) -> Response {
let mut response = next.run(req).await;
let headers = response.headers_mut();
// Prevent MIME-type sniffing
headers.insert(
HeaderName::from_static("x-content-type-options"),
HeaderValue::from_static("nosniff"),
);
// Control framing (prefer CSP frame-ancestors for modern browsers,
// but X-Frame-Options is still useful for older ones)
headers.insert(
HeaderName::from_static("x-frame-options"),
HeaderValue::from_static("DENY"),
);
// Content Security Policy: the primary defense against XSS.
// Adjust the directives to match your application's needs.
headers.insert(
HeaderName::from_static("content-security-policy"),
HeaderValue::from_static("default-src 'none'; frame-ancestors 'none'"),
);
// Enforce HTTPS connections
headers.insert(
HeaderName::from_static("strict-transport-security"),
HeaderValue::from_static("max-age=63072000; includeSubDomains"),
);
headers.insert(
HeaderName::from_static("referrer-policy"),
HeaderValue::from_static("strict-origin-when-cross-origin"),
);
response
}
}
มาดูกันว่ามีอะไรอยู่ในนี้บ้าง และมีส่วนหัวตัวไหนที่ผมจงใจไม่ใส่:
Content-Security-Policy (CSP) คือแนวป้องกันหลักในยุคใหม่ต่อช่องโหว่ Cross-Site Scripting (XSS) นโยบาย CSP ที่รัดกุมมีประสิทธิภาพเหนือกว่า header รุ่นเก่าอย่าง X-XSS-Protection ซึ่งทั้ง OWASP และ MDN ต่างประกาศเลิกใช้ (deprecated) ไปแล้ว โปรดอย่าตั้งค่า X-XSS-Protection เพราะในบาง edge case มันกลับสร้างช่องโหว่ใหม่ขึ้นมาเสียเอง ให้ใช้ CSP แทนเสมอ
Strict-Transport-Security (HSTS) ทำหน้าที่สั่งให้เบราว์เซอร์เชื่อมต่อผ่าน HTTPS เท่านั้น ช่วยป้องกันการโจมตีแบบ Protocol Downgrade และเป็นสิ่งที่ต้องมีเสมอสำหรับการ deploy บน production ที่อยู่หลัง TLS
X-Frame-Options ช่วยป้องกันการโจมตีแบบ Clickjacking สำหรับเบราว์เซอร์รุ่นเก่า ส่วนในเบราว์เซอร์สมัยใหม่ directive frame-ancestors ใน CSP จะเป็นกลไกหลักที่นิยมใช้มากกว่า แต่ทั้งสองตัวนี้ก็สามารถตั้งค่าควบคู่กันได้โดยไม่มีปัญหา
ส่วนหัวความปลอดภัยเหล่านี้ไม่ได้มาทดแทนการเขียนโค้ดที่ปลอดภัย แต่ช่วยเสริมการป้องกันแบบหลายชั้น (Defense-in-depth) โดยการเปิดใช้กลไกป้องกันฝั่งเบราว์เซอร์ต่อรูปแบบการโจมตีทั่วไป เปรียบเสมือนตาข่ายนิรภัยอีกชั้นหนึ่ง
การตรวจสอบดีเพนเดนซี
Third-party dependencies สามารถนำช่องโหว่ด้านความปลอดภัยเข้ามาในระบบได้ และในโปรเจกต์ Rust คุณมักจะมี dependency มากกว่าที่คิดไว้เสมอ ดังนั้นจงรัน cargo audit เป็นประจำ (และที่สำคัญที่สุดคือควรใส่ไว้ใน CI pipeline) เพื่อตรวจหาช่องโหว่ที่มีรายงานไว้ใน dependency tree ของคุณ:
cargo install cargo-audit
cargo audit
คำสั่งนี้จะตรวจสอบไฟล์ Cargo.lock เทียบกับฐานข้อมูล RustSec Advisory Database และรายงานหากพบว่ามี dependency ตัวใดที่มีช่องโหว่ด้านความปลอดภัย จากประสบการณ์จริง การคอยอัปเดต dependency ให้ทันสมัยอยู่เสมอเป็นหนึ่งในแนวปฏิบัติด้านความปลอดภัยที่ง่ายที่สุดและให้ผลคุ้มค่าที่สุดที่คุณสามารถเริ่มต้นทำได้ทันที
เช็กลิสต์ความปลอดภัย
นี่คือสรุปเช็กลิสต์แนวปฏิบัติด้านความปลอดภัยที่เราได้กล่าวถึงตลอดทั้งเล่ม ผมแนะนำให้ตรวจเช็กตามรายการเหล่านี้ให้ครบถ้วนก่อนที่คุณจะ deploy ระบบขึ้น production:
- คำสั่ง SQL ทั้งหมดใช้ Parameterized Queries (ไม่มีการต่อสตริง)
- จำกัดขนาดของ Request Body ด้วย
RequestBodyLimitLayer - ตั้งค่า Request Timeout ด้วย
TimeoutLayer - มีการทำ Validation ข้อมูลที่ขอบเขตของ API เสมอ
- กำหนดให้ Domain Types บังคับใช้ Business Invariants ผ่านระบบ Type System
- รหัสผ่านทั้งหมดถูก Hash ด้วย Argon2
- JWT Secret มีความยาวอย่างน้อย 48 ตัวอักษรและเป็นค่าสุ่มจริง
- JWT Secret ถูกจัดเก็บใน
SecretStringและไม่มีการบันทึกลงใน Log เด็ดขาด - มีการกำหนดอายุ Token (Expiration Time) และบังคับใช้อย่างเคร่งครัด
- CORS ถูกจำกัดเฉพาะ Origin ที่กำหนดไว้อย่างชัดเจนบน Production
- เปิดใช้ระบบป้องกัน CSRF หากใช้การยืนยันตัวตนแบบ Cookie-based
- ใช้ Rate Limiting กับ Public Endpoints ทั้งหมด
- ใช้ Rate Limiting ที่เข้มงวดเป็นพิเศษกับ Authentication Endpoints
- ตั้งค่า Headers ด้านความปลอดภัยครบถ้วน: CSP, HSTS, X-Content-Type-Options และ Referrer-Policy
- ไม่ตั้งค่า X-XSS-Protection (ให้ใช้ CSP แทน)
- CORS ถูกควบคุมผ่านการตั้งค่าตอนรันไทม์ ไม่ใช่ขึ้นอยู่กับ Build Profile
- ไม่เปิดเผยรายละเอียดข้อผิดพลาดภายใน (Internal Errors) ใน Response ของ API
- การตรวจสอบ JWT ระบุ Algorithm, Issuer และ Audience ไว้อย่างชัดเจน
- ใช้ UUID เป็น Resource ID (ช่วยให้คาดเดายากขึ้น แต่ยังต้องมีการตรวจสอบสิทธิ์เป็นหลัก)
- รัน
cargo auditเป็นประจำหรือใส่ไว้ในระบบ CI - รัน
cargo sqlx prepare --checkในระบบ CI - ไฟล์
.envถูกใส่ไว้ใน.gitignoreและไม่ถูก Commit ขึ้น Git เด็ดขาด
การทดสอบ
ถ้าคุณเคย deploy เว็บเซอร์วิสขึ้น production แล้วต้องใช้เวลาตลอดสัปดาห์ถัดมานั่งจ้อง log ด้วยความกังวลใจ คุณคงเข้าใจความรู้สึกนั้นเป็นอย่างดี การทดสอบ (Testing) คือสิ่งที่ช่วยให้เรานอนหลับได้อย่างสบายใจในตอนกลางคืน ทว่าการทดสอบเว็บแอปพลิเคชันไม่ได้มีเพียงมิติเดียว เราต้องการทั้ง unit test เพื่อตรวจสอบ business logic แบบแยกเดี่ยว (in isolation), integration test ที่วิ่งทดสอบตลอดทั้ง pipeline ตั้งแต่ request ไปจนถึง response รวมถึงกลยุทธ์ที่มั่นคงในการจัดการฐานข้อมูลสำหรับทดสอบและ dependency ภายนอก ในบทนี้ ผมจะพาคุณสำรวจแพตเทิร์นและเครื่องมือต่างๆ ที่ทำให้การทดสอบแอปพลิเคชัน Axum ใช้งานได้จริงในชีวิตประจำวัน และเอาเข้าจริงแล้ว มันค่อนข้างสนุกทีเดียว
พีระมิดการทดสอบ
คุณคงเคยได้ยินเกี่ยวกับพีระมิดการทดสอบ (Testing Pyramid) มาก่อน แม้จะเป็นแนวคิดเรียบง่าย แต่มันกลับใช้งานได้ดีเยี่ยมในทางปฏิบัติ ที่ฐานล่างสุด เราจะเขียน unit test จำนวนมากที่ทำงานได้รวดเร็ว เพื่อตรวจสอบการทำงานของแต่ละฟังก์ชันและ domain logic ถัดขึ้นมาตรงกลาง เรามี integration test ที่ครอบคลุมทั้ง HTTP handler pipeline ตั้งแต่มิดเดิลแวร์, extractor, serialization ไปจนถึงการเข้าถึงฐานข้อมูล และที่ยอดบนสุด เราจะสงวนไว้สำหรับ end-to-end test ในจำนวนไม่มาก เพื่อตรวจสอบ user flow ที่สำคัญกับเซิร์ฟเวอร์ที่รันอยู่จริงๆ
จากประสบการณ์ของผม ความพยายามในการทดสอบส่วนใหญ่ควรทุ่มเทให้กับสองชั้นล่าง Unit test ช่วยดักจับบั๊กเชิงตรรกะได้อย่างรวดเร็วและใช้ต้นทุนต่ำ ส่วน integration test จะช่วยยืนยันว่าเลเยอร์ทั้งหมดถูกร้อยเรียงเข้าด้วยกันอย่างถูกต้องจริงๆ สำหรับ end-to-end test แม้จะมีประโยชน์อย่างยิ่งกับ critical path แต่การทดสอบระดับนี้ทำงานช้าและเปราะบางกว่ามาก ผมจึงแนะนำให้ใช้เท่าที่จำเป็นจริงๆ
การทดสอบหน่วยตรรกะโดเมน
นี่คือจุดที่การลงทุนสร้าง clean architecture ในบทก่อนหน้าเริ่มออกดอกออกผลอย่างแท้จริง เพราะเลเยอร์โดเมนไม่มี dependency ผูกติดกับ Axum, SQLx หรือเฟรมเวิร์กใดๆ เลย การทดสอบจึงเรียบง่ายอย่างน่าประทับใจ เราแค่สร้าง domain type เรียกใช้ service method แล้ว assert ตรวจสอบผลลัพธ์ ไม่ต้องมี HTTP server ไม่ต้องต่อฐานข้อมูล และไม่มีอะไรซับซ้อนยุ่งยาก
หากเซอร์วิสของคุณใช้งาน repository ผ่าน trait (ตามที่เราออกแบบไว้ในบท แพตเทิร์นสถาปัตยกรรม) คุณก็สามารถส่ง in-memory implementation เข้าไปสำหรับการทดสอบได้อย่างง่ายดาย:
#![allow(unused)]
fn main() {
#[derive(Clone)]
struct InMemoryUserRepo {
users: Arc<Mutex<Vec<User>>>,
}
impl InMemoryUserRepo {
fn new() -> Self {
Self {
users: Arc::new(Mutex::new(Vec::new())),
}
}
}
impl UserRepository for InMemoryUserRepo {
async fn create(&self, req: &CreateUserRequest) -> Result<User, CreateUserError> {
let mut users = self.users.lock().await;
// Check for duplicates
if users.iter().any(|u| u.email() == &req.email) {
return Err(CreateUserError::Duplicate { email: req.email.clone() });
}
let user = User::hydrate(
UserId::new(),
req.name.clone(),
req.email.clone(),
Utc::now(),
Utc::now(),
);
users.push(user.clone());
Ok(user)
}
async fn find_by_id(&self, id: UserId) -> anyhow::Result<Option<User>> {
let users = self.users.lock().await;
Ok(users.iter().find(|u| u.id() == &id).cloned())
}
// ... other methods
}
#[tokio::test]
async fn registering_a_user_returns_the_user() {
let repo = InMemoryUserRepo::new();
let service = UserService::new(repo);
let name = UserName::parse("Alice").unwrap();
let email = Email::parse("alice@example.com").unwrap();
let user = service.register(name, email, "password123").await.unwrap();
assert_eq!(user.name().as_str(), "Alice");
assert_eq!(user.email().as_str(), "alice@example.com");
}
#[tokio::test]
async fn registering_duplicate_email_fails() {
let repo = InMemoryUserRepo::new();
let service = UserService::new(repo);
let name = UserName::parse("Alice").unwrap();
let email = Email::parse("alice@example.com").unwrap();
service.register(name.clone(), email.clone(), "password123").await.unwrap();
let result = service.register(name, email, "password456").await;
assert!(matches!(result, Err(CreateUserError::Duplicate { .. })));
}
}
การทดสอบเหล่านี้ทำงานเสร็จสิ้นภายในเสี้ยววินาที (ระดับมิลลิวินาที) เพราะไม่มีการแตะต้องเน็ตเวิร์กหรือระบบไฟล์เลย เป็นการยืนยันว่า business logic ของคุณทำงานถูกต้อง โดยไม่ขึ้นกับวิธีการเรียกใช้หรือตำแหน่งที่จัดเก็บข้อมูล ความเร็วนั้นสำคัญมาก เพราะเมื่อ test suite ทำงานได้รวดเร็ว คุณและทีมก็พร้อมที่จะรันมันบ่อยๆ จริงๆ
หากการเขียน in-memory implementation เหล่านี้ดูมี boilerplate มากเกินไป (ซึ่งก็เป็นไปได้) crate อย่าง mockall สามารถสร้าง mock implementation สำหรับ repository trait ของคุณได้โดยอัตโนมัติ โดยส่วนตัวผมมักชอบเขียน fake ขึ้นมาเองสำหรับการทดสอบ core domain เพราะไล่เรียงทำความเข้าใจได้ง่ายกว่า แต่ mockall ก็เป็นตัวเลือกที่ยอดเยี่ยมเช่นกัน โดยเฉพาะอย่างยิ่งเมื่อขนาดและจำนวนเมธอดของ trait เริ่มขยายใหญ่ขึ้น
การทดสอบการผสานด้วย oneshot
นี่คือจุดเด่นที่น่าประทับใจอย่างยิ่ง การที่ Axum ผสานการทำงานร่วมกับ Tower อย่างแนบแน่น ทำให้เราสามารถทดสอบ HTTP pipeline ทั้งหมดได้โดยไม่ต้องสตาร์ตเซิร์ฟเวอร์จริงๆ เลย เมธอด tower::ServiceExt::oneshot จะส่ง request หนึ่งคำขอผ่านเราเตอร์แล้วคืนค่า response กลับมา โดยคำขอนี้จะวิ่งผ่านทั้งมิดเดิลแวร์, extractor, serialization และกลไกจัดการ error ของคุณอย่างครบถ้วน ไม่ต่างจากคำขอจริงที่เข้ามาทางเน็ตเวิร์กแม้แต่น้อย
#![allow(unused)]
fn main() {
use axum::body::Body;
use http::Request;
use tower::ServiceExt;
use http_body_util::BodyExt;
/// Build the application the same way production does, but with a test database.
async fn test_app() -> Router {
let pool = create_test_pool().await;
create_app_with_pool(pool).await
}
#[tokio::test]
async fn health_check_returns_200() {
let app = test_app().await;
let response = app
.oneshot(
Request::builder()
.uri("/health")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
}
#[tokio::test]
async fn creating_a_user_returns_201() {
let app = test_app().await;
let response = app
.oneshot(
Request::builder()
.method("POST")
.uri("/api/v1/users")
.header("Content-Type", "application/json")
.body(Body::from(serde_json::to_string(&serde_json::json!({
"name": "Alice",
"email": "alice@example.com",
"password": "securepassword"
})).unwrap()))
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::CREATED);
let body = response.into_body().collect().await.unwrap().to_bytes();
let user: serde_json::Value = serde_json::from_slice(&body).unwrap();
assert_eq!(user["data"]["name"], "Alice");
assert_eq!(user["data"]["email"], "alice@example.com");
}
#[tokio::test]
async fn creating_a_user_with_invalid_email_returns_400() {
let app = test_app().await;
let response = app
.oneshot(
Request::builder()
.method("POST")
.uri("/api/v1/users")
.header("Content-Type", "application/json")
.body(Body::from(r#"{"name":"Alice","email":"not-an-email","password":"securepassword"}"#))
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
}
}
จุดสำคัญในที่นี้คือ test_app() ประกอบ router ขึ้นมาด้วยฟังก์ชัน create_app ตัวเดียวกับที่ใช้งานบน production (หรือใกล้เคียงกันมากที่สุด) นั่นหมายความว่า integration test ของเราจะวิ่งผ่าน middleware stack เดียวกัน, extractor ชุดเดียวกัน และการจัดการ error แบบเดียวกันกับบน production หากมีจุดผิดพลาดจากการประกอบชิ้นส่วนเหล่านี้เข้าด้วยกัน เราก็จะตรวจพบได้ทันทีตั้งแต่ขั้นตอนนี้
อย่างไรก็ดี เราต้องเข้าใจข้อจำกัดด้วยว่าการทดสอบแบบ in-process เช่นนี้ไม่ได้ครอบคลุมทุกเรื่อง เนื่องจาก oneshot ส่งคำขอเข้าไปยังเราเตอร์โดยตรงโดยไม่ผ่าน socket จริง เราจึงไม่ได้ทดสอบการทำ TLS termination, พฤติกรรมของ reverse proxy, health check ของ load balancer หรือโครงสร้างการ deploy (deployment topology) แต่อย่างใด การทดสอบลักษณะนี้ยอดเยี่ยมมากสำหรับการตรวจสอบ logic ของแอปพลิเคชัน แต่มันไม่อาจทดแทน smoke test กับเซิร์ฟเวอร์ที่รันอยู่จริงๆ บนสภาพแวดล้อม staging ได้
การจัดการฐานข้อมูลสำหรับทดสอบ
Integration test ที่ต้องต่อเข้ากับฐานข้อมูลจริงจำเป็นต้องมีกลยุทธ์การแยกชุดข้อมูล (Test Isolation) ที่ชัดเจน เพราะคุณคงไม่อยากให้ข้อมูลที่คั่งค้างจากการทดสอบหนึ่งไปรบกวนผลลัพธ์ของการทดสอบอีกตัวหนึ่ง ซึ่งผมเองเคยเจอปัญหานี้บ่อยครั้งจนนับไม่ถ้วน
แยกฐานข้อมูลต่อหนึ่งเทสต์ด้วย SQLx (Per-test databases with SQLx) นี่คือแนวทางหลักที่ผมเลือกใช้ประจำ โดย SQLx มี attribute #[sqlx::test] ที่จะสร้างฐานข้อมูลใหม่พร้อมตั้งชื่อไม่ให้ซ้ำกันสำหรับการทดสอบแต่ละเคสโดยเฉพาะ แล้วรัน migration ให้โดยอัตโนมัติ และเมื่อการทดสอบเสร็จสิ้น ตัวฐานข้อมูลก็จะถูกลบทิ้งไปทันที มอบ isolation ที่สมบูรณ์แบบโดยแทบไม่ต้องออกแรงเพิ่ม:
#![allow(unused)]
fn main() {
#[sqlx::test(migrations = "./migrations")]
async fn test_user_creation(pool: PgPool) {
let repo = PostgresUserRepo::new(pool);
let req = CreateUserRequest { /* ... */ };
let user = repo.create(&req).await.unwrap();
assert_eq!(user.email().as_str(), "alice@example.com");
}
}
ใช้ฐานข้อมูลทดสอบร่วมกันพร้อมเคลียร์ข้อมูล (Shared test database with cleanup) อีกทางเลือกหนึ่งคือการใช้ฐานข้อมูลทดสอบร่วมกันเพียงตัวเดียว แล้วทำการล้างข้อมูลระหว่างการทดสอบแต่ละเคส ไม่ว่าจะใช้วิธี truncate ข้อมูลในตาราง หรือครอบการทดสอบแต่ละรายการไว้ใน database transaction แล้วสั่ง rollback เมื่อทดสอบเสร็จสิ้น วิธีนี้จะเร็วกว่าการสร้างและลบฐานข้อมูลใหม่ทุกครั้ง ทว่าจำเป็นต้องมีการจัดการที่รัดกุมรอบคอบ คุณอาจสงสัยว่าความเร็วที่ได้มานั้นคุ้มค่ากับความซับซ้อนที่เพิ่มขึ้นหรือไม่ จากประสบการณ์ของผม สำหรับทีมส่วนใหญ่มักไม่ค่อยคุ้มค่านัก แต่หาก test suite ของคุณเริ่มใช้เวลารันนานหลายนาที ทางเลือกนี้ก็นับว่าคุ้มค่าที่จะพิจารณา
In-memory SQLite เพื่อการทดสอบที่รวดเร็วเป็นพิเศษ หากคำสั่ง SQL ของคุณเข้ากันได้กับ SQLite (ซึ่งมักจะเข้ากันได้ดีกับการทำ CRUD ทั่วไป) คุณสามารถใช้ in-memory SQLite เพื่อให้การรันเทสต์ทำได้อย่างรวดเร็วสูงสุด วิธีนี้มีประโยชน์อย่างยิ่งสำหรับการทดสอบระดับ repository ที่คุณต้องการเพียงตรวจสอบ logic ของ query โดยไม่ต้องแบกรับ overhead จากการรัน PostgreSQL เต็มรูปแบบ
ตัวช่วยทดสอบ
เมื่อ test suite ของคุณเติบโตขึ้นเรื่อยๆ คุณจะเริ่มสังเกตเห็นโค้ด setup ซ้ำๆ กระจายอยู่ทั่วทุกแห่ง ไม่ว่าจะเป็นการสร้าง request, การสร้าง test user หรือการแกะ parse response body ในตอนแรกคุณอาจรู้สึกว่าเป็นเรื่องเล็กน้อย แต่การสละเวลาสกัดโค้ดเหล่านั้นออกมาเป็น test helper กลาง จะช่วยยกระดับความสะดวกในการพัฒนาได้อย่างมหาศาล และนี่คือแพตเทิร์นที่ผมพบว่าทำงานได้ดีมาก:
#![allow(unused)]
fn main() {
// tests/common/mod.rs
pub async fn test_app() -> Router {
let pool = PgPool::connect(&test_database_url()).await.unwrap();
sqlx::migrate!("./migrations").run(&pool).await.unwrap();
create_app_with_pool(pool).await
}
pub fn test_database_url() -> String {
std::env::var("TEST_DATABASE_URL")
.unwrap_or_else(|_| "postgres://localhost/myapp_test".to_string())
}
pub async fn create_test_user(app: &Router) -> (Uuid, String) {
// Helper that creates a user and returns (user_id, auth_token)
// Reduces boilerplate in tests that need an authenticated user
// ...
}
pub async fn response_json(response: Response) -> serde_json::Value {
let body = response.into_body().collect().await.unwrap().to_bytes();
serde_json::from_slice(&body).unwrap()
}
}
สิ่งที่ควรทดสอบ
แล้วในทางปฏิบัติ คุณควรทุ่มเทเวลาให้กับการทดสอบส่วนไหนบ้าง? มาโฟกัสที่สิ่งที่สำคัญที่สุดกันครับ:
ทดสอบ Happy Path ของทุก endpoint ตรวจสอบว่า input ที่ถูกต้องจะส่ง response ที่ตรงตามคาดหวังกลับมา ทั้ง status code และโครงสร้างของ body นี่คือบรรทัดฐานขั้นต่ำที่ต้องมีเสมอ
ทดสอบกรณี Validation ล้มเหลว ลองส่งข้อมูลที่ไม่ถูกต้องเข้าไป แล้วตรวจสอบว่า API คืน error response ที่เหมาะสมกลับมาหรือไม่ การทดสอบนี้จะช่วยดักจับ regression เมื่อมีใครเผลอลบหรือผ่อนปรน validation rule โดยไม่ตั้งใจ ซึ่งเป็นปัญหาที่เกิดขึ้นบ่อยกว่าที่คุณคิด
ทดสอบ Authorization และสิทธิ์การเข้าถึง ยืนยันว่าคำขอที่ไม่ผ่าน authentication จะต้องถูกปฏิเสธเสมอ, ผู้ใช้คนหนึ่งไม่สามารถแอบดูหรือแก้ไขข้อมูลของผู้ใช้คนอื่นได้ และบทบาท (role) ต่างๆ ถูกบังคับใช้อย่างเคร่งครัด เพราะช่องโหว่ด้านความปลอดภัยคือสิ่งที่จะทำให้คุณนอนไม่หลับในยามค่ำคืน
ทดสอบ Error Mapping ยืนยันว่า domain error (เช่น อีเมลซ้ำ) ถูกแปลงออกมาเป็น HTTP status code และ error message ที่ถูกต้องเหมาะสม ไม่ใช่ตอบกลับด้วย 500 Internal Server Error ทั่วไป เราได้ลงทุนลงแรงออกแบบ error type ไว้อย่างดีในบทก่อนหน้าแล้ว จึงควรตรวจสอบให้แน่ใจว่าพวกมันถูกสื่อสารไปยัง client ได้อย่างถูกต้องสมบูรณ์
ทดสอบ Edge Case ใน domain logic ไม่ว่าจะเป็นสตริงว่าง, สตริงขนาดยาวเป็นพิเศษ, ค่าที่ขอบเขต (boundary values) หรือการส่งอินพุตประหลาดๆ มารวมกัน บั๊กมักชอบแอบซ่อนอยู่ในจุดเหล่านี้ ซึ่งกรณีเหล่านี้เหมาะที่สุดที่จะทดสอบในระดับ unit test เพราะทำงานได้รวดเร็วและโฟกัสได้อย่างตรงจุด
และข้อคิดสุดท้าย: อย่าหลงหมกมุ่นกับตัวเลข Code Coverage จนเกินไป Test suite ที่ผ่านการคิดใคร่ครวญจนครอบคลุมพฤติกรรมสำคัญและ edge case ต่างๆ มีคุณค่ามากกว่าชุดทดสอบที่วิ่งไล่ตามตัวเลข coverage 90% โดยการทดสอบ getter และ setter จุกจิก สิ่งที่ผมพบเสมอคือ ตัวเลข coverage อาจช่วยให้คุณรู้สึกสบายใจ แต่ชุดการทดสอบที่คัดสรรมาอย่างรอบคอบต่างหากที่จะช่วยดักจับบั๊กได้จริงก่อนขึ้นระบบ เมื่อกลยุทธ์การทดสอบของเราพร้อมแล้ว ต่อไปเราจะไปดูเรื่องการนำแอปพลิเคชันไป deploy และรันบน production กันครับ
ประสิทธิภาพ
ข้อดีที่ยอดเยี่ยมประการหนึ่งของการเลือกใช้ Rust และ Axum คือคุณจะได้รับขีดความสามารถด้านประสิทธิภาพ (Performance Baseline) ที่แข็งแกร่งตั้งแต่เริ่มต้นโดยแทบไม่ต้องปรับแต่งอะไรเป็นพิเศษ การทำงานร่วมกันระหว่าง zero-cost abstractions, การไม่มี garbage collector และ async runtime ของ Tokio ทำให้แอปพลิเคชัน Axum ทั่วไปของเราสามารถรองรับการเชื่อมต่อพร้อมกันได้หลายพันรายการบนฮาร์ดแวร์ขนาดพอประมาณ ถึงกระนั้น เราก็ยังอาจพลาดโอกาสในการรีดเค้นประสิทธิภาพออกมาได้อย่างเต็มเม็ดเต็มหน่วย หากเราไม่ได้ใส่ใจกับวิธีใช้งานเครื่องมือต่างๆ อย่างถี่ถ้วน
ในบทนี้ เราจะมาสำรวจแนวปฏิบัติที่ดีเพื่อช่วยรักษาให้แอปพลิเคชันทำงานได้รวดเร็วอยู่เสมอ พร้อมทั้งเจาะลึกหลุมพรางที่ผมมักเห็นผู้คนสะดุดบ่อยๆ
อย่าบล็อก async runtime
หากมีกฎเหล็กด้านประสิทธิภาพเพียงข้อเดียวที่คุณควรจดจำจากหนังสือทั้งเล่มนี้ ขอให้เป็นข้อนี้: Tokio runtime อาศัย thread pool เพื่อรัน async task ร่วมกันแบบเอื้ออารี (cooperatively) หากมี task ใด task หนึ่งเข้าไปบล็อกเธรดไว้ (เช่น ทำงานที่กิน CPU หนักๆ, ทำ synchronous I/O หรือเรียกใช้ blocking library function) เธรดนั้นจะไม่สามารถไปรับ task อื่นได้เลยจนกว่างานที่บล็อกจะเสร็จสิ้น และเนื่องจากค่าเริ่มต้นของ Tokio จะจัดสรร worker thread หนึ่งตัวต่อหนึ่ง CPU core เท่านั้น การบล็อกแม้เพียงเธรดเดียวจึงส่งผลกระทบให้ throughput ลดลงอย่างเห็นได้ชัดในทันที
สิ่งที่รับมือได้ยากคืออาการของปัญหามักไม่ปรากฏให้เห็นในสภาวะปกติ แอปพลิเคชันอาจจัดการกับโหลดระดับปานกลางได้อย่างสบายๆ แต่เมื่อการทำงานพร้อมกัน (concurrency) เพิ่มสูงขึ้น เราจะเริ่มเห็นค่า latency พุ่งสูงขึ้นอย่างกะทันหันและ throughput ตกฮวบ สิ่งที่เกิดขึ้นจริงเบื้องหลังคือ async task จำนวนมากต้องต่อคิวรอเธรดที่กำลังติดหล่มอยู่กับงานแบบ synchronous บางอย่าง
ทางออกของเรื่องนี้คือการย้ายงานที่บล็อกเหล่านั้นไปยัง thread pool แยกต่างหากสำหรับงานประเภทนี้โดยเฉพาะ:
#![allow(unused)]
fn main() {
// CPU-intensive work (password hashing, image processing, etc.)
let hash = tokio::task::spawn_blocking(move || {
hash_password(&password)
})
.await
.context("password hashing task panicked")??;
}
spawn_blocking จะรัน closure บน blocking thread pool ของ Tokio ซึ่งแยกขาดจาก async worker thread และในระหว่างที่รอลำดับผลลัพธ์ async task ของเราจะยอมสละ (yield) การควบคุมคืน ทำให้ worker thread ว่างไปประมวลผลคำขออื่นๆ ได้อย่างต่อเนื่อง
อย่างไรก็ตาม มีข้อควรระวังสำคัญประการหนึ่ง: spawn_blocking ถูกออกแบบมาเพื่อเป็นช่องทางผ่อนปรนฉุกเฉิน (escape hatch) ไม่ใช่ตัวจัดตารางงานคำนวณทั่วไป โดยค่าเริ่มต้น blocking pool ของ Tokio จะจำกัดไว้สูงสุดที่ 512 เธรด หากเราสั่ง spawn blocking task หนึ่งตัวต่อหนึ่งคำขอขาเข้าระหว่างที่ traffic พุ่งกระฉูด เราอาจทำให้ thread pool เต็มอย่างรวดเร็ว ส่งผลให้การเรียก spawn_blocking ในคำขอถัดๆ ไปต้องติดค้างรอคิว สำหรับงานที่กิน CPU หนักๆ ภายใต้ concurrency สูง ผมแนะนำให้จำกัดจำนวนงานบล็อกที่รันพร้อมกันด้วย tokio::sync::Semaphore หรือย้ายงานเหล่านั้นไปยัง thread pool สำหรับงานคำนวณโดยเฉพาะอย่าง rayon นอกจากนี้ควรทราบด้วยว่า เมื่อ blocking task เริ่มทำงานไปแล้วจะไม่สามารถสั่งยกเลิก (abort) ได้ ดังนั้นหากแอปพลิเคชันกำลังเข้าสู่กระบวนการ shutdown มันจะต้องรอจนกว่า blocking task ทั้งหมดจะทำงานเสร็จสิ้นก่อนจึงจะออกจากโปรเซสได้
แหล่งที่มาทั่วไปของการบล็อกเธรดโดยไม่ตั้งใจ ได้แก่:
- การแฮชรหัสผ่าน ด้วย Argon2 หรือ bcrypt (ซึ่งออกแบบมาให้กินทรัพยากร CPU เป็นหลัก)
- Synchronous File I/O (ควรใช้
tokio::fsแทนที่จะเป็นstd::fs) - การ resolve DNS ใน HTTP client บางตัว (ควรเลือกใช้ async-native client อย่าง
reqwest) - การเรียก
.lock()บนstd::sync::Mutex(ควรเปลี่ยนไปใช้tokio::sync::Mutexหากจำเป็นต้องถือ lock ข้ามจุด await)
พูลการเชื่อมต่อ
การสร้าง database connection ใหม่ในทุกๆ คำขอนั้นมีต้นทุนสูงมาก ทั้ง TCP handshake, การเจรจา TLS negotiation ตลอดจนกระบวนการ authentication ซึ่งรวมกันแล้วอาจกินเวลาเพิ่มขึ้นหลายสิบมิลลิวินาทีได้อย่างง่ายดาย ระบบ connection pool จะช่วยเฉลี่ยต้นทุนดังกล่าวด้วยการเปิด connection เตรียมไว้ล่วงหน้าเป็นชุด เพื่อให้แต่ละคำขอยืมไปใช้งานแล้วส่งคืนกลับเข้าพูลเมื่อเสร็จสิ้น
PgPool ของ SQLx จัดการเรื่องนี้ให้เราอย่างโปร่งใส สิ่งสำคัญที่สุดคือการปรับขนาดของ pool ให้เหมาะสมกับการใช้งาน:
#![allow(unused)]
fn main() {
PgPoolOptions::new()
.max_connections(10)
.min_connections(2)
.acquire_timeout(Duration::from_secs(3))
}
หากตั้งขนาดพูลเล็กเกินไป แต่ละคำขอก็จะต้องต่อคิวรอ connection นาน แต่หากตั้งขนาดใหญ่เกินไป ก็จะสิ้นเปลืองหน่วยความจำบนฐานข้อมูลเซิร์ฟเวอร์ และเสี่ยงต่อการชนขีดจำกัดจำนวน connection สูงสุดของ PostgreSQL จุดเริ่มต้นที่ดีคือประมาณ 2 ถึง 4 connection ต่อหนึ่ง CPU core บน application server จากนั้นจึงค่อยปรับจูนตามสัดส่วนเวลาจริงที่คำขอใช้ไปกับการทำงานในฐานข้อมูลเทียบกับการประมวลผลส่วนอื่น
acquire_timeout เปรียบเสมือนตาข่ายนิรภัยของเรา หาก connection ทั้งหมดถูกใช้งานอยู่และคำขอใหม่ไม่สามารถขอรับ connection ได้ภายในระยะเวลา timeout ที่กำหนด มันจะแจ้งข้อผิดพลาดออกมาทันทีแทนที่จะค้างเติ่งอย่างไร้จุดหมาย ซึ่งดีกว่าการปล่อยให้คำขอนั่งรออยู่ในคิวนานถึง 30 วินาทีก่อนจะเกิด timeout ในระดับ HTTP อย่างเทียบกันไม่ได้
การบีบอัดการตอบกลับ
การบีบอัด response body ด้วย gzip หรือ brotli สามารถช่วยลดปริมาณข้อมูลที่ต้องส่งผ่านเครือข่ายได้อย่างมหาศาล โดยเฉพาะอย่างยิ่งกับ JSON API ซึ่งเนื้อหาของการตอบกลับเป็นข้อความที่สามารถบีบอัดได้อย่างมีประสิทธิภาพสูง
#![allow(unused)]
fn main() {
use tower_http::compression::CompressionLayer;
let app = Router::new()
.merge(routes)
.layer(CompressionLayer::new())
.with_state(state);
}
CompressionLayer จะเจรจาเลือกอัลกอริทึมการบีบอัดกับไคลเอนต์โดยอัตโนมัติตาม header Accept-Encoding สำหรับ JSON API ส่วนใหญ่ การบีบอัดด้วย gzip สามารถลดขนาดของ response ลงได้ถึง 70 ถึง 90 เปอร์เซ็นต์ ซึ่งส่งผลให้ไคลเอนต์ได้รับข้อมูลเร็วขึ้นอย่างเห็นได้ชัด โดยเฉพาะอย่างยิ่งบนเครือข่ายที่มีความเร็วต่ำ
การจัดการข้อมูลอย่างมีประสิทธิภาพ
หลีกเลี่ยงการจัดสรรหน่วยความจำที่ไม่จำเป็น (Avoid unnecessary allocations) ในจุดที่เป็นเส้นทางประมวลผลหลัก (hot path) ควรเลือกใช้การยืม (&str) มากกว่าชนิดข้อมูลที่เป็นเจ้าของหน่วยความจำ (String) เท่าที่จะทำได้ และเลือกใช้ iterator แทนการสั่ง .collect() ลงใน vector พักข้อมูลชั่วคราว แม้สิ่งเหล่านี้จะเป็นการปรับแต่งจุดเล็กๆ แต่จะมีผลลัพธ์ทวีคูณเมื่อระบบต้องรับมือกับ traffic ปริมาณมหาศาล
ใช้ Arc สำหรับข้อมูลส่วนกลางที่ไม่เปลี่ยนแปลง (Use Arc for shared immutable data) ค่าคอนฟิกูเรชัน, static asset และข้อมูลอื่นๆ ที่ไม่มีการเปลี่ยนแปลงหลังสตาร์ตอัปควรห่อหุ้มไว้ด้วย Arc เพื่อให้การโคลน state ของแอปพลิเคชันมีต้นทุนที่ถูกมาก (เพียงแค่เพิ่มตัวนับ reference count) แทนที่จะต้องเสียต้นทุนสูงในการทำ deep copy ข้อมูลทั้งหมด
สตรีมการตอบกลับขนาดใหญ่ (Stream large responses) สำหรับ endpoint ที่ต้องส่งคืนข้อมูลปริมาณมาก ให้เลือกส่งข้อมูลแบบสตรีมแทนที่จะบัฟเฟอร์ข้อมูลทั้งหมดขึ้นมาไว้ในหน่วยความจำ โดย crate อย่าง axum-streams มีความสามารถรองรับการสตรีมทั้ง JSON array, ไฟล์ CSV และฟอร์แมตอื่นๆ ได้อย่างยอดเยี่ยม
การปรับควิวรีฐานข้อมูลให้เหมาะสม
จากประสบการณ์ของผม ฐานข้อมูลมักเป็นคอขวดหลักของเว็บแอปพลิเคชันเกือบตลอดเวลา แนวปฏิบัติสำคัญเพียงไม่กี่ข้อต่อไปนี้จะช่วยสร้างความแตกต่างได้อย่างแท้จริง:
สร้างดัชนี (Index) บนคอลัมน์ที่ใช้ในการค้นหาหรือกรองข้อมูล หากเราต้องค้นหาผู้ใช้ด้วยอีเมล เราต้องมั่นใจว่าคอลัมน์ email มีการทำ index ไว้ เพราะหากไม่มี ฐานข้อมูลจะต้องสแกนอ่านข้อมูลทุกแถวในตาราง (Full Table Scan) ในทุกครั้งที่ค้นหา
ใช้ EXPLAIN ANALYZE เพื่อทำความเข้าใจแผนการทำงานของคิวรี (Query Plan) เมื่อพบว่าคิวรีทำงานช้า ให้ลองรันด้วย EXPLAIN ANALYZE บน database client ของคุณเพื่อดูว่าฐานข้อมูลประมวลผลคำสั่งนั้นอย่างไรในความเป็นจริง โดยเฉพาะการมองหา sequential scan บนตารางขนาดใหญ่ ซึ่งมักเป็นสัญญาณบ่งชี้ว่าคอลัมน์นั้นยังขาด index
ดึงเฉพาะข้อมูลที่จำเป็นต้องใช้เท่านั้น หาก handler ต้องการใช้งานเพียงแค่ชื่อและอีเมลของผู้ใช้ อย่าใช้คำสั่ง SELECT * เพื่อดึงข้อมูลมาทุกคอลัมน์ การระบุเลือกเฉพาะคอลัมน์ที่ต้องการจะช่วยลดทั้งภาระการส่งข้อมูลผ่านเน็ตเวิร์กและการประมวลผลในหน่วยความจำ
ใช้ Pagination กับ endpoint ที่แสดงรายการข้อมูลเสมอ ตามที่เราได้กล่าวถึงในบท การออกแบบ API ให้ทำ pagination กับคิวรีประเภทรายการข้อมูลเสมอ การยิงคำสั่ง SELECT * FROM users แบบไม่มีขอบเขตจำกัดบนตารางที่มีข้อมูลนับล้านแถว ย่อมทำให้ระบบและแอปพลิเคชันล่มลงได้อย่างแน่นอน
การวัดประสิทธิภาพและการวิเคราะห์ประสิทธิภาพ
เมื่อถึงคราวที่ต้องปรับปรุงประสิทธิภาพ จงเริ่มต้นด้วยการตรวจวัดก่อนเสมอ การคาดเดาจุดที่เป็นคอขวดเป็นวิธีที่ไม่น่าเชื่อถือ เพราะคอขวดที่แท้จริงมักไม่ได้อยู่ในจุดที่คุณนึกคิด
Criterion คือเฟรมเวิร์กมาตรฐานสำหรับการทำ benchmark ในภาษา Rust ซึ่งให้ผลการทดสอบที่รัดกุมและมีความน่าเชื่อถือทางสถิติพร้อม confidence interval ช่วยให้เราพิสูจน์ได้ว่าโค้ดที่แก้ไขไปนั้นช่วยยกระดับประสิทธิภาพได้จริง หรือเป็นเพียงความบังเอิญที่รันเร็วขึ้นแค่บางรอบเท่านั้น
Flamegraph ช่วยสร้างภาพจำลองให้เห็นว่าแอปพลิเคชันของเราใช้เวลาของ CPU ไปกับฟังก์ชันใดบ้าง ซึ่งผมพบว่ามีประโยชน์อย่างยิ่งในการชี้เป้า hot spot ในสภาวะ workload ที่ใกล้เคียงกับบน production จริง
DHAT ช่วยวิเคราะห์โปรไฟล์การจัดสรรหน่วยความจำ ทำให้เราค้นพบจุดที่มีการจอง memory เกินความจำเป็นได้อย่างตรงจุด
tokio-console เป็นเครื่องมือวิเคราะห์และวินิจฉัยที่พัฒนาขึ้นสำหรับ async Rust โดยเฉพาะ แสดงให้เห็นภาพรวมว่ามี task ใดกำลังรันอยู่, task ใดถูกบล็อก และ runtime จัดตารางเวลาอย่างไร ซึ่งมีประโยชน์อย่างยิ่งสำหรับการค้นหาสาเหตุของปัญหา “รันไทม์ถูกบล็อก” ที่เราได้กล่าวถึงไปในตอนต้นของบท
สิ่งที่ไม่ควรปรับให้เหมาะสม
สิ่งสำคัญที่ควรตระหนักไว้เสมอคือ การด่วนปรับปรุงประสิทธิภาพก่อนเวลาอันควร (Premature Optimization) มีต้นทุนแฝงที่ต้องจ่ายจริง การพยายามทำ micro-optimize กับ handler ที่ใช้เวลาเพียง 2 มิลลิวินาที ทั้งๆ ที่ database query ภายในนั้นกินเวลาไปถึง 50 มิลลิวินาที นับเป็นการลงแรงที่สูญเปล่า จงโฟกัสความพยายามในการ optimize ไปที่คอขวดที่แท้จริง ซึ่งสำหรับเว็บแอปพลิเคชันแล้ว มักหนีไม่พ้น database query, network I/O และการบล็อก async runtime โดยไม่เจตนา
เริ่มต้นด้วยการเขียนโค้ดที่เข้าใจง่ายและเป็นสำนวน Rust ที่ดีเสียก่อน จากนั้นค่อยวัดผลด้วย profiler ภายใต้โหลดการใช้งานจริง แล้วจึงลงมือปรับแต่งเฉพาะจุดที่เครื่องมือฟ้องว่าช้า จากประสบการณ์ของผม วิธีการนี้จะช่วยส่งมอบแอปพลิเคชันที่มีทั้งความรวดเร็วและบำรุงรักษาได้อย่างมั่นใจในระยะยาว และนั่นคือสิ่งที่เราจำเป็นต้องใช้เมื่อเราไปดูวิธีทำให้แอปพลิเคชันตรวจสอบและสังเกตการณ์ได้ (Observability) ในบทถัดไป
การดีพลอยต์ (Deployment)
เมื่อเราพัฒนาเว็บเซอร์วิสเสร็จแล้ว ทดสอบจนผ่านฉลุย และมันรันได้อย่างราบรื่นบนเครื่องแล็ปท็อปของเรา แล้วขั้นตอนต่อไปคืออะไร? การนำระบบขึ้นสู่ production มีหัวใจสำคัญหลายประการที่เราต้องทำให้ถูกต้อง: ตั้งแต่การสร้างคอนเทนเนอร์อิมเมจขนาดเล็กกะทัดรัด, การปิดระบบอย่างนุ่มนวล (Graceful Shutdown) เพื่อไม่ให้คำขอที่กำลังประมวลผลอยู่หลุดหาย ไปจนถึงการจัดเตรียม health check endpoint ให้ออร์เคสเตรเตอร์คอยตรวจสอบสถานะของแอปพลิเคชันได้อย่างแม่นยำ มาดูรายละเอียดในแต่ละเรื่องกันครับ
Docker และบิลด์แบบหลายสเตจ
หากคุณคอมไพล์โค้ด Rust ด้วย target มาตรฐานของ GNU Linux (x86_64-unknown-linux-gnu) ไบนารีที่ได้จะถูกลิงก์แบบไดนามิกกับ glibc โดยไม่มี runtime dependency อื่นใดเพิ่มเติม หรือคุณอาจเลือกคอมไพล์ด้วย target อย่าง musl (x86_64-unknown-linux-musl) เพื่อให้ได้ไบนารีที่เป็น static ล้วน 100% เลยก็ได้ ไม่ว่าจะเลือกทางไหน คอนเทนเนอร์บน production ของเราก็ไม่จำเป็นต้องมี Rust toolchain, ซอร์สโค้ด หรือ build dependency ใดๆ หลงเหลืออยู่อีกเลยนอกจาก C library มาตรฐาน ซึ่งนับเป็นข่าวดีอย่างยิ่ง เพราะหมายความว่าเราสามารถใช้เทคนิค Docker multi-stage build ได้อย่างเต็มประสิทธิภาพ: นั่นคือคอมไพล์ซอร์สโค้ดในสเตจแรก จากนั้นคัดลอกเฉพาะตัวไบนารีที่ได้ไปยัง runtime image ขนาดจิ๋วในสเตจถัดไป
# Build stage
FROM rust:1-slim AS builder
WORKDIR /app
# Cache dependencies by copying just the manifest files first.
# For more robust dependency caching, consider the cargo-chef crate,
# which is purpose-built for this problem in Docker builds.
COPY Cargo.toml Cargo.lock ./
RUN mkdir src && echo "fn main() {}" > src/main.rs
RUN cargo build --release && rm -rf src
# Now copy the actual source and rebuild (only changed files recompile)
COPY . .
RUN touch src/main.rs && cargo build --release
# Runtime stage
FROM debian:bookworm-slim
RUN apt-get update \
&& apt-get install -y --no-install-recommends ca-certificates \
&& rm -rf /var/lib/apt/lists/*
# Run as a non-root user
RUN useradd --create-home appuser
USER appuser
COPY --from=builder /app/target/release/my-app /usr/local/bin/my-app
EXPOSE 3000
CMD ["my-app"]
เทคนิคการแคช dependency ใน build stage เป็นเรื่องที่คุ้มค่าแก่การทำความเข้าใจอย่างยิ่ง เราเริ่มต้นด้วยการคัดลอกเพียงแค่ Cargo.toml และ Cargo.lock เข้ามาก่อน แล้วสั่งรันบิลด์เพื่อสร้าง dummy project ซึ่งจะช่วยให้ Docker สามารถแคช dependency ทั้งหมดที่คอมไพล์เสร็จแล้วเก็บไว้เป็นเลเยอร์ได้ และเมื่อใดก็ตามที่เราแก้ไขโค้ดของแอปพลิเคชันโดยที่ไม่ได้แตะต้อง dependency (ซึ่งมักเป็นกรณีส่วนใหญ่ในการทำงานประจำวัน) Docker จะนำเลเยอร์แคชเดิมมาใช้ซ้ำทันที และคอมไพล์เฉพาะโค้ดส่วนของเราที่เปลี่ยนแปลงเท่านั้น หากปราศจากเทคนิคนี้ คุณจะต้องนั่งรอคอมไพล์ dependency ทั้งหมดใหม่ทุกครั้งที่บิลด์ และด้วยระยะเวลาการคอมไพล์ของ Rust ในปัจจุบัน มันจะกลายเป็นความทรมานอย่างรวดเร็ว
คุณอาจสงสัยว่าเหตุใดเราจึงต้องติดตั้ง ca-certificates ใน runtime image คำตอบคือแอปพลิเคชันของเรามักจะต้องยิง outbound HTTPS request ออกไปภายนอก (เช่น เรียกใช้ external API, payment gateway หรือบริการอื่นๆ) จึงจำเป็นต้องมีชุด CA certificate bundle ไว้ตรวจสอบความถูกต้องของการเชื่อมต่อ TLS หากละเลยขั้นตอนนี้ คุณจะพบกับข้อผิดพลาดเกี่ยวกับ TLS อันลึกลับตอนรันไทม์ ซึ่งคงไม่ใช่เรื่องสนุกแน่ๆ หากต้องมานั่งดีบักบน production
หากคุณต้องการลดขนาดอิมเมจให้เล็กลงไปอีกขั้น คุณสามารถเลือกคอมไพล์ด้วย x86_64-unknown-linux-musl เพื่อผลิตไบนารีแบบ statically linked ล้วนๆ แล้วใช้ FROM scratch เป็น runtime base image ซึ่งจะช่วยบีบขนาดอิมเมจลงมาเหลือต่ำกว่า 20 MB ได้อย่างน่าประทับใจ ทว่าข้อแลกเปลี่ยนคือคุณจะไม่มีทั้ง shell หรือเครื่องมือช่วยดีบักใดๆ หลงเหลืออยู่ในคอนเทนเนอร์เลย ซึ่งอาจทำให้การสืบหาสาเหตุของปัญหายากขึ้นอย่างมากเมื่อเกิดเหตุฉุกเฉินตอนตีสอง จากประสบการณ์ของผม อิมเมจแบบ Debian slim ถือเป็นจุดสมดุลที่ดีที่สุดสำหรับทีมส่วนใหญ่
การปิดระบบอย่างนุ่มนวล
เมื่อ container orchestrator เช่น Kubernetes, ECS หรือ Docker Swarm ตัดสินใจจะหยุดการทำงานของแอปพลิเคชัน มันจะส่งสัญญาณ SIGTERM เข้ามาก่อน พร้อมทั้งให้ช่วงเวลาผ่อนผัน (grace period ซึ่งโดยทั่วไปคือ 30 วินาที) เพื่อเปิดโอกาสให้โปรเซสเคลียร์งานที่คั่งค้างอยู่ให้เสร็จสิ้นก่อนที่จะส่งสัญญาณเด็ดขาดอย่าง SIGKILL ตามมา หากแอปพลิเคชันของเราไม่ได้ดักจับและจัดการสัญญาณ SIGTERM สิ่งเลวร้ายย่อมเกิดขึ้น: คำขอที่กำลังประมวลผลค้างอยู่จะถูกตัดทิ้งทันที, database transaction จะตกค้างอยู่ในสถานะไม่ชัดเจน และฝั่งไคลเอนต์จะเจอกับ connection reset ซึ่งไม่มีใครอยากให้เกิดเหตุการณ์เช่นนั้นอย่างแน่นอน
ข่าวดีคือ Axum มีกลไกในตัวที่เตรียมไว้สำหรับการทำ graceful shutdown ไว้อย่างยอดเยี่ยม:
use tokio::signal;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// ... setup code ...
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
tracing::info!("listening on {}", listener.local_addr()?);
axum::serve(listener, app)
.with_graceful_shutdown(shutdown_signal())
.await?;
tracing::info!("server shut down cleanly");
Ok(())
}
async fn shutdown_signal() {
let ctrl_c = async {
signal::ctrl_c()
.await
.expect("failed to install Ctrl+C handler");
};
#[cfg(unix)]
let terminate = async {
signal::unix::signal(signal::unix::SignalKind::terminate())
.expect("failed to install SIGTERM handler")
.recv()
.await;
};
#[cfg(not(unix))]
let terminate = std::future::pending::<()>();
tokio::select! {
_ = ctrl_c => {},
_ = terminate => {},
}
tracing::info!("shutdown signal received, draining connections");
}
เมื่อได้รับสัญญาณแจ้งเตือนการปิดระบบ Axum จะหยุดรับการเชื่อมต่อใหม่ทันที แต่จะยังคงเดินหน้าประมวลผลคำขอที่ค้างอยู่ระหว่างดำเนินการ (in-flight requests) ต่อไปจนเสร็จสิ้น และเมื่อคำขอที่ค้างอยู่ทั้งหมดถูกประมวลผลจนหมด (หรือเมื่อหมดระยะเวลาผ่อนผัน) เซิร์ฟเวอร์ก็จะปิดตัวลงอย่างหมดจดและปลอดภัย
เรื่องนี้มีความสำคัญอย่างยิ่งต่อการทำงานกับฐานข้อมูล เพราะหากคำขอกำลังทำงานอยู่กึ่งกลาง transaction ในจังหวะที่สัญญาณ SIGKILL ฟาดลงมา แม้ฐานข้อมูลจะสั่ง rollback transaction นั้นในท้ายที่สุดหลังจาก connection timeout แต่ไคลเอนต์จะเห็นเป็น error ทันที ในทางกลับกัน ด้วยการทำ graceful shutdown ตัว transaction จะสามารถทำงานต่อจนเสร็จสมบูรณ์ตามปกติ และส่ง response ที่ถูกต้องกลับไปยังไคลเอนต์ได้ นี่คือหนึ่งในรายละเอียดที่หลายคนอาจมองข้าม แต่มันสร้างความแตกต่างอย่างมหาศาลในการทำงานจริงบน production
การตรวจสุขภาพ
Health check endpoint ทำหน้าที่สื่อสารกับ container orchestrator หรือ load balancer เพื่อรายงานว่าแอปพลิเคชันยังมีชีวิตอยู่และพร้อมที่จะให้บริการ traffic หรือไม่ โดยทั่วไป orchestrator ส่วนใหญ่จะแบ่งประเภทของการตรวจสอบสุขภาพออกเป็น 2 ชนิดหลักๆ ซึ่งคุ้มค่าอย่างยิ่งที่จะทำความเข้าใจความแตกต่างของทั้งสองตัว เพราะหากตั้งค่าสับสน อาจนำไปสู่พฤติกรรมประหลาดที่ชวนปวดหัวได้
Liveness Probe ตอบคำถามที่ว่า: “โปรเซสยังมีชีวิตอยู่และไม่ได้เกิดอาการค้าง (hang) ใช่หรือไม่?” หาก liveness probe ล้มเหลว ตัว orchestrator จะสั่งรีสตาร์ตคอนเทนเนอร์ใหม่ทันที การตรวจสอบนี้จึงควรเน้นความเรียบง่ายและรวดเร็วเป็นหลัก และนี่คือข้อควรระวังสำคัญที่สุด: อย่าตรวจสอบ dependency ภายนอกใน liveness probe เป็นอันขาด หากฐานข้อมูลเกิดขัดข้องชั่วคราว คุณคงไม่ต้องการให้ orchestrator ไล่ฆ่าแล้วรีสตาร์ตเว็บแอปพลิเคชันวนไปเรื่อยๆ เพราะการทำเช่นนั้นจะยิ่งเป็นการกระหน่ำโหลดซ้ำเติมฐานข้อมูลที่กำลังวิกฤตอยู่ให้ย่ำแย่ลงไปอีก
#![allow(unused)]
fn main() {
async fn health_live() -> StatusCode {
StatusCode::OK
}
}
Readiness Probe ตอบคำถามที่ต่างออกไป: “อินสแตนซ์นี้พร้อมที่จะรับ traffic หรือยัง?” หาก readiness probe ล้มเหลว orchestrator จะเพียงแค่หยุดการส่ง traffic มายังอินสแตนซ์ตัวนี้ชั่วคราวโดยไม่สั่งรีสตาร์ตคอนเทนเนอร์ จุดนี้เองคือตำแหน่งที่เราควรตรวจสอบว่า connection ไปยังฐานข้อมูลยังปกติดีหรือไม่, cache ที่จำเป็นสามารถเข้าถึงได้หรือยัง และแอปพลิเคชันทำขั้นตอน initialization ตอนสตาร์ตอัปเสร็จสิ้นเรียบร้อยแล้วหรือไม่
#![allow(unused)]
fn main() {
async fn health_ready(State(state): State<AppState>) -> StatusCode {
let db_ok = sqlx::query("SELECT 1")
.execute(&state.db)
.await
.is_ok();
if db_ok {
StatusCode::OK
} else {
StatusCode::SERVICE_UNAVAILABLE
}
}
}
เราจะเมานต์ (mount) endpoint เหล่านี้ไว้ภายนอกเส้นทาง API ที่มีเวอร์ชัน:
#![allow(unused)]
fn main() {
let app = Router::new()
.route("/health", get(health_live))
.route("/health/ready", get(health_ready))
.nest("/api/v1", api_routes())
.with_state(state);
}
สำหรับการ deploy บน Kubernetes คุณสามารถกำหนดค่า probe ภายใน pod spec ได้ดังนี้:
livenessProbe:
httpGet:
path: /health
port: 3000
initialDelaySeconds: 5
periodSeconds: 10
readinessProbe:
httpGet:
path: /health/ready
port: 3000
initialDelaySeconds: 5
periodSeconds: 10
การตั้งค่าจากสภาพแวดล้อม
ตามที่เราได้อธิบายไว้ในบท การตั้งค่า แอปพลิเคชันของเราควรอ่าน configuration ทั้งหมดจาก environment variable ซึ่งหมายความว่าเราสามารถนำ Docker image ตัวเดียวกันนี้ไป deploy ใช้งานได้ทั้งบน development, staging และ production โดยสิ่งเดียวที่เปลี่ยนแปลงไปในแต่ละสภาพแวดล้อมมีเพียงแค่ค่าของ environment variable ที่ระบบ deployment platform ป้อนเข้ามาให้เท่านั้น
อย่าเผลอฝัง (hardcode/bake) ค่าคอนฟิกเฉพาะของสภาพแวดล้อมลงใน Docker image เป็นอันขาด ผมเห็นหลายทีมทำเช่นนี้และลงท้ายด้วยปัญหาเสมอ ตัวอิมเมจควรเป็นอาร์ติแฟกต์ที่ไม่เปลี่ยนแปลง (Immutable Artifact) ที่คุณทำการบิลด์เพียงครั้งเดียวแล้วสามารถนำไป deploy ได้ทุกที่ เมื่อคุณเลื่อนระดับ (promote) อิมเมจที่ผ่านการทดสอบอย่างสมบูรณ์จาก staging ขึ้นสู่ production คุณย่อมต้องการความมั่นใจเต็มร้อยว่าไบนารีที่กำลังรันอยู่นั้นเป็นตัวเดียวกันทุกประการ
การรันไมเกรชัน
Database migration ควรถูกสั่งรันเป็นส่วนหนึ่งของกระบวนการเริ่มต้นแอปพลิเคชัน (Startup) ก่อนที่เซิร์ฟเวอร์จะเปิดรับ traffic แรก ซึ่งเราสามารถจัดการเรื่องนี้ได้อย่างสะดวกด้วยมาโคร sqlx::migrate! ตามที่ได้อธิบายไว้ในบท เลเยอร์ฐานข้อมูล
หากอยู่ในสภาพแวดล้อมของ Kubernetes คุณอาจเลือกสั่งรัน migration ในรูปแบบของ Init Container หรือ Pre-deployment Job แยกต่างหากก็ได้เช่นกัน แนวทางนั้นจะมีความชัดเจนตรงไปตรงมาและช่วยแยกความล้มเหลวจากการทำ migration ออกจากความล้มเหลวในการสตาร์ตของตัวแอปพลิเคชันได้อย่างเด็ดขาด ทว่าสำหรับแอปพลิเคชันส่วนใหญ่ ประสบการณ์ของผมพบว่าการรัน migration ในจังหวะ startup โดยตรงนั้นเรียบง่ายกว่าและทำงานได้ดีอย่างยิ่ง โดยเฉพาะเมื่อทำงานควบคู่กับ readiness probe ซึ่งจะคอยการันตีว่าแอปพลิเคชันจะไม่เปิดรับ traffic ใดๆ จนกว่ากระบวนการ migration จะเสร็จสมบูรณ์และฐานข้อมูลพร้อมใช้งาน นับเป็นตาข่ายนิรภัยที่อุ่นใจได้อย่างแท้จริง
แล้ว Shuttle ล่ะ?
Shuttle คือแพลตฟอร์มการ deploy ที่พัฒนาขึ้นเพื่อระบบนิเวศของ Rust โดยเฉพาะ โดยช่วยดูแลเรื่องการจัดเตรียมโครงสร้างพื้นฐาน (Infrastructure Provisioning), การตั้งค่าฐานข้อมูล และการ deploy ให้โดยอัตโนมัติด้วยการตั้งค่าเพียงเล็กน้อย หากคุณไม่จำเป็นต้องลงไปควบคุมรายละเอียดในระดับโครงสร้างพื้นฐานด้วยตนเอง Shuttle จะช่วยปลดเปลื้องภาระงานด้าน operation ออกไปจากบ่าของคุณได้อย่างมหาศาล
อย่างไรก็ดี ผมเชื่อมั่นว่าการทำความเข้าใจวิธีการ deploy ด้วย Docker และ Kubernetes ย่อมมีคุณค่าอย่างยิ่ง ไม่ว่าสุดท้ายแล้วคุณจะเลือกใช้แพลตฟอร์มใดก็ตาม เพราะแนวคิดพื้นฐานที่เราได้กล่าวถึงในบทนี้ (ทั้งการทำ graceful shutdown, health check, การคอนฟิกผ่าน environment variable และการสร้าง immutable image) ล้วนเป็นหลักการสากลที่นำไปปรับใช้ได้ทุกหนแห่ง แม้ว่าคุณจะใช้งาน Shuttle หรือแพลตฟอร์มสำเร็จรูปอื่นๆ การเข้าใจสิ่งที่เกิดขึ้นภายใต้กระโปรงรถ (Under the Hood) ย่อมช่วยให้คุณสืบหาและแก้ปัญหาได้อย่างแม่นยำเมื่อเกิดเหตุไม่คาดฝันขึ้น
ข้อผิดพลาดแบบแอซิงก์และความปลอดภัยในการยกเลิก
หากคุณเคยเขียน async Rust มาระยะหนึ่ง คุณน่าจะเคยเจอบั๊กแปลกๆ ที่มองแวบแรกแล้วดูไม่มีเหตุผลเอาเสียเลย ข้อมูลจู่ๆ ก็สูญหาย, stream เกิดความเสียหาย หรือโค้ดทุกบรรทัดดูถูกต้องสมบูรณ์แบบ ทว่ากลับมีงานบางอย่างหลุดหายไปอย่างไร้ร่องรอย จากประสบการณ์ของผม ตัวการหลักเกือบทั้งหมดมักเกิดจากเรื่องของการยกเลิก (Cancellation): เมื่อ future ถูก drop ทิ้งไปก่อนที่มันจะทำงานจนเสร็จสิ้น งานที่มันกำลังทำอยู่จะหยุดชะงักลงทันที และโปรแกรมของคุณอาจตกค้างอยู่ในสถานะที่ไม่ได้คาดคิดมาก่อน
ในบทนี้ เราจะมาเจาะลึกแพตเทิร์นที่เป็นหลุมพรางดักผู้คนตรงจุดนี้ แม้แต่นักพัฒนา Rust ที่มีประสบการณ์สูงก็ยังพลาดได้ง่ายๆ โดยเราจะเน้นไปที่ tokio::select!, ความปลอดภัยในการยกเลิก (Cancellation Safety) และ structured concurrency primitive ที่จะช่วยให้คุณบริหารจัดการงานที่ทำงานพร้อมกันได้โดยไม่ชวนให้ปวดหัว
หลักการทำงานของ tokio::select!
tokio::select! คือเครื่องมือหลักของเราสำหรับการรอรับผลลัพธ์จาก async operation หลายรายการพร้อมๆ กัน โดยมันจะคอย poll ตรวจสอบทุกๆ branch (แขนง) และเมื่อมี branch ใด branch หนึ่งทำงานเสร็จก่อน มันจะ drop ทิ้ง branch ที่เหลือทั้งหมดทันที แล้วจึงหันไปรันโค้ดใน handler ของ branch ที่เสร็จนั้น
#![allow(unused)]
fn main() {
tokio::select! {
msg = rx.recv() => {
// A message arrived from the channel.
handle_message(msg).await;
}
_ = shutdown.cancelled() => {
// A shutdown signal was received.
tracing::info!("shutting down");
return;
}
}
}
จุดสำคัญที่สุดในที่นี้คือสิ่งที่เกิดขึ้นกับ branch ที่เป็นฝ่ายพ่ายแพ้ (branch ที่ไม่เสร็จเป็นอันแรก) เมื่อ shutdown.cancelled() ทำงานเสร็จก่อน future ของ rx.recv() จะถูกสั่ง drop ทิ้งทันที ซึ่งสำหรับเมธอด recv() นั้นไม่มีปัญหาใดๆ เกิดขึ้นเลย: เพราะ channel จะยังคงรักษาข้อความทั้งหมดที่ค้างอยู่ใน buffer ไว้อย่างปลอดภัย และเมื่อมีการเรียก recv() ในครั้งถัดไป มันก็จะหยิบข้อความมาทำงานต่อจากจุดเดิมได้อย่างราบรื่น คุณสมบัติอันยอดเยี่ยมเช่นนี้เองคือสิ่งที่เราเรียกว่า “ความปลอดภัยในการยกเลิก” (Cancellation Safety)
“ปลอดภัยต่อการยกเลิก” หมายถึงอะไร
Future จะถือว่า “ปลอดภัยต่อการยกเลิก” (Cancellation-safe) ก็ต่อเมื่อการสั่ง drop มันทิ้งกลางคันไม่ก่อให้เกิดการสูญหายของข้อมูล หรือไม่ทิ้ง shared state ไว้ในสภาพที่เสียหาย ในเอกสารทางการของ Tokio จะมีการระบุไว้อย่างชัดเจนว่าแต่ละฟังก์ชันหรือเมธอดมีความปลอดภัยต่อการยกเลิกหรือไม่ และผมขอแนะนำอย่างยิ่งให้คุณตรวจสอบตรงนี้ให้ถี่ถ้วนเสมอก่อนที่จะนำคำสั่งใดๆ ไปวางไว้ใน branch ของ select!
ตัวอย่างของ operation ที่ ปลอดภัยต่อการยกเลิก ได้แก่ channel.recv(), TcpListener::accept(), sleep() และ CancellationToken::cancelled() การ drop future เหล่านี้ทิ้งมีความหมายเพียงแค่ว่า “เราเลิกรอแล้วนะ” และไม่มีข้อมูลใดๆ สูญหาย
ในทางตรงกันข้าม operation ที่ ไม่ปลอดภัยต่อการยกเลิก ได้แก่ read_exact(), write_all() และ read_to_string() ลองจินตนาการดูว่าจะเกิดอะไรขึ้นหาก write_all เขียนข้อมูลไปได้ 50 ไบต์จากทั้งหมด 100 ไบต์ แล้วจู่ๆ select! ก็สั่ง drop มันทิ้ง: ข้อมูล 50 ไบต์นั้นถูกส่งออกไปยัง network wire เรียบร้อยแล้ว แต่คุณกลับไม่มีทางรู้ได้เลยว่าส่งสำเร็จไปแล้วกี่ไบต์ และเมื่อมีความพยายามจะเขียนข้อมูลในครั้งถัดไป มันก็จะเริ่มต้นส่งข้อความใหม่อีก 100 ไบต์ตั้งแต่ต้น ส่งผลให้ data stream เกิดความเสียหายทันที
มาดูตัวอย่างรูปธรรมที่สะท้อนถึงปัญหานี้กัน:
#![allow(unused)]
fn main() {
// BROKEN: buf is not cancel-safe inside select!
let mut buf = vec![0u8; 1024];
loop {
tokio::select! {
// If this branch loses, we lose track of how many bytes
// were read. The next iteration starts over with an empty buf.
result = socket.read_exact(&mut buf) => {
process(&buf).await;
}
_ = shutdown.cancelled() => {
return;
}
}
}
}
ทางแก้ไขสำหรับกรณีนี้คือ การย้าย operation ที่ไม่ปลอดภัยต่อการยกเลิกออกไปจาก select! โดยสิ้นเชิง เพื่อเปิดโอกาสให้มันทำงานจนเสร็จสมบูรณ์เสมอ แล้วเก็บเฉพาะ operation ที่ cancellation-safe อย่างแท้จริง (เช่น การรอรับข้อมูลจาก channel) ไว้ภายใน branch ของ select!:
#![allow(unused)]
fn main() {
loop {
tokio::select! {
result = rx.recv() => {
// Only cancel-safe operations in select! branches.
if let Some(data) = result {
process(&data).await;
}
}
_ = shutdown.cancelled() => {
return;
}
}
}
}
โมเดลแอ็กเตอร์ แพตเทิร์นที่ทนทานต่อการยกเลิก
วิธีที่ผมพบว่ามีความน่าเชื่อถือที่สุดในการหลีกเลี่ยงบั๊กที่เกิดจากการยกเลิก คือการจัดวางโครงสร้างคอมโพเนนต์ที่ทำงานแบบขนานให้อยู่ในรูปแบบของ Actor Model โดย actor แต่ละตัวจะรัน loop เพื่อรอรับข้อความ, นำข้อความนั้นไปประมวลผลจนเสร็จสมบูรณ์ แล้วจึงค่อยวนกลับมารอรับข้อความถัดไป และเนื่องจาก select! จะทำงานเฉพาะในจังหวะระหว่างรอบของ loop เท่านั้น (ตอนที่ actor กำลังนอนรอ input ใหม่ ไม่ใช่ตอนที่กำลังทำงานอยู่กึ่งกลางคัน) จึงไม่มีความเสี่ยงใดๆ ที่จะเกิดการยกเลิกงานกลางคันขึ้นได้เลย
#![allow(unused)]
fn main() {
async fn run_worker(
mut commands: mpsc::Receiver<Command>,
shutdown: CancellationToken,
) {
loop {
let command = tokio::select! {
cmd = commands.recv() => {
match cmd {
Some(c) => c,
None => return, // Channel closed, all senders dropped.
}
}
_ = shutdown.cancelled() => {
tracing::info!("worker shutting down");
return;
}
};
// This runs to completion before the next select! iteration.
// No cancellation risk here.
process_command(command).await;
}
}
}
นี่คือแพตเทิร์นที่เราเลือกใช้งานอย่างกว้างขวางใน topos-protocol/topos โดยแต่ละระบบย่อย (broadcast, synchronizer, API) จะรัน event loop ที่ทำ multiplex ระหว่างคำสั่ง, shutdown signal และ timer ต่างๆ ผ่านทาง select! แต่จะประมวลผลแต่ละ event จนเสร็จสิ้นอย่างสมบูรณ์ก่อนจะวนกลับขึ้นไปรับงานใหม่ที่จุดเริ่มต้นของ loop เสมอ ในตอนแรก โครงสร้างแบบนี้อาจดูเหมือนมีพิธีรีตองมากเกินจำเป็น แต่ในเวลาไม่นานมันจะตอบแทนคุณอย่างคุ้มค่า ด้วยการที่คุณจะไม่ต้องมานั่งปวดหัวไล่ล่าบั๊กพิลึกพิลั่นเหล่านี้อีกต่อไป
การทำงานพร้อมกันแบบมีโครงสร้างด้วย CancellationToken
เมื่อแอปพลิเคชันของคุณประกอบด้วยระบบย่อยที่ทำงานพร้อมกันหลายตัว (เช่น HTTP server, background worker, metrics reporter) คุณจำเป็นต้องมีกลไกที่ชัดเจนในการส่งสัญญาณสั่งให้ทุกตัวปิดการทำงานลงอย่างพร้อมเพรียงกัน แล้วค่อยรอจนกว่าแต่ละตัวจะเก็บกวาดงานของตนเองเสร็จสิ้นจริงๆ ซึ่งนี่คือจุดที่ tokio_util::sync::CancellationToken ก้าวเข้ามามีบทบาทสำคัญ
#![allow(unused)]
fn main() {
use tokio_util::sync::CancellationToken;
let root_token = CancellationToken::new();
// Each subsystem gets a child token. Cancelling the root
// cancels all children, but cancelling a child does not
// affect siblings or the parent.
let http_token = root_token.child_token();
let worker_token = root_token.child_token();
let metrics_token = root_token.child_token();
// Spawn subsystems with their tokens.
let http_handle = tokio::spawn(run_http_server(http_token));
let worker_handle = tokio::spawn(run_background_worker(worker_token));
let metrics_handle = tokio::spawn(run_metrics_reporter(metrics_token));
// When a shutdown signal arrives, cancel the root.
wait_for_signal().await;
root_token.cancel();
// Wait for all subsystems to finish their cleanup.
let _ = tokio::join!(http_handle, worker_handle, metrics_handle);
tracing::info!("all subsystems shut down cleanly");
}
ความสัมพันธ์แบบ Parent-Child (แม่-ลูก) ช่วยให้สัญญาณการปิดระบบสามารถส่งต่อกระจายลงไปตามลำดับชั้นได้อย่างเป็นระบบ ระบบย่อยแต่ละตัวจะคอยเฝ้าดู token.cancelled() ภายใน event loop ของตนเอง (ผ่าน select!) และจะเริ่มขั้นตอน cleanup ทันทีเมื่อสัญญาณถูกกระตุ้นขึ้น ส่วนฝั่ง parent ก็จะคอยจนกระทั่ง handle ของงานย่อยทั้งหมด resolve สมบูรณ์ ทำให้เรามั่นใจได้อย่างเต็มร้อยว่าจะไม่มีงานใดถูกทอดทิ้งไว้กลางทาง
เราจะมาเจาะลึกแพตเทิร์นนี้อย่างละเอียดในบท การปิดระบบอย่างนุ่มนวล ซึ่งเราจะมาประกอบลำดับขั้นตอนการปิดระบบอย่างเต็มรูปแบบสำหรับแอปพลิเคชันที่ใช้งานจริง
ข้อผิดพลาดที่พบบ่อย
ใช้ select! ทั้งที่จริงๆ ต้องการ join! คุณอาจเคยสงสัยว่าทำไมงานชิ้นที่สองถึงไม่เคยทำงานเสร็จสักที หากคุณต้องการรันสองงานควบคู่กันแล้วรอให้ทั้งคู่เสร็จสิ้น คุณต้องใช้ tokio::join! หรือ tokio::try_join! เพราะ select! จะคืนผลลัพธ์ทันทีที่งานแรกเสร็จ แล้วสั่ง drop งานที่เหลือทิ้งทั้งหมด ผมเคยเห็นความเข้าใจผิดตรงนี้ทำให้ข้อมูลหรืองานสูญหายมานับครั้งไม่ถ้วน
ลืมไปว่า select! ที่อยู่ใน loop ต้องให้ทุก branch ปลอดภัยต่อการยกเลิก ทุกครั้งที่ loop เริ่มต้นรอบใหม่ future ที่ยังค้างจากรอบก่อนหน้าจะถูก drop ทิ้ง หาก future ตัวใดตัวหนึ่งไม่ใช่ cancellation-safe ข้อมูลก็อาจสูญหายไปเงียบๆ ระหว่างรอบการทำงานได้ แพตเทิร์น Actor Model ที่เราได้ดูกันไปข้างต้นจะช่วยขจัดปัญหานี้ โดยการจำกัด branch ของ select! ให้มีเฉพาะ operation ที่ปลอดภัยต่อการยกเลิกเท่านั้น (เช่น การรับข้อมูลจาก channel, การนับของ timer หรือสัญญาณ cancellation)
ถือ MutexGuard ข้ามจุด await หากใช้ std::sync::Mutex การถือ guard ข้ามจุด .await อาจทำให้ runtime thread ทั้งเธรดถูกบล็อกสนิท ส่วนในกรณีของ tokio::sync::Mutex แม้จะปลอดภัยจากการบล็อกเธรด แต่ก็อาจทำให้เกิดการถือ lock ค้างไว้นานเกินไปหาก future ภายใน critical section นั้นใช้เวลาประมวลผลนาน ในทั้งสองกรณี ผมขอแนะนำให้พิจารณาใช้แพตเทิร์น Actor/Channel แทน นั่นคือส่งข้อความไปหา task ที่เป็นเจ้าของ state โดยตรง แทนที่จะพยายามแย่งกัน acquire lock บน shared state จากหลายๆ task
ไม่ยอมจัดการ branch else ใน select! หาก channel ทั้งหมดที่อยู่ใน select! ปิดตัวลง (ทุก recv() ทยอยคืนค่า None ออกมา) และไม่มีการระบุ branch else รองรับไว้ ตัวแมโคร select! จะเกิดอาการ panic ทันที ดังนั้นในโค้ด production ควรจัดการกรณี None อย่างรัดกุมรอบคอบเสมอ หรือตรวจสอบให้มั่นใจว่ามีอย่างน้อยหนึ่ง branch (เช่น cancellation token) ที่ไม่มีวันปิดตัวลง
tokio::pin! และเมื่อไหร่ที่คุณต้องใช้
Future บางประเภทจำเป็นต้องถูก pin เสียก่อนจึงจะสามารถนำไปใช้งานใน select! ได้ เนื่องจาก select! กำหนดเงื่อนไขไว้ว่า future ในแต่ละ branch จะต้อง implement เทรต Unpin หรือไม่ก็ต้องผ่านการ pin มาแล้ว คุณมักจะพบเจอกรณีนี้บ่อยที่สุดเมื่อมีการเก็บ future ไว้ในตัวแปรเพื่อนำมาใช้ซ้ำข้ามรอบการทำงานของ loop:
#![allow(unused)]
fn main() {
let sleep_future = tokio::time::sleep(Duration::from_secs(30));
tokio::pin!(sleep_future);
loop {
tokio::select! {
_ = &mut sleep_future => {
tracing::info!("timeout reached");
break;
}
msg = rx.recv() => {
// Process message. The sleep future continues
// from where it left off on the next iteration.
}
}
}
}
หากปราศจาก tokio::pin! คอมไพเลอร์ของ Rust จะปฏิเสธโค้ดชุดนี้ทันทีด้วยข้อผิดพลาดเกี่ยวกับ bound ของ Unpin หากคุณยังไม่เคยเจอ error นี้มาก่อน ก็ไม่ต้องกังวลไปครับ อีกไม่นานคุณจะได้พบกับมันอย่างแน่นอน การทำ pinning จะช่วยการันตีว่าตำแหน่งในหน่วยความจำของ future จะคงที่อยู่กับที่ข้ามจุด await ต่างๆ ซึ่งเป็นข้อกำหนดสำคัญของกลไกการ poll ภายในแมโคร select! นี่เป็นหนึ่งในเรื่องที่อาจชวนให้สับสนในตอนแรก แต่จะกลายเป็นเรื่องปกติที่เป็นธรรมชาติอย่างยิ่งเมื่อคุณได้เห็นและใช้งานแพตเทิร์นนี้ไปสักสองสามครั้ง
การส่งข้อความและแพตเทิร์นแชนเนล
เมื่อระบบเริ่มขยายใหญ่ขึ้น ย่อมถึงจุดที่ async task ต่างๆ จำเป็นต้องสื่อสารแลกเปลี่ยนข้อมูลระหว่างกัน และเมื่อเวลานั้นมาถึง โดยพื้นฐานแล้วคุณจะมี 2 ทางเลือกหลัก: นั่นคือการใช้ shared state ที่ปกป้องด้วย lock หรือการส่งข้อความผ่าน channel (Message Passing) แม้ทั้งสองวิธีจะมีจุดเด่นและกรณีการใช้งานที่เหมาะสมของตนเอง แต่จากประสบการณ์ของผม channel มักเป็นทางเลือกเริ่มต้น (default) ที่ดีกว่าสำหรับงานเว็บแอปพลิเคชันส่วนใหญ่ เพราะมันบังคับการประมวลผลตามลำดับอย่างเป็นธรรมชาติ ทำให้การถ่ายโอน ownership มีความชัดเจนตรงไปตรงมา และทำงานร่วมกับ tokio::select! ได้อย่างกลมกลืน
ในบทนี้ เราจะมาสำรวจ channel primitive ประเภทต่างๆ ที่ Tokio จัดเตรียมไว้ให้, รูปแบบสถาปัตยกรรมที่ต่อยอดจาก channel เหล่านี้ ตลอดจนการประกอบพวกมันเข้าด้วยกันเป็น Actor/Service-Worker Model ซึ่งผมพบว่าเป็นรากฐานสำคัญที่ค้ำจุนแอปพลิเคชัน concurrent Rust ที่มีโครงสร้างดีแทบทุกตัว
ชนิดแชนเนลสามแบบ
Tokio มอบ channel มาให้เรา 3 ชนิดหลักๆ ซึ่งแต่ละชนิดถูกออกแบบมาเพื่อรูปแบบการสื่อสาร (communication shape) ที่แตกต่างกัน มาดูกันว่าแต่ละชนิดทำงานอย่างไร และควรเลือกหยิบมาใช้งานในสถานการณ์ใด
mpsc: ผู้ผลิตหลายราย ผู้บริโภครายเดียว
mpsc (Multi-Producer, Single-Consumer) ถือเป็นม้าศึกหลักของงานส่วนใหญ่ ทาสก์หลายๆ ตัวสามารถส่งข้อความเข้ามาพร้อมกันได้ ขณะที่มีทาสก์ฝั่งรับเพียงตัวเดียวคอยดึงข้อความไปประมวลผลตามลำดับ หากคุณกำลังสร้างคิวคำสั่ง (command queue), ระบบกระจายงาน (work dispatching) หรือแพตเทิร์นการประสานงานใดๆ ก็ตาม นี่คือจุดเริ่มต้นที่คุณมักจะได้ใช้เสมอ
#![allow(unused)]
fn main() {
use tokio::sync::mpsc;
let (tx, mut rx) = mpsc::channel::<Command>(32); // bounded, capacity 32
// Senders can be cloned and shared across tasks.
let tx2 = tx.clone();
// The receiver processes commands one at a time.
while let Some(cmd) = rx.recv().await {
process(cmd).await;
}
}
จุดสำคัญยิ่งในการนำไปใช้บน production คือการเลือกระหว่าง bounded channel หรือ unbounded channel โดย Bounded Channel (สร้างด้วยคำสั่ง mpsc::channel(capacity)) จะมอบกลไก Backpressure ให้โดยอัตโนมัติ: กล่าวคือ เมื่อ channel เต็ม คำสั่ง send().await จะสั่งพัก (block/wait) ทาสก์ฝั่งผู้ส่งไว้ชั่วคราวจนกว่าทาสก์ฝั่งผู้รับจะดึงข้อความออกไปประมวลผลทัน กลไกนี้ช่วยป้องกันไม่ให้ producer ที่ทำงานเร็วเกินไปส่งข้อมูลมาท่วม consumer ที่ประมวลผลช้าจนคิวล้น ในทางตรงกันข้าม Unbounded Channel (สร้างด้วย mpsc::unbounded_channel()) จะไม่มีวันบล็อกผู้ส่งเลย แต่มันอาจสูบกลืนหน่วยความจำของระบบไปอย่างไร้ขีดจำกัดหากฝั่งผู้รับทำงานตามไม่ทัน ผมจึงแนะนำให้ใช้ bounded channel เป็นค่าเริ่มต้นเสมอ และเลือกใช้ unbounded เฉพาะเมื่อคุณมีเหตุผลความจำเป็นที่ชัดเจนเท่านั้น
oneshot: คำขอ-การตอบกลับแบบครั้งเดียว
คุณจะเลือกใช้ oneshot เมื่อต้องการรับคำตอบเพียงครั้งเดียวต่อหนึ่งคำขอ (Request-Response) โดยรูปแบบการทำงานจะเป็นดังนี้: คุณสร้าง oneshot channel ขึ้นมาชุดหนึ่ง ส่งครึ่งที่เป็น Sender แนบไปพร้อมกับคำสั่ง และรอรับผลลัพธ์จากฝั่ง Receiver
#![allow(unused)]
fn main() {
use tokio::sync::oneshot;
enum Command {
Get {
key: String,
reply: oneshot::Sender<Option<String>>,
},
Set {
key: String,
value: String,
},
}
// Caller side: send a command and wait for the response.
async fn get_value(tx: &mpsc::Sender<Command>, key: String) -> Option<String> {
let (reply_tx, reply_rx) = oneshot::channel();
tx.send(Command::Get { key, reply: reply_tx }).await.ok()?;
reply_rx.await.ok()?
}
}
นี่คือวิธีการสร้างการสื่อสารแบบ Request-Response ซ้อนทับลงบน command channel แบบ mpsc ฝั่งผู้เรียกจะสร้างคู่ oneshot ขึ้นมา นำ Sender บรรจุเข้าไปใน command แล้วสั่ง .await รอผลลัพธ์จาก Receiver ในขณะที่ทาสก์ผู้ประมวลผลอีกฝั่งจะรับคำสั่งเข้ามา ทำงานจนเสร็จ แล้วส่งผลลัพธ์ย้อนกลับมาทาง oneshot::Sender ในตอนแรกอาจดูเหมือนมีขั้นตอนหลายสเต็ป แต่คุณจะพบว่ามันกลายเป็นเรื่องปกติที่คุ้นเคยได้อย่างรวดเร็ว
broadcast: การกระจายหนึ่งต่อหลาย
Channel แบบ broadcast เปิดโอกาสให้ผู้ส่งสามารถถ่ายทอดทุกข้อความไปยัง receiver ที่กำลังทำงานอยู่ทั้งหมดได้ในคราวเดียว โดย receiver แต่ละตัวจะได้รับสำเนาของข้อความทุกชิ้นที่ถูกส่งออกมาหลังจากที่ตนเองกดสมัครรับข้อมูล (subscribe)
#![allow(unused)]
fn main() {
use tokio::sync::broadcast;
let (tx, _rx) = broadcast::channel::<Event>(100);
// Each subscriber gets a receiver by calling subscribe().
let mut rx1 = tx.subscribe();
let mut rx2 = tx.subscribe();
// Both rx1 and rx2 will receive this event.
tx.send(Event::CertificateReady { id: cert_id })?;
}
Broadcast channel เหมาะอย่างยิ่งสำหรับการกระจายอีเวนต์ (Event Distribution), การส่งสัญญาณเคลียร์แคช (Cache Invalidation) หรือการแจ้งเตือนการเปลี่ยนแปลง configuration ไปยัง consumer หลายๆ ตัวพร้อมกัน ทว่ามีจุดสำคัญที่ต้องพึงระวัง: หาก receiver ตัวใดประมวลผลช้าจนตามไม่ทัน มันจะเจอกับข้อผิดพลาด RecvError::Lagged(n) ซึ่งจะระบุจำนวนข้อความที่ตัวมันหลุดตกหล่นไป คุณจึงต้องมั่นใจเสมอว่า consumer ของคุณได้เขียนโค้ดรองรับกรณีนี้ไว้อย่างรัดกุม
แพตเทิร์นแอ็กเตอร์/เซอร์วิสเวิร์กเกอร์
มาถึงแพตเทิร์นที่ผมรู้สึกตื่นเต้นและชื่นชอบมากที่สุด Actor Model (หรือ Service-Worker) คือผลลัพธ์ที่ทรงคุณค่าที่สุดที่ channel ช่วยเปิดทางให้ และเมื่อคุณเริ่มมองเห็นประโยชน์ของมันแล้ว คุณจะอยากนำมันไปปรับใช้ในทุกๆ ที่ แนวคิดของมันเรียบง่ายมาก: Actor คือ task ตัวหนึ่งที่เป็นเจ้าของ state บางอย่างเพียงผู้เดียว ทำหน้าที่คอยรับคำสั่งผ่าน channel และประมวลผลทีละคำสั่งตามลำดับ ในขณะที่โค้ดภายนอกจะสื่อสารกับ actor ผ่าน client struct ที่ห่อหุ้ม channel sender ไว้ข้างใน และเปิดเผย async API ที่มี type ชัดเจนสวยงามให้เรียกใช้งาน
มาดูตัวอย่างที่สมบูรณ์ของ Cache Actor แบบเรียบง่ายกันครับ:
#![allow(unused)]
fn main() {
use std::collections::HashMap;
use tokio::sync::{mpsc, oneshot};
// The commands the actor understands.
enum CacheCommand {
Get {
key: String,
reply: oneshot::Sender<Option<String>>,
},
Set {
key: String,
value: String,
},
Invalidate {
key: String,
},
}
// The client that external code uses. It hides the channel details.
#[derive(Clone)]
pub struct CacheClient {
sender: mpsc::Sender<CacheCommand>,
}
impl CacheClient {
pub async fn get(&self, key: &str) -> Option<String> {
let (tx, rx) = oneshot::channel();
self.sender
.send(CacheCommand::Get {
key: key.to_string(),
reply: tx,
})
.await
.ok()?;
rx.await.ok()?
}
pub async fn set(&self, key: String, value: String) {
let _ = self
.sender
.send(CacheCommand::Set { key, value })
.await;
}
pub async fn invalidate(&self, key: &str) {
let _ = self
.sender
.send(CacheCommand::Invalidate {
key: key.to_string(),
})
.await;
}
}
// Spawn the actor and return the client.
pub fn spawn_cache(shutdown: CancellationToken) -> CacheClient {
let (tx, rx) = mpsc::channel(64);
tokio::spawn(run_cache_actor(rx, shutdown));
CacheClient { sender: tx }
}
async fn run_cache_actor(
mut commands: mpsc::Receiver<CacheCommand>,
shutdown: CancellationToken,
) {
let mut store: HashMap<String, String> = HashMap::new();
loop {
let cmd = tokio::select! {
cmd = commands.recv() => match cmd {
Some(c) => c,
None => return, // All clients dropped.
},
_ = shutdown.cancelled() => return,
};
match cmd {
CacheCommand::Get { key, reply } => {
let _ = reply.send(store.get(&key).cloned());
}
CacheCommand::Set { key, value } => {
store.insert(key, value);
}
CacheCommand::Invalidate { key } => {
store.remove(&key);
}
}
}
}
}
แล้วเหตุใดแพตเทิร์นนี้จึงเข้ากับโค้ดระดับ production ได้อย่างเป็นธรรมชาตินัก? ให้ผมสรุปข้อดีหลักๆ ที่ทำให้มันทรงพลังขนาดนี้:
ไม่ต้องใช้ Lock เลย (No Locking) ตัว HashMap ถูกถือครองกรรมสิทธิ์โดย actor task แต่เพียงผู้เดียว ไม่ต้องมี Mutex, ไม่ต้องมี RwLock และไม่มีปัญหา thread contention เกิดขึ้น เพราะ mpsc channel ทำหน้าที่เรียงคิวการเข้าถึงข้อมูลให้เราโดยอัตโนมัติตามธรรมชาติ
ทนทานต่อการยกเลิก (Cancellation Resilient) คำสั่งแต่ละคำสั่งจะได้รับการประมวลผลจนเสร็จสิ้นสมบูรณ์ก่อนที่จะวนกลับไปที่ select! รอบถัดไป จึงไม่มีความเสี่ยงที่ future จะถูก drop ทิ้งไปกึ่งกลางจังหวะที่มีการแก้ไข state ซึ่งเป็นบั๊กลึกที่มักตามมาหลอกหลอนในแนวทางอื่นๆ
ทดสอบได้ง่าย (Testable) คุณสามารถเขียนเทสต์ทดสอบ actor ได้อย่างตรงไปตรงมา เพียงแค่สร้าง channel, ยิงคำสั่งเข้าไป แล้ว assert ตรวจสอบผลลัพธ์จาก response ไม่ต้องมานั่งกังวลเรื่อง timing หรือ race condition ในการรันพร้อมกัน ซึ่งช่วยประหยัดแรงไปได้มหาศาล
ประกอบเข้ากับระบบได้ลงตัว (Composable) ตัว CacheClient สามารถบรรจุอยู่ใน AppState และถูกดึงออกมาผ่าน extractor ใน Axum handler ได้เหมือนกับ shared dependency ทั่วไป เพราะมัน implement ทั้ง Clone และ Send ไว้อย่างครบถ้วนตามที่ Axum ต้องการ
เมื่อไหร่ควรใช้แชนเนลเทียบกับสถานะที่ใช้ร่วมกัน
คุณอาจสงสัยว่าจังหวะไหนควรเลือกใช้ channel และจังหวะไหนควรครอบ Mutex ทับลงบน state ไปตรงๆ นี่คือหลักคิดที่ผมใช้ในการตัดสินใจ:
Channel และ Actor Model เป็นเครื่องมือที่เหมาะสมอย่างยิ่งเมื่อ:
- State นั้นจำเป็นต้องได้รับการประมวลผลตามลำดับก่อนหลังอย่างเคร่งครัด (คำสั่งต้องไม่แทรกแซงกัน)
- คุณต้องการห่อหุ้ม (encapsulate) รายละเอียดของ state ไว้เบื้องหลัง async API
- รูปแบบการเข้าถึงประกอบด้วยทั้งการอ่านและการเขียนที่จำเป็นต้องประสานงานกันอย่างใกล้ชิด
- คุณมีการใช้งาน
tokio::select!เพื่อทำ multiplex ระหว่างแหล่ง event หลายๆ แหล่งอยู่แล้ว
ในขณะที่ Shared State (Arc<RwLock<T>>, Arc<DashMap<K, V>>) เป็นเครื่องมือที่เหมาะสมเมื่อ:
- รูปแบบการเข้าถึงส่วนใหญ่เป็นการอ่าน (Read-heavy) และมีการเขียนข้อมูลเพียงนานๆ ครั้ง
- คุณต้องการเปิดให้ task จำนวนมากสามารถอ่านข้อมูลพร้อมๆ กันได้โดยไม่ต้องมาต่อคิวรอรับส่งข้อความ
- โครงสร้างของ state เรียบง่ายพอที่การใช้ lock จะไม่ก่อให้เกิดความซับซ้อนหรือ deadlock
- คุณไม่จำเป็นต้องประสานการทำงานของ state ร่วมกับ event source อื่นๆ ภายในลูป
select!
และข้อคิดสุดท้ายก่อนจบบทนี้: สำหรับงานคอนฟิกูเรชันของแอปพลิเคชัน channel แบบ watch ก็นับเป็นอีกเครื่องมือที่คุ้มค่าแก่การเรียนรู้ โดยมันจะคอยเก็บค่าข้อมูลไว้เพียงค่าเดียวเพื่อให้ receiver กี่ตัวก็ได้เข้ามาสังเกตการณ์ และฝั่ง receiver จะมองเห็นเฉพาะค่าที่เป็นปัจจุบันล่าสุดเสมอ สิ่งนี้มีประโยชน์อย่างยิ่งสำหรับการทำ dynamic configuration reload ในตอนรันไทม์ หรือการตรวจสอบสถานะสุขภาพ (health status) ที่หลายๆ ทาสก์ต้องคอยตรวจเช็กอยู่ตลอดเวลา ซึ่งเราจะได้เห็นการประสานงานในลักษณะนี้เพิ่มเติมในบทถัดๆ ไปครับ
การปิดระบบอย่างนุ่มนวลและการจัดการไลฟ์ไซเคิล
ในบท การดีพลอยต์ เราได้ดูวิธีปิดเซิร์ฟเวอร์ Axum ตัวเดียวอย่างหมดจดเมื่อได้รับสัญญาณ SIGTERM กันไปแล้ว นั่นเป็นเพียงกรณีที่เรียบง่ายที่สุด แต่ในโลกความเป็นจริง แอปพลิเคชันบน production มักไม่ได้มีแค่เซิร์ฟเวอร์ HTTP เพียงอย่างเดียว คุณมักจะมี background worker ที่กำลังประมวลผลงาน, การเชื่อมต่อ WebSocket ที่เปิดค้างไว้เพื่อระบายข้อความ, ตัวรายงานเมตริกที่กำลังฟลัชข้อมูล, และพูลฐานข้อมูลที่ต้องปิดการทำงานอย่างเป็นระเบียบ หากซับซิสเต็มใดซับซิสเต็มหนึ่งเหล่านี้ยังคงทำงานค้างอยู่ตอนที่โพรเซสยุติลง คุณอาจต้องเจอกับปัญหาข้อมูลสูญหาย การเชื่อมต่อขาดกะทันหัน หรือสถานะข้อมูลที่ไม่สอดคล้องกัน
ในบทนี้ เราจะมาดูวิธีประสานงานการปิดระบบ (graceful shutdown) ข้ามหลายซับซิสเต็มที่ทำงานพร้อมกัน เพื่อให้แต่ละส่วนสามารถเคลียร์งานที่ค้างอยู่ (in-flight work) ให้เสร็จสิ้นตามลำดับขั้นตอนที่ถูกต้อง ก่อนที่โพรเซสจะจบการทำงานลง
CancellationToken ในฐานะพรามิทีฟกลางของการประสานงาน
หากคุณเคยพยายามประสานงานการปิดระบบมาก่อน คุณอาจจะเคยหยิบแชนเนล oneshot หรือแฟล็ก Arc<AtomicBool> มาใช้งาน วิธีการเหล่านั้นใช้งานได้จริง แต่โค้ดจะเริ่มยุ่งเหยิงอย่างรวดเร็วทันทีที่คุณมีซับซิสเต็มมากกว่าสองตัวขึ้นไป tokio_util::sync::CancellationToken จึงเหมาะสมกับงานนี้มากกว่ามาก โดยมีฟิวเจอร์ cancelled() ที่จะ resolve เมื่อโทเคนถูกยกเลิก และยังรองรับความสัมพันธ์แบบพ่อแม่-ลูก (parent-child relationship) ซึ่งการยกเลิกโทเคนพ่อแม่จะส่งผลให้โทเคนลูกทั้งหมดถูกยกเลิกตามไปด้วยโดยอัตโนมัติ
#![allow(unused)]
fn main() {
use tokio_util::sync::CancellationToken;
// Create a root token for the entire application.
let root_token = CancellationToken::new();
// Each subsystem gets a child token.
let http_token = root_token.child_token();
let worker_token = root_token.child_token();
let telemetry_token = root_token.child_token();
}
เมื่อสัญญาณปิดระบบมาถึง เราจะสั่งยกเลิก root token จากนั้นทุกซับซิสเต็มจะรับรู้การแจ้งเตือนผ่าน child token ของตนเอง ตัวโทเคนนี้ออกแบบมาเพื่อรองรับการยกเลิกโดยเฉพาะ และสามารถประกอบเข้ากับ tokio::select! ได้อย่างเป็นธรรมชาติ ช่วยให้โครงสร้างโค้ดอ่านและทำความเข้าใจได้ง่ายกว่าทางเลือกอื่นอย่างเห็นได้ชัด
แอปพลิเคชันหลายซับซิสเต็ม
มาดูตัวอย่างฟังก์ชัน main ในสถานการณ์จริงที่เริ่มทำงาน 3 ซับซิสเต็มพร้อมกัน และจัดการประสานงานการปิดระบบของแต่ละตัว:
use tokio_util::sync::CancellationToken;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let config = Config::from_env()?;
init_tracing(&config.log_level);
let pool = create_pool(config.database_url.expose_secret()).await?;
sqlx::migrate!("./migrations").run(&pool).await?;
let root_token = CancellationToken::new();
// Spawn the HTTP server.
let http_token = root_token.child_token();
let http_handle = tokio::spawn({
let pool = pool.clone();
let config = config.clone();
async move {
let app = build_router(config, pool);
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000")
.await
.expect("failed to bind");
axum::serve(listener, app)
.with_graceful_shutdown(http_token.cancelled_owned())
.await
.expect("server error");
}
});
// Spawn a background job worker.
let worker_token = root_token.child_token();
let worker_handle = tokio::spawn({
let pool = pool.clone();
async move {
run_job_worker(pool, worker_token).await;
}
});
// Spawn a metrics reporter.
let metrics_token = root_token.child_token();
let metrics_handle = tokio::spawn(async move {
run_metrics_reporter(metrics_token).await;
});
// Wait for the shutdown signal, then cancel everything.
wait_for_signal().await;
tracing::info!("shutdown signal received");
root_token.cancel();
// Wait for all subsystems to finish.
let _ = tokio::join!(http_handle, worker_handle, metrics_handle);
// Close the database pool after all subsystems have stopped.
pool.close().await;
tracing::info!("shutdown complete");
Ok(())
}
จุดสำคัญที่ต้องสังเกตตรงนี้คือ พูลฐานข้อมูลจะถูกปิด หลังจาก ที่ซับซิสเต็มทั้งหมดหยุดทำงานลงแล้วเท่านั้น เหตุผลคืออะไร? เพราะในระหว่างช่วงระบายงาน (drain phase) ซับซิสเต็มเหล่านั้นอาจยังจำเป็นต้องรันคิวรีที่ค้างอยู่ หากคุณปิดพูลไปก่อน คิวรีเหล่านั้นก็จะล้มเหลวทันที นี่คือหัวใจสำคัญของ “การรื้อถอนแบบมีลำดับ” (ordered teardown) ซึ่งเป็นเรื่องที่คุ้มค่าแก่การทำความเข้าใจอย่างละเอียด
การรื้อถอนแบบมีลำดับ
กฎทั่วไปคือ: จงคืนรีซอร์สในลำดับย้อนกลับของสายดีเพนเดนซี (dependency chain) หากแฮนด์เลอร์ HTTP ของเราต้องพึ่งพาพูลฐานข้อมูล และตัวรายงานเมตริกต้องพึ่งพาเซิร์ฟเวอร์ HTTP ที่ยังคงเปิดอยู่ ลำดับการรื้อถอนที่ถูกต้องควรเป็นดังนี้:
- หยุดรับการเชื่อมต่อ HTTP ใหม่ (Axum จัดการเรื่องนี้ให้เมื่อ shutdown future ทำงานสำเร็จ/resolve)
- ระบายคำขอ HTTP ที่ค้างอยู่ (in-flight requests) ให้เสร็จสิ้นทั้งหมด
- หยุด background worker (ปล่อยให้มันทำงานชิ้นปัจจุบันให้เสร็จ แล้วค่อยออกจากลูป)
- ฟลัชตัวรายงานเมตริก (ส่งข้อมูลทั้งหมดที่ค้างอยู่ในบัฟเฟอร์ออกไปให้ครบ แล้วค่อยออกจากลูป)
- ปิดพูลฐานข้อมูล
ในทางปฏิบัติ ขั้นตอนที่ 2 ถึง 4 มักจะเกิดขึ้นไปพร้อมๆ กัน (ผ่าน tokio::join!) เนื่องจากแต่ละซับซิสเต็มต่างจัดการระบายงานของตนเองอย่างเป็นอิสระ สิ่งสำคัญอย่างเดียวที่เราต้องควบคุมให้รัดกุมคือ รีซอร์สส่วนกลางอย่าง connection pool จะต้องไม่ถูกปิดเด็ดขาดจนกว่าผู้ใช้งาน (consumer) ทุกตัวจะหยุดทำงานลงอย่างสมบูรณ์
การจัดการพูลทาสก์แบบไดนามิกด้วย FuturesUnordered
ซับซิสเต็มบางประเภทไม่ได้มีจำนวนทาสก์ที่คงที่ตายตัว เช่น คุณอาจมี 1 ทาสก์ต่อ 1 การเชื่อมต่อ WebSocket ที่เปิดอยู่, 1 ทาสก์ต่องานเบื้องหลังที่กำลังประมวลผลอยู่, หรือ 1 ทาสก์ต่อ gRPC สตรีมที่กำลังเชื่อมต่อ ซึ่งจำนวนเหล่านี้มีความผันผวนตลอดเวลา สำหรับสถานการณ์เช่นนี้ FuturesUnordered เป็นเครื่องมือที่ยอดเยี่ยมมาก เพราะมันทำหน้าที่เป็นสตรีมของผลลัพธ์ทาสก์ที่ทำงานเสร็จแล้ว ทำให้คุณสามารถรอระบายทาสก์ทั้งหมดได้อย่างเป็นระเบียบในระหว่างกระบวนการปิดระบบ
#![allow(unused)]
fn main() {
use futures::stream::FuturesUnordered;
use futures::StreamExt;
async fn run_connection_manager(
mut new_connections: mpsc::Receiver<TcpStream>,
shutdown: CancellationToken,
) {
let mut active_tasks = FuturesUnordered::new();
loop {
tokio::select! {
// Accept new connections while running.
conn = new_connections.recv() => {
if let Some(stream) = conn {
let token = shutdown.child_token();
active_tasks.push(tokio::spawn(
handle_connection(stream, token)
));
}
}
// Reap completed tasks to free resources.
Some(result) = active_tasks.next() => {
if let Err(e) = result {
tracing::error!(error = ?e, "connection task panicked");
}
}
// On shutdown, stop accepting new connections
// and drain the remaining tasks.
_ = shutdown.cancelled() => {
tracing::info!(
active = active_tasks.len(),
"shutting down, draining active connections"
);
break;
}
}
}
// Drain: wait for all active connections to finish.
while let Some(result) = active_tasks.next().await {
if let Err(e) = result {
tracing::error!(error = ?e, "connection task panicked during drain");
}
}
tracing::info!("all connections drained");
}
}
ผมอยากเน้นย้ำถึงโครงสร้างแบบสองเฟส (two-phase structure) ตรงนี้เป็นพิเศษ เพราะนี่คือแพตเทิร์นที่คุณจะได้นำไปใช้บ่อยมาก โดยระหว่างการทำงานตามปกติ ลูป select! จะคอยรับการเชื่อมต่อใหม่ เคลียร์ทาสก์ที่ทำงานเสร็จสิ้นแล้ว และคอยเฝ้าฟังสัญญาณปิดระบบ และเมื่อการปิดระบบถูกกระตุ้นขึ้น ลูปจะหยุดทำงาน (break) ทันทีเพื่อก้าวเข้าสู่เฟสการระบายงาน (drain phase) ซึ่งก็คือการวนลูปรอให้ทาสก์ที่ยังค้างอยู่ทั้งหมดทำงานจนเสร็จสิ้น ทาสก์ของการเชื่อมต่อแต่ละตัวจะได้รับ child cancellation token ส่งต่อเข้าไป เพื่อเปิดโอกาสให้มันได้ทำความสะอาดรีซอร์สของตนเอง (เช่น ฟลัชบัฟเฟอร์ หรือส่ง close frame) ให้เรียบร้อยก่อนที่จะจบการทำงาน
การล้างการเชื่อมต่อ
สำหรับการเชื่อมต่อที่มีอายุยืนยาว (long-lived connections) เช่น WebSocket ลำดับการล้างข้อมูลภายในแต่ละทาสก์มีความสำคัญมากกว่าที่คุณคาดคิด โปรเจกต์ mozilla-services/autopush-rs ถือเป็นตัวอย่างที่ดีเยี่ยมในการจัดการเรื่องนี้อย่างรัดกุม: เมื่อการเชื่อมต่อ WebSocket ต้องปิดตัวลง มันจะตัดการเชื่อมต่อออกจาก client registry, ทำการระบายการแจ้งเตือนจากฝั่งเซิร์ฟเวอร์ที่ยังค้างอยู่ผ่าน on_server_notif_shutdown(), เรียก client.shutdown() พร้อมแนบรายละเอียดข้อผิดพลาด, และปิดเซสชันด้วยรหัสเหตุผลการปิด WebSocket (close reason) ที่เหมาะสม การเก็บกวาดตามลำดับย้อนกลับเช่นนี้ช่วยรับประกันได้ว่าจะไม่มี notification ใดๆ ตกหล่นสูญหายไปในช่องว่างระหว่างการตัดสินใจปิดระบบกับการปิดการเชื่อมต่อจริง
หลักการที่ผมอยากแนะนำให้ยึดถือคือ: เมื่อการเชื่อมต่อหรือทาสก์ใดๆ จำเป็นต้องปิดตัวลง ให้สะสางงานขาออกที่ค้างอยู่ทั้งหมดให้เสร็จสิ้นเสียก่อน (ฟลัช write buffer, ส่งการแจ้งเตือนที่ค้างอยู่, ยืนยันรับทราบข้อความที่ยังค้างอยู่) ก่อนที่จะปิดทรานสปอร์ต (underlying transport) ด้านล่าง แม้การไล่เรียงรายละเอียดขั้นตอนเหล่านี้อาจดูจุกจิก แต่จากประสบการณ์จริง บั๊กที่เกิดจากการละเลยขั้นตอนการทำความสะอาดนั้นตามแก้ได้ยากกว่าการเขียนโค้ด cleanup เหล่านี้อย่างเทียบไม่ติด
การทดสอบพฤติกรรมการปิดระบบ
คุณอาจสงสัยว่าจะทดสอบการทำงานทั้งหมดนี้ได้อย่างไร โค้ดส่วนการปิดระบบมักเป็นเรื่องที่ทดสอบได้ยาก เพราะมักจะขึ้นอยู่กับจังหวะเวลา (timing), การทำงานพร้อมกัน (concurrency), และ edge case ที่มักจะโผล่มาเฉพาะเมื่อเกิดลำดับเหตุการณ์แบบจำเพาะเจาะจงเท่านั้น สิ่งที่ผมพบว่าได้ผลดีมากคือการใช้ tokio::time::timeout เพื่อตรวจสอบและรับประกันว่าขั้นตอนการปิดระบบทั้งหมดจะเสร็จสิ้นภายในระยะเวลาที่กำหนดไว้อย่างสมเหตุสมผล:
#![allow(unused)]
fn main() {
#[tokio::test]
async fn shutdown_completes_within_timeout() {
let token = CancellationToken::new();
let handle = tokio::spawn(run_my_subsystem(token.clone()));
// Give it a moment to start up.
tokio::time::sleep(Duration::from_millis(100)).await;
// Trigger shutdown.
token.cancel();
// It should finish within 5 seconds.
let result = tokio::time::timeout(
Duration::from_secs(5),
handle,
).await;
assert!(result.is_ok(), "shutdown did not complete within timeout");
}
}
หากการทดสอบนี้เกิดอาการค้าง (hang) นั่นเป็นสัญญาณชัดเจนว่าเส้นทางการปิดระบบของคุณมีบั๊กแฝงอยู่ อาจมีส่วนใดส่วนหนึ่งกำลังรอรับข้อความจากแชนเนลที่จะไม่มีวันส่งมาอีก หรือมีทาสก์บางตัวที่ไม่ได้ตรวจสอบ cancellation token ของตัวเอง แม้จะเป็นเพียงแบบทดสอบสั้นๆ เรียบง่าย แต่กลับช่วยดักจับปัญหาคอขาดบาดตายในระบบจริงได้อย่างยอดเยี่ยม และเมื่อคุณมีเทสต์นี้คอยกำกับไว้ คุณก็จะปรับแก้ตรรกะการปิดระบบในอนาคตได้อย่างมั่นใจยิ่งขึ้น
งานเบื้องหลังและการจัดการทาสก์
หากคุณเคยสร้างเว็บแอปพลิเคชันที่จริงจังกว่าโปรเจกต์ทดลองเล่นทั่วไป คุณคงเคยเผชิญกับสถานการณ์นี้: งานบางอย่างไม่ควรถูกผูกไว้ในวงรอบคำขอ-การตอบกลับ (request-response cycle) เลย ไม่ว่าจะเป็นการส่งอีเมลยืนยันตัวตน, การประมวลผลไฟล์ที่อัปโหลด, การสร้างรายงานขนาดใหญ่, การลองส่ง webhook ที่เคยล้มเหลวซ้ำ, หรือการเก็บกวาดเซสชันที่หมดอายุ ทั้งหมดนี้ล้วนทำให้ HTTP response ของเราตอบสนองช้าลงอย่างมากหากเราพยายามทำทุกอย่างแบบอินไลน์ (inline) ในบทนี้ เราจะมาเจาะลึกแพตเทิร์นสำหรับการจัดการงานเบื้องหลัง (background jobs) ในแอปพลิเคชันที่ใช้ Tokio ตั้งแต่ทาสก์แบบยิงแล้วลืม (fire-and-forget) ขั้นพื้นฐาน ไปจนถึงระบบคิวงานแบบถาวร (persistent job queue) ที่รองรับการลองใหม่อัตโนมัติ (retry)
การสร้างทาสก์ภายในกระบวนการ
วิธีที่ง่ายที่สุดในการรันงานเบื้องหลังคือการใช้ tokio::spawn ซึ่งจะสร้างทาสก์แบบแอซิงก์ตัวใหม่ที่ทำงานอย่างเป็นอิสระจากโค้ดตัวต้นทางที่สร้างมันขึ้นมา โดยโค้ดต้นทางจะไม่ต้องหยุดรอให้ทาสก์ใหม่ทำงานจนเสร็จ เว้นแต่คุณจะระบุ .await บน JoinHandle ที่ได้รับกลับมาอย่างชัดเจน
#![allow(unused)]
fn main() {
async fn create_user(
State(state): State<AppState>,
ValidatedJson(payload): ValidatedJson<CreateUserDto>,
) -> AppResult<(StatusCode, Json<UserResponse>)> {
let user = state.user_service.register(payload).await?;
// Send the welcome email in the background.
// The HTTP response does not wait for this to finish.
let email_client = state.email_client.clone();
let email = user.email().clone();
tokio::spawn(async move {
if let Err(e) = email_client.send_welcome(&email).await {
tracing::error!(error = ?e, "failed to send welcome email");
}
});
Ok((StatusCode::CREATED, Json(user.into())))
}
}
วิธีนี้ตอบโจทย์ได้เป็นอย่างดีสำหรับผลข้างเคียง (side effects) ที่ไม่ได้สำคัญถึงขั้นวิกฤต ซึ่งความผิดพลาดเป็นครั้งคราวเป็นสิ่งที่ยอมรับได้ (เช่น ข้อมูลผู้ใช้ยังคงถูกบันทึกลงฐานข้อมูลสำเร็จ แม้การส่งอีเมลต้อนรับจะล้มเหลวก็ตาม) ทว่ามีข้อควรระวังสำคัญบางประการที่คุณจำเป็นต้องรู้ไว้:
ประการแรก หากทาสก์ที่ถูก spawn เกิดอาการแพนิก (panic) ตัวแพนิกนั้นจะถูกดักจับและเก็บไว้ใน JoinHandle หากคุณไม่ได้ .await บนแฮนเดิลดังกล่าว แพนิกนั้นจะถูกกลืนหายไปอย่างเงียบๆ ซึ่งอาจทำให้การดีบักปัญหาบน production ชวนสับสนอย่างมาก คุณจึงควร await แฮนเดิล หรือหันไปใช้ JoinSet ที่สามารถรายงานข้อผิดพลาดกลับมาให้คุณได้
แต่ปัญหาที่ใหญ่หลวงกว่านั้นคือ: หากโพรเซสของคุณถูกรีสตาร์ท (เช่น จากการดีพลอยต์เวอร์ชันใหม่, เซิร์ฟเวอร์แครช, หรือถูกระบบปฏิบัติการทำ OOM kill) ทาสก์ที่ spawn ไว้และกำลังทำงานอยู่จะสูญหายไปทันทีโดยไร้ร่องรอย ไม่มีการลองใหม่ (retry), ไม่มีความคงทนของข้อมูล (persistence), และไม่มีการรับประกันใดๆ ว่างานนั้นจะทำเสร็จสมบูรณ์ ดังนั้นสำหรับงานที่ จำเป็นต้อง สำเร็จให้ได้ในท้ายที่สุด คุณจะต้องพึ่งพาระบบคิวงานแบบถาวร ซึ่งเราจะมาคุยกันในช่วงท้ายของบทนี้
JoinSet สำหรับจัดการกลุ่มทาสก์
เมื่อคุณมีชุดของทาสก์ที่ทราบจำนวนแน่นอนและทุกตัวจำเป็นต้องทำงานให้เสร็จสิ้น tokio::task::JoinSet จะช่วยมอบโครงสร้างที่เป็นระเบียบเรียบร้อยในการ spawn ทาสก์เหล่านั้นและรวบรวมผลลัพธ์กลับมา:
#![allow(unused)]
fn main() {
use tokio::task::JoinSet;
async fn process_batch(items: Vec<Item>, pool: PgPool) -> anyhow::Result<()> {
let mut set = JoinSet::new();
for item in items {
let pool = pool.clone();
set.spawn(async move {
process_item(&pool, &item).await
});
}
// Wait for all tasks to complete.
while let Some(result) = set.join_next().await {
match result {
Ok(Ok(())) => {}
Ok(Err(e)) => tracing::error!(error = ?e, "item processing failed"),
Err(e) => tracing::error!(error = ?e, "task panicked"),
}
}
Ok(())
}
}
JoinSet ยังมีประโยชน์อย่างยิ่งสำหรับการจำกัดอัตราการทำงานพร้อมกัน (concurrency limiting) โดยคุณสามารถตรวจสอบ set.len() ก่อนที่จะ spawn ทาสก์ใหม่ และหยุดรอให้มีทาสก์ตัวใดตัวหนึ่งเสร็จสิ้นก่อนได้หากความจุเต็มแล้ว ยิ่งไปกว่านั้น เมื่อ JoinSet ถูกทำลาย (dropped) ทาสก์ทั้งหมดที่อยู่ข้างในจะถูกยกเลิก (abort) โดยอัตโนมัติ ซึ่งเหมาะอย่างยิ่งกับสถานการณ์การปิดระบบ (graceful shutdown) ที่คุณต้องการยกเลิกงานที่ยังค้างอยู่ทั้งหมดอย่างเป็นระเบียบ
งานแบบเป็นคาบ
แอปพลิเคชันจำนวนมากจำเป็นต้องมีงานเบื้องหลังที่รันซ้ำตามช่วงเวลา (recurring tasks) เช่น การเคลียร์แคชทุกๆ 5 นาที, การส่งรายงานเมตริกทุกๆ 30 วินาที, หรือการส่งสัญญาณ heartbeat ตรวจสอบสุขภาพระบบทุกๆ 10 วินาที เป็นต้น ฟังก์ชัน interval ของ Tokio คือเครื่องมือหลักที่เราจะหยิบมาใช้ในกรณีนี้:
#![allow(unused)]
fn main() {
use tokio::time::{interval, Duration};
async fn run_cache_cleanup(
pool: PgPool,
shutdown: CancellationToken,
) {
let mut ticker = interval(Duration::from_secs(300));
loop {
tokio::select! {
_ = ticker.tick() => {
if let Err(e) = cleanup_expired_sessions(&pool).await {
tracing::error!(error = ?e, "session cleanup failed");
}
}
_ = shutdown.cancelled() => {
tracing::info!("cache cleanup shutting down");
return;
}
}
}
}
}
จุดหนึ่งที่เคยทำให้ผมสะดุดในช่วงแรกคือ: interval มีการตั้งค่า MissedTickBehavior เพื่อควบคุมว่าจะทำอย่างไรเมื่อการทำงานของทาสก์ในรอบหนึ่งใช้เวลานานเกินกว่ารอบเวลาที่กำหนดไว้ ค่าดีฟอลต์คือ Burst ซึ่งจะยิงสัญญาณ tick ที่เคยพลาดไปออกมารัวๆ ทันทีเพื่อไล่กวดให้ทันรอบ แต่สำหรับงานบำรุงรักษาในเบื้องหลังส่วนใหญ่ สิ่งที่คุณต้องการจริงๆ มักจะเป็น MissedTickBehavior::Skip เพราะคุณคงอยากให้ข้าม tick ที่ตกหล่นไประหว่างที่งานรอบก่อนหน้ายังทำไม่เสร็จ แทนที่จะปล่อยให้มันสะสมแล้วระดมยิงออกมาพร้อมกันจนระบบรับไม่ไหว
#![allow(unused)]
fn main() {
let mut ticker = interval(Duration::from_secs(300));
ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Skip);
}
การผสาน worker เบื้องหลังเข้ากับ Axum
ในทางปฏิบัติ คุณมักจะเริ่มรัน background worker ไปพร้อมๆ กับเซิร์ฟเวอร์ HTTP โดยแชร์ connection pool ของฐานข้อมูลและการตั้งค่าต่างๆ ร่วมกันผ่าน AppState หรือด้วยการ clone พูลออกมาโดยตรง ทั้งนี้ในบท การปิดระบบอย่างนุ่มนวล ได้แสดงรูปแบบเต็มรูปแบบในการ spawn หลายซับซิสเต็มและการประสานงานวงจรชีวิต (lifecycle) ของระบบไว้แล้ว
ขอสรุปจุดเชื่อมต่อที่สำคัญดังนี้:
สถานะที่ใช้ร่วมกัน (Shared state) Worker ในเบื้องหลังจำเป็นต้องใช้พูลฐานข้อมูล, ค่าคอนฟิก, และอาจรวมถึงออบเจกต์ของเซอร์วิสชุดเดียวกันกับแฮนด์เลอร์ HTTP ดังนั้นให้ clone สิ่งเหล่านี้มาจากแหล่งเดียวกันตั้งแต่ช่วงเริ่มต้นการทำงานของระบบ
การปิดระบบที่ประสานงานกัน (Coordinated shutdown) Worker จะต้องถือ CancellationToken ไว้ด้วย เพื่อให้สามารถหยุดการทำงานได้อย่างนุ่มนวลเมื่อแอปพลิเคชันกำลังจะปิดตัวลง โดยเราต้องการให้ worker เคลียร์งานชิ้นปัจจุบันให้เสร็จสิ้นก่อนออกจากลูป แทนที่จะทิ้งงานค้างไว้กลางคัน
การตัดขาดข้อผิดพลาด (Error isolation) การที่ทาสก์เบื้องหลังเกิดแพนิกไม่ควรส่งผลให้เซิร์ฟเวอร์ HTTP ล่มตามไปด้วย การแยก worker ออกมารันใน tokio::spawn ต่างหากจะช่วยจำกัดขอบเขตความเสียหายให้อยู่เฉพาะจุด จากนั้นให้ทำการบันทึกล็อกข้อผิดพลาด และตัดสินใจตามความต้องการของระบบว่าจะทำการรีสตาร์ท worker ขึ้นมาใหม่ หรือปล่อยให้มันหยุดทำงานไป
คิวงานแบบถาวร
สำหรับงานที่ต้องรอดพ้นจากการรีสตาร์ทโพรเซส คุณจำเป็นต้องใช้ระบบคิวแบบถาวร (persistent queue) ที่จัดเก็บข้อมูลลงฐานข้อมูลหรือ message broker ข่าวดีก็คือ ปัจจุบันมี crate ใน Rust ที่มีความสมบูรณ์พร้อมและช่วยแก้ปัญหานี้ให้เราอยู่แล้วหลายตัว:
apalis เป็นไลบรารีประมวลผลงานเบื้องหลังที่ปลอดภัยเรื่องชนิดข้อมูล (type-safe) และยืดหยุ่นขยายได้ง่าย รองรับสตอเรจแบ็กเอนด์หลากหลาย (PostgreSQL, Redis, SQLite) อีกทั้งยังมีระบบมอนิเตอร์, เมตริก, และ graceful shutdown ติดตั้งมาให้ในตัว โดยทำงานร่วมกับ Tokio และ async runtime อื่นๆ ได้เป็นอย่างดี
fang รัน worker แต่ละตัวในทาสก์ Tokio แยกต่างหาก พร้อมความสามารถในการรีสตาร์ทใหม่อัตโนมัติหากเกิดแพนิก รองรับการตั้งเวลางานด้วย cron expression, มีโหมดคำนวณการหน่วงเวลาเพื่อลองใหม่ (retry backoff) ที่ปรับแต่งได้, และรองรับการตัดงานที่ซ้ำซ้อน (deduplication) ตามคีย์เฉพาะ
backie มอบการประมวลผลทาสก์แบบ asynchronous และ persistent โดยใช้ PostgreSQL เป็นแบ็กเอนด์ ออกแบบมาเพื่อรองรับการขยายระบบในแนวนอน (horizontal scaling) โดย worker ไม่จำเป็นต้องรันอยู่ในโพรเซสเดียวกับฝั่งที่สร้างคิว
รูปแบบการทำงานทั่วไปของระบบเหล่านี้มีความคล้ายคลึงกัน และเข้าใจได้ไม่ยาก: แฮนด์เลอร์ HTTP (หรือเซอร์วิส) ของคุณจะส่งงานเข้าคิวโดยการแทรกแถวข้อมูลใหม่ลงในตารางงาน หรือเผยแพร่ไปยัง message broker จากนั้นโพรเซสของ worker ที่แยกออกมา (หรือทาสก์เบื้องหลังในโพรเซสเดียวกัน) จะคอยดึง (poll) งานที่รออยู่ไปประมวลผล แล้วอัปเดตสถานะว่างานสำเร็จหรือล้มเหลว หากงานล้มเหลว ระบบจะทำการลองใหม่ตามระยะเวลาหน่วงที่กำหนดไว้ และเมื่องานนั้นล้มเหลวจนครบจำนวนครั้งสูงสุด มันจะถูกย้ายไปยังสถานะ dead-letter เพื่อให้ผู้ดูแลระบบเข้ามาตรวจสอบปัญหาได้ด้วยตนเอง
การจัดการข้อผิดพลาดในงานเบื้องหลัง
นี่คือจุดที่มีความน่าสนใจเป็นพิเศษ เพราะต่างจากแฮนด์เลอร์ HTTP ตรงที่งานเบื้องหลังไม่มี client คอยรอรับ error response กลับไป เมื่อทาสก์เบื้องหลังเกิดข้อผิดพลาดขึ้น คุณจึงต้องมีกลยุทธ์ที่ชัดเจนในการทำให้ความล้มเหลวนั้นมองเห็นได้และสามารถเข้าไปแก้ไขได้อย่างทันท่วงที ต่อไปนี้คือแนวทางที่ผมพบว่าใช้งานได้ผลดีอย่างยิ่ง:
บันทึกข้อผิดพลาดพร้อมบริบท (Log with context) ใช้ tracing::error! พร้อมระบุฟิลด์ข้อมูลแบบมีโครงสร้าง (structured fields) เพื่อให้ข้อผิดพลาดปรากฏบนระบบรวบรวมล็อกส่วนกลางอย่างชัดเจน และสามารถสืบสาวกลับไปยังคำขอต้นทางที่ส่งงานนี้เข้าคิวได้ หากไม่มีข้อมูลเหล่านี้ คุณจะไม่ต่างอะไรกับการงมเข็มในความมืดเมื่อเกิดปัญหาขึ้นกลางดึก
ลองใหม่พร้อมการหน่วงเวลาแบบทวีคูณ (Retry with backoff) สำหรับข้อผิดพลาดชั่วคราว (transient errors) เช่น ปัญหาเครือข่ายขัดข้องชั่วขณะ หรือฐานข้อมูลไม่พร้อมใช้งานชั่วคราว ให้ลองประมวลผลใหม่อีกครั้งโดยเว้นระยะเวลาหน่วงที่เพิ่มขึ้นเรื่อยๆ ซึ่ง crate สำหรับคิวงานแบบถาวรส่วนใหญ่มักมีฟังก์ชันนี้มาให้พร้อมใช้งานอยู่แล้ว
ย้ายไปยังคิว Dead-Letter เมื่อครบโควตาการลองใหม่ หากงานยังคงล้มเหลวซ้ำๆ จนหมดจำนวนครั้งที่กำหนด ให้ย้ายงานนั้นไปยังตารางหรือคิว dead-letter เพื่อให้ทีมงานเข้ามาตรวจสอบ หาสาเหตุ และแก้ไขหรือลบทิ้งด้วยตนเอง อย่าตั้งให้ลองใหม่ไปเรื่อยๆ อย่างไม่มีที่สิ้นสุด เพราะงานที่ล้มเหลวถาวรจะคอยแย่งทรัพยากรของ worker และทำให้งานอื่นๆ ในคิวต้องล่าช้าตามไปด้วย
เก็บและรายงานเมตริก (Emit metrics) คอยติดตามอัตราความสำเร็จของงาน, ระยะเวลาที่ใช้ในการประมวลผล, ความยาวของคิว (queue depth), และจำนวนครั้งของการลองใหม่ เมตริกเหล่านี้เปรียบเสมือนระบบเตือนภัยล่วงหน้าที่จะแจ้งเตือนปัญหาที่กำลังก่อตัวก่อนที่ผู้ใช้งานจริงจะได้รับผลกระทบ จากประสบการณ์ของผม กราฟความยาวของคิวที่พุ่งสูงขึ้นอย่างต่อเนื่องมักเป็นสัญญาณเตือนแรกเสมอว่าระบบกำลังเริ่มมีปัญหา
gRPC ด้วย Tonic
หากคุณกำลังสร้างเซอร์วิส Axum ตามแบบแผนในบทก่อนๆ มาเรื่อยๆ เมื่อถึงจุดหนึ่งคุณจะต้องพบกับคำถามที่คุ้นเคย: เราจะสื่อสารกับเซอร์วิสภายในตัวอื่นๆ อย่างไร? การสร้าง API แบบ HTTP/JSON นั้นยอดเยี่ยมมากสำหรับไคลเอนต์บนเว็บเบราว์เซอร์และผู้ใช้งานภายนอก แต่สำหรับการสื่อสารกันเองระหว่างเซอร์วิสภายใน (service-to-service communication) คุณมักจะต้องการอะไรบางอย่างที่มีการรับประกันโครงสร้างข้อมูล (schema guarantees) ที่รัดกุมกว่า, มีระบบสตรีมมิงในตัว, และสร้างโค้ดให้โดยอัตโนมัติ นั่นคือจุดที่ gRPC เข้ามาตอบโจทย์ ซึ่ง Tonic คือเฟรมเวิร์ก gRPC ที่เป็นตัวเลือกอันดับหนึ่งในระบบนิเวศของ Rust และเนื่องจากมันถูกพัฒนาขึ้นบน Tokio เช่นเดียวกับ Axum ทั้งสองตัวจึงทำงานประสานกันได้อย่างลงตัวไร้รอยต่อ
ในบทนี้ เราจะมาดูขั้นตอนการเพิ่มช่องทาง gRPC ให้กับเซอร์วิส Rust ที่มีอยู่เดิม รันมันควบคู่ไปกับเซิร์ฟเวอร์ HTTP Axum และนำหลักการทางสถาปัตยกรรมชุดเดิมที่เราใช้มาตลอด (แฮนด์เลอร์ขนาดเล็กเบาบาง, การแยกเลเยอร์โดเมนอย่างชัดเจน, การจัดการข้อผิดพลาดแบบรวมศูนย์) มาประยุกต์ใช้กับฝั่ง gRPC อย่างเป็นระบบ
เมื่อไหร่ควรใช้ gRPC
gRPC ตอบโจทย์ได้อย่างเป็นธรรมชาติเมื่อผู้เรียกใช้งาน (consumer) คือเซอร์วิสตัวอื่นๆ ภายใต้การควบคุมของคุณเอง ทั้งสองฝั่งจะได้รับประโยชน์จากสกีมาส่วนกลางที่กำหนดไว้ในไฟล์ .proto, รูปแบบ wire format ของ Protocol Buffers (protobuf) นั้นกะทัดรัดและประหยัดแบนด์วิธกว่า JSON มาก, และคุณยังได้ความปลอดภัยเรื่องชนิดข้อมูล (type safety) ข้ามภาษาไปใช้งานได้ฟรีๆ อีกด้วย ยิ่งไปกว่านั้น RPC แบบสตรีม (ไม่ว่าจะเป็น server-streaming, client-streaming, หรือแบบสองทิศทาง bidirectional) ยังถือเป็นแนวคิดระดับ first-class ที่รองรับมาตั้งแต่ต้น ไม่ใช่สิ่งที่ต้องมาดัดแปลงเสริมแต่งในภายหลัง
ทว่าจุดที่ gRPC อาจไม่ค่อยเหมาะนัก ได้แก่ ไคลเอนต์ที่รันบนเว็บบราวเซอร์โดยตรง (แม้จะมี gRPC-Web เข้ามาช่วยปิดช่องว่างนี้ก็ตาม), พับลิก API ที่จำเป็นต้องเปิดให้ทดสอบยิงได้ง่ายๆ ด้วยคำสั่ง curl, หรือเซอร์วิสประเภท CRUD พื้นฐานทั่วไปที่ขั้นตอนและกลไกของ protobuf อาจกลายเป็นภาระมากกว่าความคุ้มค่า
จากประสบการณ์จริง ระบบในระดับ production ส่วนใหญ่มักจบลงด้วยการใช้งานร่วมกันทั้งสองรูปแบบ: ใช้ gRPC สำหรับการสื่อสารกันเองระหว่างเซอร์วิสภายใน และเปิด API แบบ HTTP/JSON สำหรับฝั่งภายนอกหรือผู้ใช้ทั่วไป ซึ่งนี่ก็คือสถานการณ์จริงที่เราจะมาจัดการกันในบทนี้นั่นเอง
การจัดระเบียบไฟล์ Proto
นิยามของ Protocol buffer จะถูกเขียนไว้ในไฟล์ .proto ซึ่งโดยทั่วไปมักจัดวางไว้ในไดเรกทอรี proto/ ณ ระดับรากของโปรเจกต์หรือเวิร์กสเปซของคุณ:
my-service/
├── proto/
│ └── myservice/
│ └── v1/
│ ├── users.proto
│ └── health.proto
├── build.rs
├── Cargo.toml
└── src/
└── ...
คุณอาจสงสัยว่าทำไมเราจึงควรกำหนดเวอร์ชันให้กับแพ็กเกจ proto (เช่น myservice.v1) ตั้งแต่แรกเริ่ม อันที่จริงแล้ว เรื่องนี้มีความสำคัญยิ่งกว่าการทำ REST เสียอีก เพราะสกีมา proto จะถูกนำไปคอมไพล์เป็นโค้ดในฝั่งของไคลเอนต์ เมื่อผู้บริโภคนำไทป์ที่เจนออกมาเหล่านั้นไปใช้งานแล้ว การแก้ไขสกีมาอาจกลายเป็นการเปลี่ยนแปลงที่กระทบโค้ดเดิมอย่างรุนแรง (breaking change) สำหรับทุกคนได้ทันที การวางโครงสร้างระบุเวอร์ชันไว้ตั้งแต่ต้นจึงช่วยปกป้องคุณจากการต้องมาทำไมเกรชันที่ยุ่งยากซับซ้อนในภายหลัง
ตัวอย่างไฟล์ proto ทั่วไปจะมีโครงสร้างดังนี้:
syntax = "proto3";
package myservice.v1;
service UserService {
rpc GetUser (GetUserRequest) returns (GetUserResponse);
rpc CreateUser (CreateUserRequest) returns (CreateUserResponse);
rpc ListUsers (ListUsersRequest) returns (stream UserResponse);
}
message GetUserRequest {
string id = 1;
}
message GetUserResponse {
string id = 1;
string name = 2;
string email = 3;
}
// ... other messages
การสร้างโค้ดตอนบิลด์
Tonic จะอาศัยสคริปต์การบิลด์ (build.rs) เพื่อคอมไพล์ไฟล์ .proto ออกมาเป็นโค้ด Rust ในระหว่างกระบวนการบิลด์โปรเจกต์ เรามาลองเพิ่มดีเพนเดนซีที่จำเป็นลงใน Cargo.toml กันก่อน:
[dependencies]
tonic = "0.14"
tonic-prost = "0.14"
prost = "0.14"
[build-dependencies]
tonic-prost-build = "0.14"
จุดหนึ่งที่อาจทำให้คุณสับสนได้คือ: ตั้งแต่เวอร์ชัน Tonic 0.14 เป็นต้นมา การสร้างโค้ดจาก protobuf จะเปลี่ยนมาใช้ tonic-prost-build แทนการใช้ tonic-build โดยตรง แม้ crate tonic-build จะยังคงมีอยู่เพื่อทำหน้าที่เป็นโครงสร้างพื้นฐานสำหรับ codegen แต่ตัวที่คุณจำเป็นต้องเรียกใช้สำหรับการคอมไพล์ protobuf จริงๆ คือ tonic-prost-build และคุณยังจำเป็นต้องใส่ tonic-prost เป็นดีเพนเดนซีสำหรับตอนรันไทม์ควบคู่ไปกับ tonic อีกด้วย
คราวนี้ มาเขียนสคริปต์ใน build.rs กัน:
fn main() -> Result<(), Box<dyn std::error::Error>> {
tonic_prost_build::configure()
.build_server(true)
.build_client(true)
.compile_protos(
&["proto/myservice/v1/users.proto"],
&["proto/"],
)?;
Ok(())
}
โค้ดที่ถูกสร้างขึ้นจะถูกจัดเก็บไว้ในไดเรกทอรี target/ ของคุณ และคุณสามารถนำโค้ดดังกล่าวเข้ามาใช้งานในโปรเจกต์ได้ด้วยมาโคร tonic::include_proto!("myservice.v1") นอกจากนี้ หากคุณต้องการให้ไทป์ที่ถูกเจนขึ้นมาสามารถผสานการทำงานกับไทป์ในโดเมนได้อย่างราบรื่น คุณยังสามารถตั้งค่าคอนฟิกให้เพิ่ม derive แบบกำหนดเอง (เช่น Eq, Hash, หรือ serde::Serialize) เข้าไปได้อีกด้วย
การนำเซอร์วิส gRPC ไปใช้
โค้ดที่ถูกเจนขึ้นมาจะเตรียมเทรต (trait) สำหรับนำไปอิมพลีเมนต์เป็นเซอร์วิสของคุณ โดยแต่ละเมธอดของ RPC จะกลายสภาพเป็นเมธอดบนเทรตที่รับค่า Request<T> และส่งคืนผลลัพธ์กลับมาเป็น Result<Response<U>, Status> ซึ่งหากคุณเคยเขียนแฮนด์เลอร์ใน Axum มาก่อน โครงสร้างนี้จะให้ความรู้สึกที่คุ้นเคยเป็นอย่างยิ่ง
#![allow(unused)]
fn main() {
use tonic::{Request, Response, Status};
// Include the generated code.
pub mod pb {
tonic::include_proto!("myservice.v1");
}
use pb::user_service_server::{UserService, UserServiceServer};
pub struct MyUserService {
// Same domain services and repositories you use in Axum handlers.
inner: domain::services::UserService<PostgresUserRepo>,
}
impl UserService for MyUserService {
async fn get_user(
&self,
request: Request<pb::GetUserRequest>,
) -> Result<Response<pb::GetUserResponse>, Status> {
let req = request.into_inner();
let id = Uuid::parse_str(&req.id)
.map_err(|_| Status::invalid_argument("invalid user ID"))?;
let user = self.inner
.get_by_id(&UserId::from_uuid(id))
.await
.map_err(|e| {
tracing::error!(error = ?e, "failed to fetch user");
Status::internal("internal error")
})?
.ok_or_else(|| Status::not_found("user not found"))?;
Ok(Response::new(pb::GetUserResponse {
id: user.id().as_uuid().to_string(),
name: user.name().as_str().to_string(),
email: user.email().as_str().to_string(),
}))
}
// ... other methods
}
}
สังเกตได้ว่ารูปแบบนี้ถอดแบบมาจากแพตเทิร์นเดียวกับแฮนด์เลอร์ของ Axum แบบเป๊ะๆ: ดึงข้อมูลอินพุตออกมา, เรียกใช้เซอร์วิสของโดเมน, แล้วแปลงผลลัพธ์ให้อยู่ในฟอร์แมตสำหรับส่งผ่านเครือข่าย ความแตกต่างมีเพียงเล็กน้อยเท่านั้น คือข้อผิดพลาดจะถูกแปลงไปเป็นรหัสสถานะ tonic::Status แทนที่จะเป็น HTTP status code และไทป์ของคำขอ/การตอบกลับจะมาจาก protobuf แทนการทำ JSON deserialization แต่รูปทรง (shape) ของโครงสร้างโค้ดยังคงเหมือนเดิมทุกประการ ซึ่งนี่คือหัวใจและเป้าหมายทั้งหมดของการออกแบบสถาปัตยกรรมแบบแบ่งเลเยอร์ของเรา
การจัดการข้อผิดพลาดใน gRPC
tonic::Status คือสิ่งที่เทียบเท่ากับรหัสสถานะ HTTP ในโลกของ gRPC แต่จะพ่วงข้อความแจ้งข้อผิดพลาดแนบติดไปด้วย รหัสมาตรฐานจะประกอบไปด้วย NotFound, InvalidArgument, PermissionDenied, Internal, Unavailable และอื่นๆ ซึ่งสามารถจับคู่ความหมายเข้ากับรหัส HTTP ได้อย่างตรงไปตรงมา
หากคุณมี enum AppError สำหรับแฮนด์เลอร์ Axum อยู่แล้ว (ตามที่อธิบายไว้ในบท การจัดการข้อผิดพลาด) คุณสามารถเขียนตัวแปลงชนิดข้อมูลจาก AppError ไปเป็น Status เพื่อนำสิ่งที่มีอยู่แล้วกลับมาใช้ซ้ำได้อย่างคุ้มค่า:
#![allow(unused)]
fn main() {
impl From<AppError> for Status {
fn from(err: AppError) -> Self {
match err {
AppError::NotFound => Status::not_found("resource not found"),
AppError::Validation(msg) => Status::invalid_argument(msg),
AppError::Unauthorized => Status::unauthenticated("authentication required"),
AppError::Forbidden => Status::permission_denied("insufficient permissions"),
AppError::Conflict(msg) => Status::already_exists(msg),
AppError::Internal(e) => {
tracing::error!(error = ?e, "internal error in gRPC handler");
Status::internal("internal error")
}
_ => Status::internal("internal error"),
}
}
}
}
เมื่อมีตัวแปลงนี้แล้ว แฮนด์เลอร์ gRPC ของคุณก็สามารถใช้โอเปอเรเตอร์ ? ในการส่งต่อข้อผิดพลาดได้แบบเดียวกับแฮนด์เลอร์ของ Axum ข้อผิดพลาดจากฝั่งโดเมนจะถูกแปลงเป็นรหัสสถานะ gRPC ที่ถูกต้องโดยอัตโนมัติ ทำให้คุณไม่ต้องมาคอยเขียนตรรกะการแปลง error ซ้ำๆ กระจายอยู่ทั่วทั้งโปรเจกต์
การรัน gRPC ควบคู่กับ Axum
โดยทั่วไปมีสองแนวทางหลักในการรันทั้ง HTTP และ gRPC ร่วมกันภายในโพรเซสเดียวกัน เรามาดูข้อดีข้อเสียของแต่ละแบบกัน:
แยกคนละพอร์ต (Separate ports) เป็นตัวเลือกที่เรียบง่ายกว่า และเป็นแนวทางที่ผมแนะนำให้เริ่มต้นใช้งาน โดยให้เซิร์ฟเวอร์ Axum ของเรา bind เข้ากับพอร์ต 3000 และเซิร์ฟเวอร์ Tonic bind เข้ากับพอร์ต 50051 ทั้งสองตัวจะรันแยกกันใน tokio::spawn ของตนเอง พร้อมทั้งแชร์ AppState, พูลฐานข้อมูล, และเซอร์วิสโดเมนร่วมกันอย่างเป็นอิสระ
#![allow(unused)]
fn main() {
// Spawn the HTTP server.
let http_handle = tokio::spawn(async move {
let listener = TcpListener::bind("0.0.0.0:3000").await.unwrap();
axum::serve(listener, http_router)
.with_graceful_shutdown(http_token.cancelled_owned())
.await
.unwrap();
});
// Spawn the gRPC server.
let grpc_handle = tokio::spawn(async move {
tonic::transport::Server::builder()
.add_service(UserServiceServer::new(grpc_user_service))
.serve_with_shutdown(
"0.0.0.0:50051".parse().unwrap(),
grpc_token.cancelled_owned(),
)
.await
.unwrap();
});
}
ใช้พอร์ตเดียวกันพร้อมการตรวจจับโปรโตคอล (Same port with protocol detection) วิธีนี้จะมีความซับซ้อนมากกว่า แต่ช่วยลดภาระด้านการจัดการพอร์ตลงได้ โดย Server ของ Tonic สามารถประกอบเข้ากับเราเตอร์ของ Axum เพื่อให้คำขอ gRPC ที่วิ่งผ่าน HTTP/2 และคำขอ REST ที่วิ่งผ่าน HTTP/1.1 ได้รับการจัดการผ่าน listener บนพอร์ตเดียวกัน อย่างไรก็ตาม วิธีนี้ต้องอาศัยการตั้งค่าที่รัดกุมรอบคอบ และจากประสบการณ์ตรง มันมักจะคุ้มค่าเฉพาะเมื่อคุณมีเหตุผลจำเป็นจริงๆ เช่น ต้องปฏิบัติตามนโยบายด้านเน็ตเวิร์กที่เข้มงวด
สำหรับแอปพลิเคชันส่วนใหญ่ การเลือกใช้พอร์ตแยกกันถือเป็นทางเลือกที่ดีกว่ามาก เพราะเรียบง่ายกว่า, แยกมอนิเตอร์และตรวจสอบได้สะดวกกว่า, และไม่เสี่ยงที่จะเจอกับปัญหา edge case ในขั้นตอนการตรวจจับโปรโตคอล
มิดเดิลแวร์และอินเทอร์เซปเตอร์
Tonic รองรับอินเทอร์เซปเตอร์ (interceptor) ซึ่งทำหน้าที่เทียบเท่ากับมิดเดิลแวร์ในโลกของ gRPC โดยคุณสามารถแทรกระบบยืนยันตัวตน, การบันทึกล็อก, และการจัดการเรื่องส่วนกลางอื่นๆ (cross-cutting concerns) ได้เช่นเดียวกับที่ทำใน Axum:
#![allow(unused)]
fn main() {
use tonic::service::interceptor;
fn auth_interceptor(req: Request<()>) -> Result<Request<()>, Status> {
let token = req.metadata()
.get("authorization")
.and_then(|v| v.to_str().ok())
.and_then(|v| v.strip_prefix("Bearer "))
.ok_or_else(|| Status::unauthenticated("missing token"))?;
// Validate token...
Ok(req)
}
// Apply the interceptor to a service.
let user_service = UserServiceServer::with_interceptor(
MyUserService::new(state),
auth_interceptor,
);
}
สำหรับมิดเดิลแวร์ที่มีความซับซ้อนมากขึ้น (เช่น tracing, metrics, timeout) Tonic สามารถต่อเข้ากับเลเยอร์ของ Tower ได้เช่นเดียวกับ Axum คุณจึงสามารถนำ TraceLayer, TimeoutLayer, และมิดเดิลแวร์ตัวอื่นๆ ของ Tower มาใช้งานร่วมกับเซิร์ฟเวอร์ gRPC ของคุณได้ทันที ทำให้องค์ความรู้และทักษะที่คุณได้ฝึกฝนมาจากบทก่อนๆ สามารถนำมาต่อยอดใช้งานได้โดยตรง
gRPC reflection
การเปิดใช้งาน server reflection จะช่วยให้เครื่องมือฝั่งไคลเอนต์ เช่น grpcurl และ grpc-ui สามารถตรวจสอบและค้นพบ API ของเซอร์วิสคุณได้โดยอัตโนมัติโดยไม่จำเป็นต้องมีไฟล์ .proto อยู่ในเครื่องปลายทาง ให้มองว่ามันคือสิ่งที่เทียบเท่ากับ Swagger UI ในโลกของ gRPC ฟีเจอร์นี้มีประโยชน์อย่างมหาศาลในระหว่างขั้นตอนการพัฒนา ดังนั้นผมจึงแนะนำให้ตั้งค่าเปิดใช้งานไว้ตั้งแต่เนิ่นๆ
#![allow(unused)]
fn main() {
use tonic_reflection::server::Builder;
let reflection_service = Builder::configure()
.register_encoded_file_descriptor_set(pb::FILE_DESCRIPTOR_SET)
.build_v1()?;
tonic::transport::Server::builder()
.add_service(reflection_service)
.add_service(UserServiceServer::new(user_service))
.serve(addr)
.await?;
}
สำหรับการสร้างชุดไฟล์ descriptor ให้เพิ่มคำสั่งต่อไปนี้ลงในไฟล์ build.rs ของคุณ:
#![allow(unused)]
fn main() {
tonic_prost_build::configure()
.file_descriptor_set_path(
std::path::PathBuf::from(std::env::var("OUT_DIR").unwrap())
.join("myservice_descriptor.bin")
)
.compile_protos(&["proto/myservice/v1/users.proto"], &["proto/"])?;
}
การทดสอบเซอร์วิส gRPC
คุณสามารถทดสอบเซอร์วิส gRPC ได้อย่างสมจริง โดยการเปิดเซิร์ฟเวอร์ขึ้นมาจริงๆ ภายในเทสต์ แล้วเชื่อมต่อเข้าไปด้วยไคลเอนต์ที่ถูกเจนขึ้นมา:
#![allow(unused)]
fn main() {
#[tokio::test]
async fn test_get_user() {
let addr = start_test_grpc_server().await;
let mut client = UserServiceClient::connect(
format!("http://{}", addr)
).await.unwrap();
let response = client
.get_user(pb::GetUserRequest {
id: "some-uuid".to_string(),
})
.await
.unwrap();
assert_eq!(response.into_inner().name, "Alice");
}
}
หากคุณกังวลเรื่อง overhead ของการเชื่อมต่อเครือข่ายสำหรับการทำยูนิตเทสต์ที่ต้องการความรวดเร็วสูง คุณยังสามารถเลือกใช้ tonic::transport::Channel ร่วมกับ in-process transport ได้อีกด้วย ซึ่งมีแนวคิดคล้ายคลึงกับแพตเทิร์นการทดสอบแบบ oneshot ของ Axum ช่วยให้เทสต์ของคุณทำงานได้อย่างรวดเร็วเป็นพิเศษโดยไม่สูญเสียความครอบคลุมในการทดสอบเลย
HTTP ขาออกและความทนทานของบริการ
ที่ผ่านมา เรามักมองเซอร์วิสของเราในบทบาทของ “เซิร์ฟเวอร์” ที่คอยรับคำขอและส่งการตอบกลับ แต่ในความเป็นจริง เซอร์วิสส่วนใหญ่ก็ทำหน้าที่เป็น “ไคลเอนต์” ด้วยเช่นกัน โดยเว็บเซิร์ฟเวอร์ของเราต้องคอยเรียกใช้งาน payment gateway, ส่ง webhook, ยิงคิวรีไปยัง API ภายใน, ดึงข้อมูลจากบริการภายนอก (third-party), หรือส่งข้อความเข้าคิว ผมเคยพบเห็นเหตุการณ์ระบบล่มหลายครั้งที่ไม่เกี่ยวข้องอะไรเลยกับการจัดการทราฟฟิกขาเข้า แต่ปัญหาเกิดจากวิธีการที่เราเรียกออกไปยังภายนอก หาก downstream dependency เกิดทำงานช้าลงและคุณไม่มีกลไกป้องกัน (guardrails) ที่รัดกุมพอ มันก็พร้อมที่จะลากเซอร์วิสทั้งหมดของคุณล่มตามไปด้วยทันที
ในบทนี้ เราจะมาเจาะลึกแพตเทิร์นที่จะช่วยปกป้องไม่ให้การเรียก HTTP ขาออกสร้างหายนะให้กับระบบของคุณ: ไม่ว่าจะเป็นการตั้งเวลาหมดเวลา (timeout), การลองใหม่ (retry), การหน่วงเวลาถอยร่น (backoff), คุณสมบัติการทำซ้ำแล้วได้ผลคงเดิม (idempotency), ระบบตัดวงจร (circuit breaking), และการส่งต่อบริบทการติดตาม (trace context propagation)
reqwest ในฐานะไคลเอนต์ HTTP
Crate reqwest คือไคลเอนต์ HTTP ที่เป็นตัวเลือกอันดับหนึ่งในระบบนิเวศของ Rust รองรับ async มาตั้งแต่กำเนิด, จัดการเรื่อง TLS ให้โดยอัตโนมัติ, รองรับ connection pooling, และทำงานร่วมกับ Tokio runtime ได้อย่างกลมกลืน จุดหนึ่งที่มักทำให้หลายคนสะดุดในช่วงเริ่มต้นคือ: คุณควรสร้างอินสแตนซ์ Client เพียงตัวเดียวตอนเริ่มต้นระบบ (startup) แล้วแชร์ใช้งานร่วมกันทั่วทั้งแอปพลิเคชัน เนื่องจาก Client จะดูแล connection pool ภายในตัวมันเอง หากคุณสร้างอินสแตนซ์ใหม่ขึ้นมาทุกครั้งที่มีคำขอเข้ามา คุณจะสูญเสียประโยชน์ทั้งหมดที่ได้จากการทำ pooling ไปอย่างน่าเสียดาย
#![allow(unused)]
fn main() {
use reqwest::Client;
use std::time::Duration;
pub fn create_http_client() -> Client {
Client::builder()
.timeout(Duration::from_secs(10))
.connect_timeout(Duration::from_secs(3))
.pool_max_idle_per_host(10)
.build()
.expect("failed to create HTTP client")
}
}
เราจะเก็บไคลเอนต์นี้ไว้ใน AppState และดึงออกมาใช้งานในแฮนด์เลอร์หรือเซอร์วิสเมื่อต้องการยิงคำขอออกไปข้างนอก โดยไคลเอนต์ตัวเดียวกันนี้สามารถรองรับคำขอที่ทำงานพร้อมกันหลายรายการได้อย่างปลอดภัย ซึ่งตรงกับสิ่งที่เราต้องการอย่างยิ่ง
การหมดเวลาในทุกระดับ
หากผมต้องเลือกกลไกเพื่อความทนทาน (resilience) เพียงอย่างเดียวสำหรับการเรียกใช้งานภายนอก สิ่งนั้นคือการกำหนด “เวลาหมดเวลา” (timeout) อย่างแน่นอน เพราะหากปราศจากมัน เซอร์วิสปลายทางที่ตอบสนองช้าหรือไม่ตอบสนองเลยจะดึงการเชื่อมต่อของคุณค้างไว้แบบไม่มีกำหนด จนในที่สุด connection pool, file descriptor, หรือความสามารถในการรับคำขอของเซิร์ฟเวอร์ของคุณจะถูกกลืนกินจนหมดสิ้น ผมเคยเห็นปัญหานี้เกิดขึ้นจริงบน production มาแล้ว และมันไม่ใช่เรื่องน่าอภิรมย์เลยแม้แต่น้อย
มีระดับการกำหนด timeout อยู่ 3 ระดับที่คุณควรนำมาพิจารณา:
Connect timeout ควบคุมระยะเวลาที่เรารอเพื่อเปิดการเชื่อมต่อ TCP หากเซิร์ฟเวอร์ปลายทางไม่สามารถเข้าถึงได้หรือเกิดปัญหาเครือข่าย คุณย่อมต้องการให้มันล้มเหลวโดยเร็ว (fail fast) ดีกว่ารอจนหมดค่าเริ่มต้นของระบบปฏิบัติการ (ซึ่งบน Linux อาจยาวนานถึง 120 วินาที) ระยะเวลา 3 ถึง 5 วินาทีจึงเป็นจุดเริ่มต้นที่สมเหตุสมผล
Per-request timeout จำกัดเวลาการทำงานทั้งหมดสำหรับคำขอ HTTP หนึ่งรายการ ซึ่งครอบคลุมตั้งแต่การเชื่อมต่อ, การทำ TLS handshake, การส่งคำขอ, ตลอดจนการรับข้อมูลตอบกลับกลับมาจนครบถ้วน โดยทั่วไปมักตั้งไว้ที่ 10 ถึง 30 วินาที แต่ทั้งนี้ขึ้นอยู่กับว่าคุณคาดหวังให้ระบบปลายทางตอบสนองเร็วแค่ไหน
Overall operation timeout คือเส้นตาย (deadline) สูงสุดสำหรับการดำเนินงานทั้งหมด ซึ่งครอบคลุมถึงการพยายามลองใหม่ (retry) ด้วย หากกฎทางธุรกิจระบุว่า “ต้องดึงสถานะการชำระเงินให้ได้ภายใน 30 วินาที” งบเวลา 30 วินาทีนั้นจะต้องครอบคลุมการลองใหม่ทั้งหมด ไม่ใช่แค่งบต่อการยิงหนึ่งครั้ง ให้ใช้ tokio::time::timeout ครอบลูปของการลองใหม่ทั้งหมด แทนที่จะครอบเฉพาะคำขอแต่ละรอบ
#![allow(unused)]
fn main() {
use tokio::time::timeout;
async fn fetch_with_deadline(
client: &Client,
url: &str,
deadline: Duration,
) -> anyhow::Result<String> {
timeout(deadline, async {
// Individual attempts have their own timeout (via client config).
// The outer timeout caps the total time including retries.
let response = client.get(url).send().await?.error_for_status()?;
Ok(response.text().await?)
})
.await
.map_err(|_| anyhow::anyhow!("operation timed out after {:?}", deadline))?
}
}
การลองใหม่และการถอยหน่วง
ความผิดพลาดชั่วคราว (transient failure) คือสัจธรรมที่หลีกเลี่ยงไม่ได้ในระบบแบบกระจาย (distributed systems) ไม่ว่าจะเป็นปัญหาเครือข่ายกระตุกชั่วขณะ, เซอร์วิสปลายทางรีสตาร์ทสั้นๆ, หรือเกิด timeout จากโหลดที่พุ่งขึ้นชั่วคราว ข้อผิดพลาดเหล่านี้หากเราเว้นจังหวะแล้วลองส่งใหม่อีกครั้งในอีกสักครู่ก็มักจะทำงานสำเร็จ ดังนั้น ไคลเอนต์ขาออกที่ดีจึงควรมีระบบลองใหม่สำหรับความล้มเหลวลักษณะนี้ พร้อมทั้งเพิ่มระยะเวลาหน่วงระหว่างการลองแต่ละรอบเพื่อไม่ให้เป็นการซ้ำเติมระบบปลายทาง
#![allow(unused)]
fn main() {
use std::time::Duration;
use tokio::time::sleep;
async fn fetch_with_retries(
client: &Client,
url: &str,
max_retries: u32,
) -> anyhow::Result<reqwest::Response> {
let mut last_error = None;
for attempt in 0..=max_retries {
if attempt > 0 {
// Exponential backoff with jitter to prevent thundering herd.
let base = Duration::from_millis(100 * 2u64.pow(attempt - 1));
let jitter = Duration::from_millis(rand::random::<u64>() % 50);
sleep(base + jitter).await;
}
match client.get(url).send().await {
Ok(resp) if resp.status().is_server_error() => {
// 5xx errors are retryable.
last_error = Some(anyhow::anyhow!(
"server error: {}", resp.status()
));
}
Ok(resp) => return Ok(resp),
Err(e) if e.is_timeout() || e.is_connect() => {
// Timeouts and connection errors are retryable.
last_error = Some(e.into());
}
Err(e) => return Err(e.into()), // Non-retryable error.
}
}
Err(last_error.unwrap_or_else(|| anyhow::anyhow!("exhausted retries")))
}
}
ในการออกแบบกลยุทธ์การลองใหม่ มีการตัดสินใจหลักๆ ไม่กี่ข้อที่คุณต้องกำหนดให้ชัดเจน:
ข้อผิดพลาดประเภทใดที่ควรลองใหม่ (Which errors to retry) ให้ลองใหม่เฉพาะกับข้อผิดพลาดด้านการเชื่อมต่อ (connection errors), timeout, และการตอบกลับรหัสตระกูล 5xx ห้ามลองใหม่กับรหัสตระกูล 4xx โดยเด็ดขาด เพราะนั่นหมายถึงคำขอมีข้อผิดพลาด และการส่งคำขอเดิมซ้ำไปอีกก็ไม่มีวันช่วยอะไร เช่นเดียวกับข้อผิดพลาดที่บ่งชี้ว่าเป็นปัญหาถาวร เช่น การ resolve ชื่อโดเมน (DNS) ไม่สำเร็จเนื่องจากไม่มีโดเมนนั้นอยู่จริง
กลยุทธ์การถอยร่น (Backoff strategy) การใช้ Exponential backoff (เพิ่มระยะเวลาหน่วงเป็นสองเท่าในแต่ละรอบ) ควบคู่กับ Jitter (การเพิ่มค่าสุ่มเล็กๆ น้อยๆ เข้าไป) คือแนวทางมาตรฐาน โดย jitter มีความสำคัญอย่างยิ่งในการป้องกันปัญหาฝูงชนแห่เข้าซ้ำ (thundering herd problem) ซึ่งเกิดจากการที่ไคลเอนต์จำนวนมากต่างแห่กันยิงคำขอรอบใหม่เข้ามาพร้อมกันเป๊ะๆ ทันทีที่ระบบฟื้นตัว ทำให้เซอร์วิสปลายทางที่กำลังตั้งหลักต้องล่มซ้ำลงไปอีก
จำนวนครั้งสูงสุดในการลองใหม่ (Maximum attempts) โดยทั่วไปมักกำหนดไว้ที่ 3 ถึง 5 ครั้ง หากเกินกว่านั้นมักหมายความว่าระบบปลายทางล่มแบบต่อเนื่องยาวนาน และการฝืนลองใหม่ต่อไปก็มีแต่จะเพิ่มโหลดโดยเปล่าประโยชน์
การทำซ้ำแล้วได้ผลเหมือนเดิมของปฏิบัติการที่ลองใหม่
การลองใหม่กับคำขอแบบ GET ย่อมปลอดภัยเสมอ เพราะ GET มีคุณสมบัติ idempotent (ทำซ้ำแล้วได้ผลลัพธ์คงเดิม) ตามนิยาม แต่การลองใหม่กับคำขอ POST ที่ทำการสร้างรีซอร์สขึ้นใหม่ล่ะ? นั่นเป็นคนละเรื่องกันเลย หาก API ปลายทางไม่ได้รองรับ idempotency key การลองยิง POST ซ้ำอาจส่งผลให้เกิดข้อมูลซ้ำซ้อนในระบบ ซึ่งคงเป็นสิ่งสุดท้ายที่คุณอยากให้เกิดขึ้น
หากคุณกำลังเรียกใช้ API ที่รองรับ idempotency key (ตัวอย่างเช่น Stripe ที่รองรับเฮดเดอร์ Idempotency-Key) แนวทางจัดการจะตรงไปตรงมามาก: เพียงแค่สร้าง UUID สำหรับการทำรายการนั้นขึ้นมาหนึ่งตัว แล้วแนบส่งไปในทุกๆ รอบที่มีการลองใหม่:
#![allow(unused)]
fn main() {
let idempotency_key = Uuid::new_v4().to_string();
for attempt in 0..=max_retries {
let result = client
.post(url)
.header("Idempotency-Key", &idempotency_key)
.json(&payload)
.send()
.await;
// Same retry logic as above.
}
}
แล้วถ้า API ปลายทางไม่ได้รองรับ idempotency key ล่ะ? คุณมีทางเลือกอยู่ 2 ทาง: ข้อแรกคือออกแบบการทำงานให้มีคุณสมบัติ idempotent โดยธรรมชาติ (เช่น เปลี่ยนไปใช้ PUT พร้อมระบุ ID ที่กำหนดไว้ล่วงหน้า แทนที่จะใช้ POST ไปยังคอลเลกชัน) หรือข้อสองคือ ไม่ต้องลองใหม่สำหรับการทำงานที่เป็นการเขียนข้อมูลเลย แล้วส่งต่อข้อผิดพลาดออกมาเพื่อให้มนุษย์เข้ามาตรวจสอบและแก้ไขด้วยตนเอง แม้จะไม่มีวิธีใดที่สมบูรณ์แบบไร้ที่ติ แต่ทั้งสองทางเลือกก็ยังดีกว่าการปล่อยให้ระบบตัดเงินหรือสร้างรายการซ้ำซ้อนอย่างเงียบๆ โดยไม่รู้ตัว
การตัดวงจร (Circuit breaking)
คุณอาจตั้งคำถามว่า: หากเซอร์วิสปลายทางเกิดความล้มเหลวอย่างต่อเนื่อง ทำไมเรายังต้องดันทุรังส่งคำขอต่อไปเรื่อยๆ? การทำเช่นนั้นมีแต่จะทำให้เราสูญเสียทรัพยากรไปโดยเปล่าประโยชน์ และยิ่งเป็นการเพิ่มโหลดซ้ำเติมระบบปลายทางที่กำลังวิกฤตอยู่แล้ว นี่คือเหตุผลที่ต้องมี Circuit Breaker (ระบบตัดวงจร) โดยระบบจะคอยติดตามอัตราความล้มเหลว และเมื่อตัวเลขพุ่งสูงจนเกินเกณฑ์ที่กำหนด มันจะทำการตัดวงจร (short-circuit) ปฏิเสธคำขอทันทีในช่วงเวลาคูลดาวน์ ก่อนที่จะเริ่มเปิดให้ทดลองส่งใหม่อีกครั้ง
ในระบบนิเวศของ tower มี crate เช่น tower-resilience ที่เตรียมมิดเดิลแวร์สำหรับ circuit breaker, bulkhead, และ retry ให้คุณสามารถนำมาประกอบเข้ากับ reqwest client หรือ Tower service ใดๆ ได้อย่างยืดหยุ่น และสำหรับความต้องการในระดับพื้นฐาน คุณสามารถเขียน circuit breaker อย่างง่ายได้ด้วยตัวเองโดยใช้ตัวนับความล้มเหลวแบบ AtomicU32 ร่วมกับ tokio::time::Instant สำหรับบันทึกเวลาที่ทำการตรวจสอบล่าสุด
สถานะการทำงานมีอยู่ 3 สถานะหลัก ได้แก่:
- Closed (สภาวะปกติ): คำขอวิ่งผ่านได้ตามปกติ หากเกิดข้อผิดพลาดจะเพิ่มตัวนับความล้มเหลวขึ้น
- Open (ตัดวงจร): คำขอจะถูกปฏิเสธกลับไปทันทีโดยไม่มีการยิงออกไปยังปลายทางจริง เมื่อพ้นช่วงเวลาคูลดาวน์ วงจรจะเปลี่ยนสถานะเป็น half-open
- Half-open (ทดลองเปิดรับ): ปล่อยให้คำขอบางส่วนผ่านไปทดสอบ หากคำขอนั้นสำเร็จ วงจรจะกลับมาเป็น Closed แต่ถ้าล้มเหลว ก็จะกลับไป Open อีกครั้ง
การส่งต่อบริบทเทรซ
เมื่อเซอร์วิสของเรายิงคำขอไปยังเซอร์วิสอื่น เราย่อมต้องการให้บริบทการติดตาม (trace context ได้แก่ trace ID, span ID, และ sampling decision) ถูกส่งต่อแนบไปกับคำขอนั้นด้วย นี่คือหัวใจสำคัญที่ช่วยให้คุณสามารถเชื่อมโยงล็อกและสแปน (span) ข้ามพรมแดนระหว่างแต่ละเซอร์วิสได้ และทำให้ระบบ Distributed Tracing เกิดประโยชน์ในการใช้งานจริง ไม่ใช่เป็นเพียงแค่ของประดับ
หากทั้งสองเซอร์วิสใช้งาน OpenTelemetry บริบทของเทรซจะถูกส่งต่อไปทาง HTTP header ชื่อ traceparent (ตามมาตรฐาน W3C Trace Context) ซึ่ง crate อย่าง reqwest-tracing หรือ reqwest-middleware สามารถแทรกเฮดเดอร์นี้ให้อัตโนมัติได้อย่างสะดวกสบาย แต่หากคุณใช้การตั้งค่าที่เรียบง่ายกว่านั้น อย่างน้อยที่สุดก็ควรส่งต่อ request ID ของคุณผ่าน custom header เพื่อให้สามารถนำมาค้นหาจับคู่ล็อกด้วยตนเองได้ คุณจะต้องขอบคุณตัวเองแน่นอนเมื่อต้องตื่นขึ้นมาไล่ตรวจหาปัญหาบน production ตอนตีสอง
#![allow(unused)]
fn main() {
let request_id = "req-abc-123"; // from the inbound request's span
let response = client
.get(url)
.header("x-request-id", request_id)
.send()
.await?;
}
เมื่อไหร่ไม่ควรลองใหม่
ไม่ใช่ทุกข้อผิดพลาดที่จะเหมาะกับการลองใหม่ นี่คือหนึ่งในเรื่องที่ฟังดูเหมือนเข้าใจง่ายเวลาอ่าน แต่จากประสบการณ์จริง ผู้คนมักทำพลาดกันบ่อยมาก การแห่ส่งคำขอลองใหม่อย่างรุนแรงใส่เซอร์วิสที่กำลัง overload อยู่แล้ว มีแต่จะยิ่งทำให้สถานการณ์เลวร้ายลงไปอีก ต่อไปนี้คือสถานการณ์ที่คุณ ไม่ควร ทำการลองใหม่เป็นอันขาด:
- ข้อผิดพลาดฝั่งไคลเอนต์รหัส 4xx (ยกเว้นรหัส 429 Too Many Requests ซึ่งเป็นการแจ้งเตือนอย่างชัดเจนให้คุณเว้นระยะห่างแล้วค่อยส่งใหม่)
- ข้อผิดพลาดที่บ่งชี้ถึงปัญหาถาวร (เช่น ข้อมูลประจำตัวยืนยันตัวตนไม่ถูกต้อง, รีซอร์สถูกลบไปแล้ว, หรือโครงสร้างข้อมูลไม่ตรงกัน)
- เมื่อหมดงบเวลา (deadline) ของการทำงานแล้ว (ไม่มีประโยชน์ที่จะส่งคำขอรอบใหม่ หากฝั่งผู้เรียกเดิมถอดใจและยกเลิกการรอไปแล้ว)
- เมื่อ Circuit Breaker อยู่ในสถานะ Open (เพราะระบบรู้อยู่แล้วว่าปลายทางกำลังมีปัญหา)
หลักการทั่วไปที่ผมยึดถือคือ: ลองใหม่เฉพาะกับความผิดพลาดชั่วคราวโดยใช้ระยะเวลาหน่วงที่เหมาะสม, เคารพ rate limit ของระบบปลายทาง, และให้รีบล้มเหลวโดยเร็ว (fail fast) หากเป็นปัญหาเชิงโครงสร้าง คราวนี้เรามาดูกันว่าเราจะห่อหุ้มตรรกะทั้งหมดนี้ให้ออกมาเป็นโค้ดที่สะอาดเรียบร้อยได้อย่างไร
การห่อไคลเอนต์ขาออก
สำหรับเซอร์วิสปลายทางที่แอปพลิเคชันของคุณจำเป็นต้องเรียกใช้งานอยู่บ่อยครั้ง ผมขอแนะนำให้ห่อหุ้ม reqwest::Client แบบดิบๆ ไว้ภายใน struct ไคลเอนต์โดยเฉพาะ ซึ่ง struct นี้จะทำหน้าที่รวบรวม base URL, กลไกการยืนยันตัวตน, นโยบายการตั้ง timeout, ตรรกะการลองใหม่, และการแปลงข้อผิดพลาดทั้งหมดไว้ในจุดเดียว ให้มองว่านี่คือเวอร์ชันฝั่งขาออกของ repository pattern ที่เราเคยใช้สำหรับจัดการการเข้าถึงฐานข้อมูลนั่นเอง
#![allow(unused)]
fn main() {
pub struct PaymentClient {
http: Client,
base_url: String,
api_key: String,
}
impl PaymentClient {
pub async fn charge(
&self,
amount_cents: i64,
currency: &str,
idempotency_key: &str,
) -> Result<PaymentResult, PaymentError> {
let url = format!("{}/v1/charges", self.base_url);
let response = self.http
.post(&url)
.bearer_auth(&self.api_key)
.header("Idempotency-Key", idempotency_key)
.json(&serde_json::json!({
"amount": amount_cents,
"currency": currency,
}))
.send()
.await
.map_err(PaymentError::Network)?;
match response.status() {
s if s.is_success() => {
let result = response.json().await.map_err(PaymentError::Parse)?;
Ok(result)
}
StatusCode::UNPROCESSABLE_ENTITY => {
let body = response.text().await.unwrap_or_default();
Err(PaymentError::Validation(body))
}
s => Err(PaymentError::Upstream(s)),
}
}
}
}
โครงสร้างเช่นนี้ช่วยให้เซอร์วิสในเลเยอร์โดเมนของเรามีอินเทอร์เฟซที่สะอาดตาและปลอดภัยด้วยระบบชนิดข้อมูล (type-safe) สำหรับติดต่อกับระบบภายนอก โดยช่วยซ่อนรายละเอียดทางเทคนิคของ HTTP เอาไว้เบื้องหลัง ทั้งยังเป็นจุดที่เหมาะสมอย่างยิ่งในการสอดแทรกตรรกะการลองใหม่, ระบบตัดวงจร, และการเก็บเมตริกเพิ่มเติมในอนาคตได้โดยไม่ต้องแตะต้องโค้ดฝั่งผู้เรียกใช้งานเลย จากประสบการณ์ของผม แพตเทิร์นนี้ให้ผลตอบแทนที่คุ้มค่าอย่างรวดเร็ว โดยเฉพาะอย่างยิ่งเมื่อระบบของคุณมี dependency ภายนอกเพิ่มจำนวนมากขึ้นเรื่อยๆ
ไทป์สเตตและแพตเทิร์นระบบชนิดข้อมูลขั้นสูง
ในบท การสร้างแบบจำลองโดเมน เราได้ใช้ newtype เพื่อบังคับใช้อินแวเรียนต์ (invariant) กับค่าแต่ละตัว: เช่น Email จะสร้างขึ้นได้จากสตริงที่เป็นอีเมลที่ถูกต้องเท่านั้น และเมื่อสร้างขึ้นมาได้แล้ว ความถูกต้องของมันก็ได้รับการการันตีทันที คราวนี้เราจะนำแนวคิดดังกล่าวมาต่อยอดไปอีกขั้น แทนที่จะเข้ารหัสระบุว่าค่านั้น คือ อะไร เราจะเข้ารหัสระบุว่าเอนทิตี (entity) กำลังอยู่ ใน สถานะใด และใช้ระบบชนิดข้อมูล (type system) เพื่อควบคุมว่ามีโอเปอเรชันใดบ้างที่สามารถเรียกใช้งานได้ในแต่ละสถานะ
ผลตอบแทนที่ได้คืออะไร? การเปลี่ยนผ่านสถานะ (state transition) ที่ไม่ถูกต้องจะกลายเป็นข้อผิดพลาดตอนคอมไพล์ (compile-time error) ทันที แทนที่จะหลุดรอดไปเป็นบั๊กในตอนรันไทม์
แพตเทิร์นไทป์สเตต
แนวคิดหลักนั้นเรียบง่ายและตรงไปตรงมา: เราจะแทนสถานะของเอนทิตีด้วย type parameter แล้วนิยามเมธอดต่างๆ ให้สามารถเรียกใช้งานได้เฉพาะเมื่อเอนทิตีอยู่ในสถานะที่ถูกต้องเท่านั้น และเมื่อคุณทำการเปลี่ยนผ่านไปยังสถานะใหม่ ค่าอ็อบเจกต์เดิมจะถูกบริโภคไป (consumed) แล้วคุณจะได้รับอ็อบเจกต์ตัวใหม่ที่มี type parameter เปลี่ยนไปตามสถานะนั้นกลับมาแทน เรามาดูกันว่าแพตเทิร์นนี้มีหน้าตาอย่างไรในทางปฏิบัติ
#![allow(unused)]
fn main() {
use std::marker::PhantomData;
// States are zero-sized types. They exist only at compile time.
pub struct Created;
pub struct Paid;
pub struct Shipped;
pub struct Order<State> {
id: Uuid,
customer_id: Uuid,
total_cents: i64,
_state: PhantomData<State>,
}
impl Order<Created> {
pub fn new(customer_id: Uuid, total_cents: i64) -> Self {
Self {
id: Uuid::new_v4(),
customer_id,
total_cents,
_state: PhantomData,
}
}
/// Pay for the order. Consumes the Created order
/// and returns a Paid order.
pub fn pay(self, payment_id: String) -> Order<Paid> {
tracing::info!(order_id = %self.id, "order paid");
Order {
id: self.id,
customer_id: self.customer_id,
total_cents: self.total_cents,
_state: PhantomData,
}
}
}
impl Order<Paid> {
/// Ship the order. Only available on paid orders.
pub fn ship(self, tracking_number: String) -> Order<Shipped> {
tracing::info!(order_id = %self.id, "order shipped");
Order {
id: self.id,
customer_id: self.customer_id,
total_cents: self.total_cents,
_state: PhantomData,
}
}
/// Refund the order. Only available on paid (not yet shipped) orders.
pub fn refund(self) -> Order<Created> {
tracing::info!(order_id = %self.id, "order refunded");
Order {
id: self.id,
customer_id: self.customer_id,
total_cents: self.total_cents,
_state: PhantomData,
}
}
}
impl Order<Shipped> {
pub fn tracking_number(&self) -> &str {
// In a real implementation, this would be stored in the struct.
"tracking info"
}
}
}
ด้วยการออกแบบเช่นนี้ ในกรณีทำงานปกติ (happy path) โค้ดจะคอมไพล์ผ่านได้อย่างราบรื่น:
#![allow(unused)]
fn main() {
let order = Order::new(customer_id, 4999);
let paid_order = order.pay("pay_123".into());
let shipped_order = paid_order.ship("TRACK456".into());
}
แต่หากคุณลองข้ามขั้นตอนใดขั้นตอนหนึ่งดู คอมไพเลอร์จะหยุดคุณไว้ทันที:
#![allow(unused)]
fn main() {
let order = Order::new(customer_id, 4999);
// Error: no method named `ship` found for `Order<Created>`
let shipped = order.ship("TRACK456".into());
}
คอมไพเลอร์สามารถดักจับการเปลี่ยนผ่านสถานะที่ไม่ถูกต้องได้ทันที เพราะเมธอด ship() ถูกนิยามไว้เฉพาะบน Order<Paid> เท่านั้น ไม่ได้มีอยู่บน Order<Created> คุณจึงไม่มีทางจัดส่งออร์เดอร์ที่ยังไม่ได้ชำระเงินได้เลย และระบบชนิดข้อมูลก็คอยบังคับใช้กฎนี้ให้โดยไม่ต้องพึ่งพาการตรวจสอบตอนรันไทม์แม้แต่น้อย ไม่ต้องเขียนคำสั่ง if, ไม่มีการแพนิก (panic), มีเพียงข้อความแจ้งเตือนจากคอมไพเลอร์ที่บอกคุณอย่างชัดเจนว่าคุณทำผิดพลาดตรงไหน
การประยุกต์ในโลกจริง: ไลฟ์ไซเคิลการเชื่อมต่อ
จุดที่แพตเทิร์นนี้ฉายแววโดดเด่นอย่างแท้จริงคือ การพัฒนาโปรโตคอลเครือข่ายที่การเชื่อมต่อต้องเคลื่อนผ่านแต่ละเฟสที่มีขอบเขตความสามารถแตกต่างกัน ผมเคยมีส่วนร่วมในโปรเจกต์ mozilla-services/autopush-rs ซึ่งนำแนวทางนี้ไปประยุกต์ใช้กับการจัดการการเชื่อมต่อ WebSocket: โดย UnidentifiedClient จะทำหน้าที่จัดการขั้นตอน handshake เริ่มต้น และเมื่อได้รับข้อความ Hello ที่ถูกต้อง มันจะเปลี่ยนผ่านสถานะไปเป็น WebPushClient ซึ่งมีสิทธิ์เข้าถึงข้อมูลการสมัครรับข้อมูล (subscription) และแชนเนลสำหรับส่ง notification ของผู้ใช้
นี่คือตัวอย่างแบบย่อของแพตเทิร์นดังกล่าว:
#![allow(unused)]
fn main() {
pub struct Unauthenticated;
pub struct Authenticated;
pub struct Connection<State> {
stream: WebSocketStream,
remote_addr: SocketAddr,
_state: PhantomData<State>,
}
impl Connection<Unauthenticated> {
pub fn new(stream: WebSocketStream, remote_addr: SocketAddr) -> Self {
Self {
stream,
remote_addr,
_state: PhantomData,
}
}
/// Perform the authentication handshake.
/// Consumes the unauthenticated connection and returns
/// an authenticated one, or an error if auth fails.
pub async fn authenticate(
mut self,
timeout: Duration,
) -> Result<(Connection<Authenticated>, UserId), AuthError> {
let hello = tokio::time::timeout(timeout, self.read_hello())
.await
.map_err(|_| AuthError::Timeout)?
.map_err(AuthError::Protocol)?;
let user_id = validate_credentials(&hello)?;
Ok((
Connection {
stream: self.stream,
remote_addr: self.remote_addr,
_state: PhantomData,
},
user_id,
))
}
}
impl Connection<Authenticated> {
/// Send a push notification. Only available on authenticated connections.
pub async fn send_notification(&mut self, notif: &Notification) -> Result<(), SendError> {
self.stream.send(notif.to_message()).await?;
Ok(())
}
/// Graceful close with notification draining.
pub async fn shutdown(mut self, reason: CloseReason) {
// Drain any remaining notifications before closing.
self.drain_pending_notifications().await;
self.stream.close(reason.into()).await.ok();
}
}
}
ข้อคิดสำคัญที่ได้จาก autopush-rs คือ กลยุทธ์การจัดการข้อผิดพลาดจะมีความแตกต่างกันอย่างสิ้นเชิงระหว่างสองเฟสนี้ โดยในระหว่างเฟสที่ยังไม่ผ่านการยืนยันตัวตน (unauthenticated) หากเกิดข้อผิดพลาดของโปรโตคอลขึ้น เราก็เพียงแค่ตัดการเชื่อมต่อของไคลเอนต์ทิ้งไป (เนื่องจากยังไม่มีรีซอร์สใดที่ต้องทำความสะอาด) แต่เมื่อเข้าสู่เฟสที่ยืนยันตัวตนสำเร็จแล้ว (authenticated) หากเกิดข้อผิดพลาดขึ้น ระบบจะต้องกระตุ้นให้เกิด graceful shutdown เพื่อระบาย notification ที่ยังค้างอยู่ทั้งหมดออกไปให้ครบก่อนที่จะปิดการเชื่อมต่อ ซึ่งแพตเทิร์น typestate ช่วยแปลงความแตกต่างทางพฤติกรรมนี้ให้กลายเป็นกฎเชิงโครงสร้างได้อย่างสมบูรณ์แบบ: เพราะเมธอด shutdown พร้อมตรรกะระบายข้อความจะมีอยู่เฉพาะบน Connection<Authenticated> เท่านั้น ทำให้คุณไม่มีทางเผลอเรียกใช้งานมันผิดเฟสได้อย่างแน่นอน
แพตเทิร์นบิลเดอร์ในฐานะไทป์สเตตแบบเสื่อม
คุณอาจกำลังใช้งาน typestate ในรูปแบบที่เรียบง่ายอยู่แล้วโดยไม่รู้ตัว: นั่นคือ Builder Pattern ที่มีฟิลด์บังคับ (mandatory fields) โดยการใช้ type parameter ที่แตกต่างกันในแต่ละสเตจของบิลเดอร์ เราจะสามารถรับประกันได้ว่าฟิลด์ที่จำเป็นทั้งหมดจะต้องถูกตั้งค่าให้เรียบร้อยเสียก่อน เมธอด build() จึงจะปรากฏขึ้นมาให้เรียกใช้งานได้
#![allow(unused)]
fn main() {
pub struct NoAddr;
pub struct HasAddr;
pub struct ServerBuilder<AddrState> {
addr: Option<SocketAddr>,
max_connections: usize,
_state: PhantomData<AddrState>,
}
impl ServerBuilder<NoAddr> {
pub fn new() -> Self {
Self {
addr: None,
max_connections: 100,
_state: PhantomData,
}
}
pub fn bind(self, addr: SocketAddr) -> ServerBuilder<HasAddr> {
ServerBuilder {
addr: Some(addr),
max_connections: self.max_connections,
_state: PhantomData,
}
}
}
impl ServerBuilder<HasAddr> {
/// build() is only available after bind() has been called.
pub fn build(self) -> Server {
Server {
addr: self.addr.unwrap(), // Safe: guaranteed by typestate.
max_connections: self.max_connections,
}
}
}
// Optional settings are available in any state.
impl<S> ServerBuilder<S> {
pub fn max_connections(mut self, n: usize) -> Self {
self.max_connections = n;
self
}
}
}
สิ่งนี้ช่วยรับประกันในระดับคอมไพล์ไทม์ว่าคุณจะไม่สามารถเรียก build() ได้เลยหากยังไม่ได้เรียก bind() ก่อน และหากคุณฝืนลองทำ คอมไพเลอร์จะฟ้องข้อผิดพลาดอย่างชัดเจนว่า: “no method named build found for ServerBuilder<NoAddr>” นี่คือเสน่ห์ที่ผมประทับใจใน Rust ที่สามารถเปลี่ยนสิ่งที่ในภาษาอื่นๆ มักจะกลายเป็น panic หรือแครชตอนรันไทม์ ให้กลายมาเป็นสิ่งที่คอมไพเลอร์ดักจับให้เราได้อย่างแม่นยำตั้งแต่แรก
เมื่อไหร่ไทป์สเตตคุ้มกับความซับซ้อน
อย่างไรก็ดี ผมไม่อยากให้คุณเข้าใจผิดว่าเราควรหยิบ typestate ไปใช้ในทุกๆ ที่ เพราะมันย่อมเพิ่มความซับซ้อนให้กับ type signature ของคุณ และอาจทำให้การทำงานพื้นฐานบางอย่างทำได้ยากขึ้น (เช่น การจัดเก็บคอลเลกชันของเอนทิตีที่คละสถานะกัน) จากประสบการณ์ของผม typestate จะคุ้มค่าเป็นพิเศษเมื่อ:
- การเปลี่ยนผ่านสถานะที่ผิดพลาดอาจก่อให้เกิดช่องโหว่ด้านความปลอดภัยหรือทำให้ข้อมูลเสียหาย (data corruption)
- มีจำนวนสถานะค่อนข้างน้อย และการเปลี่ยนผ่านสถานะมีความชัดเจนในรูปแบบเส้นตรง (linear transitions)
- โค้ดที่จัดการการเปลี่ยนสถานะมีความสำคัญต่อประสิทธิภาพสูง จนคุณต้องการต้นทุนตอนรันไทม์เป็นศูนย์ (zero runtime overhead)
- ไทป์เหล่านั้นถูกจำกัดขอบเขตการใช้งานอยู่ภายในโมดูลหรือซับซิสเต็มเดียว ทำให้ generic parameter ไม่แพร่กระจายจนรกโค้ดส่วนอื่น
ในทางกลับกัน คุณควรเลือกใช้ State Machine แบบ enum ทั่วไปเมื่อ:
- คุณจำเป็นต้องเก็บเอนทิตีที่มีสถานะแตกต่างกันไว้ในคอลเลกชันเดียวกัน (เช่น
Vec<Order>ที่บางตัวจ่ายเงินแล้วและบางตัวจัดส่งแล้ว) - จำนวนสถานะมีมาก หรือกราฟการเปลี่ยนสถานะมีความซับซ้อนและวนลูปไปมา
- สถานะจำเป็นต้องถูก serialize ลงฐานข้อมูล หรือ deserialize จาก API response
- สถานะถูกกำหนดขึ้นในตอนรันไทม์จากข้อมูลภายนอกที่ไม่สามารถล่วงรู้ได้ในตอนคอมไพล์
สิ่งที่ผมพบในการทำงานจริงคือ หลายระบบเลือกใช้งานร่วมกันทั้งสองรูปแบบ: ใช้ typestate สำหรับตรรกะแกนกลางภายในที่การเปลี่ยนสถานะมีความสำคัญต่อความถูกต้องอย่างยิ่งยวด และห่อหุ้มด้วย enum สำหรับการจัดเก็บข้อมูลถาวร (persistence) และการเชื่อมต่อกับระบบภายนอก โดย typestate จะช่วยคุมความถูกต้องในโค้ดตรรกะ ส่วน enum จะมอบความยืดหยุ่นสำหรับการจัดเก็บและการ serialize ซึ่งเราจะได้เห็นการประยุกต์ใช้สิ่งนี้กันมากขึ้นเมื่อเข้าสู่เลเยอร์การจัดเก็บข้อมูล
การเชื่อมโยงกลับสู่การสร้างแบบจำลองโดเมน
หากคุณเริ่มสังเกตเห็นทิศทางบางอย่างที่สอดคล้องกันที่นี่ คุณคิดถูกแล้ว เพราะแพตเทิร์น typestate แท้จริงแล้วก็คือการต่อยอดปรัชญา “parse, don’t validate” จากบท การสร้างแบบจำลองโดเมน ออกไปอย่างเป็นธรรมชาตินั่นเอง ในขณะที่ newtype ช่วยทำให้ค่าที่ไม่ถูกต้องไม่สามารถเกิดขึ้นได้ในระบบ (Email เก็บได้เฉพาะสตริงที่ถูกต้องเท่านั้น) ตัว typestate ก็ช่วยทำให้การเปลี่ยนผ่านสถานะที่ไม่ถูกต้องไม่สามารถเกิดขึ้นได้ในระบบเช่นเดียวกัน (Order<Created> จะไม่มีเมธอด ship() ให้เรียก) ทั้งสองแพตเทิร์นต่างอาศัยระบบชนิดข้อมูลอันทรงพลังของ Rust เพื่อย้ายการการันตีความถูกต้องจากการตรวจสอบตอนรันไทม์ มาเป็นการบังคับใช้ตั้งแต่ตอนคอมไพล์ และทั้งคู่ต่างให้ผลตอบแทนที่คุ้มค่าสูงสุดในส่วนของโค้ดที่หากเกิดข้อผิดพลาดขึ้นมาจะสร้างความเสียหายอย่างรุนแรง ในบทถัดไป เราจะดูวิธีจัดโครงสร้างไทป์ข้อผิดพลาดของเรา เพื่อที่ว่าเมื่อมีอะไรผิดพลาดขึ้นมาจริงๆ ในตอนรันไทม์ เราจะสามารถรับมือและจัดการกับมันได้อย่างเป็นระบบและหมดจด
เวิร์กโฟลว์การพัฒนาร่วมกับ AI
หากคุณเคยพัฒนาระบบร่วมกับ AI coding agent คุณอาจสังเกตเห็นว่าพวกมันเก่งมากเรื่องการปั่นโค้ดออกมาอย่างรวดเร็ว แต่กลับแย่มากในการทำความเข้าใจกฎเฉพาะ ของ โปรเจกต์คุณ บทนี้จะมาช่วยเชื่อมช่องว่างดังกล่าว เราจะมาดูวิธีนำหลักการจากคู่มือเล่มนี้ไปแปลงเป็นคำสั่งระดับรีโพสิทอรีที่เอเจนต์ AI (Claude Code, Codex, Cursor, Aider) สามารถนำไปใช้งานได้อย่างมีประสิทธิภาพ เพื่อให้พวกมันเลิกคาดเดาและเริ่มปฏิบัติตามสถาปัตยกรรมของคุณอย่างถูกต้อง
ปัญหาของการวางคู่มือทั้งเล่มลงไป
ผมเข้าใจดีครับว่าแรงดึงดูดใจมันสูงมาก หลายคนเลือกคัดลอกเนื้อหาคู่มือทั้งเล่ม วางลงในหน้าแชท แล้วสั่งให้เอเจนต์ “สร้างแอป Rust ขึ้นมา” ผมเองก็เคยทำแบบนั้น ผลลัพธ์ที่ได้คือ… ไม่ค่อยน่าประทับใจเท่าไหร่ เพราะโมเดลแยกแยะไม่ออกว่าอะไรคือกฎเหล็กที่ห้ามละเมิด และอะไรเป็นเพียงคำแนะนำเสริม มันจึงเลือกทำเฉพาะส่วนที่ดูง่ายที่สุดแล้วมองข้ามส่วนที่เหลือไปทั้งหมด
สิ่งที่ผมพบว่าได้ผลดีกว่ามาก คือการกลั่นกรองกฎเหล็กที่คุณยอมให้ผิดไม่ได้ลงในไฟล์ถาวรของรีโพสิทอรี ซึ่งเอเจนต์จะโหลดขึ้นมาอัตโนมัติเมื่อเริ่มต้นแต่ละเซสชัน จากนั้นจึงป้อนความรู้เชิงขั้นตอน (เช่น วิธีเพิ่มเอนด์พอยต์ วิธีเขียนไมเกรชัน) ในรูปแบบของสกิล (skills) แยกเป็นเรื่องๆ เพื่อให้เอเจนต์ดึงมาใช้เมื่อจำเป็นเท่านั้น มาดูวิธีตั้งค่าสิ่งนี้กันครับ
โครงสร้างไฟล์คำสั่งในรีโพสิทอรี
เครื่องมือเขียนโค้ดด้วย AI ส่วนใหญ่ในปัจจุบันรองรับคำสั่งแบบไฟล์ถาวร (persistent instructions) ซึ่งจะถูกโหลดขึ้นมาโดยอัตโนมัติเมื่อเอเจนต์เริ่มเซสชันการทำงาน:
- Claude Code อ่าน
CLAUDE.mdที่รากของรีโพสิทอรี รวมถึง.claude/rules/สำหรับกฎที่จำกัดขอบเขตเฉพาะส่วน - Codex อ่าน
AGENTS.mdที่รากของรีโพสิทอรี รวมถึงไฟล์AGENTS.mdที่ซ้อนอยู่ในซับไดเรกทอรีต่างๆ - Cursor อ่าน
.cursor/rules/หรือAGENTS.md - Aider ใช้ repo map เพื่อทำความเข้าใจโครงสร้าง และสามารถกำหนดไฟล์ข้อตกลง (conventions) ได้
แม้ชื่อไฟล์จะแตกต่างกัน แต่แนวคิดเบื้องหลังนั้นเหมือนกัน คือคำสั่งที่กระชับ ตรงประเด็น และคงทนถาวร ซึ่งฝังอยู่ในรีโพสิทอรีและถูกโหลดขึ้นมาทุกครั้งที่เริ่มเซสชัน นี่คือที่จัดเก็บกฎเกณฑ์ที่ดีกว่าการพิมพ์ลงในแชทแล้วคุณอาจลืมแปะในครั้งถัดไปอย่างแน่นอน
ในรีโพสิทอรีนี้มีไดเรกทอรี templates/ ที่เตรียมไฟล์คำสั่งพร้อมใช้งานไว้ให้แล้ว คุณสามารถคัดลอกไฟล์เหล่านี้ลงในโปรเจกต์ของคุณและปรับแต่งให้เข้ากับโค้ดเบสของคุณได้ทันที
คำสั่งระดับราก
ไฟล์ AGENTS.md (หรือ CLAUDE.md) ที่รูทของโปรเจกต์ ควรบรรจุเฉพาะกฎที่ต้องใช้ร่วมกันในทุกเซสชันและทุกไฟล์เท่านั้น ผมแนะนำให้รักษาความยาวไว้ไม่เกิน 40 บรรทัด ลองมองว่ามันคือสิ่งที่คุณจะบอกสมาชิกใหม่ในทีมตั้งแต่วันแรกที่เริ่มงาน:
- โครงสร้างเลเยอร์ของโปรเจกต์และกฎทิศทางของดีเพนเดนซี
- กฎสไตล์โค้ดแบบเข้มงวด (ห้าม unwrap ในแฮนด์เลอร์, ใช้ newtype สำหรับค่าโดเมน ฯลฯ)
- คำสั่งตรวจสอบความถูกต้องที่ใช้นิยามว่างาน “เสร็จสมบูรณ์” (done)
- การชี้ทางไปยังไฟล์คำสั่งย่อยสำหรับกฎเฉพาะของแต่ละเลเยอร์
templates/
AGENTS.md # Root rules (copy to your repo root)
จงตั้งใจรักษาไฟล์นี้ให้มีขนาดกะทัดรัดเข้าไว้ ส่วนกฎเกณฑ์ใดที่เจาะจงเฉพาะเลเยอร์ ให้แยกไปใส่ไว้ในไฟล์ย่อยที่ซ้อนอยู่ด้านใน ซึ่งเราจะมาดูกันในหัวข้อถัดไป
คำสั่งระดับเลเยอร์ย่อย
แต่ละเลเยอร์ของสถาปัตยกรรมจะมีไฟล์คำสั่งเป็นของตัวเองพร้อมกฎเฉพาะสำหรับเลเยอร์นั้นๆ วิธีนี้ช่วยให้เอเจนต์โหลดเฉพาะคำแนะนำที่เกี่ยวข้องเมื่อกำลังแก้ไขไฟล์ในไดเรกทอรีดังกล่าว โดยไม่ต้องถูกถล่มด้วยกฎฐานข้อมูลในขณะที่กำลังเขียนแฮนด์เลอร์
templates/
src/http/AGENTS.md # Handler, DTO, middleware, routing rules
src/domain/AGENTS.md # Model, service, port, error rules
src/infra/db/AGENTS.md # Repository, query, migration rules
คำสั่งของเลเยอร์ HTTP จะครอบคลุมขีดจำกัดความยาวของแฮนด์เลอร์ ข้อตกลงการใช้ extractor ลำดับของมิดเดิลแวร์ และกฎการสร้าง DTO ส่วนคำสั่งของเลเยอร์โดเมนจะบังคับใช้กฎห้ามพึ่งพาเฟรมเวิร์กภายนอก (zero-framework-dependency) รวมถึงแพตเทิร์น newtype/คอนสตรักเตอร์ที่เราได้พูดถึงไปก่อนหน้านี้ และคำสั่งของเลเยอร์ฐานข้อมูลจะครอบคลุมแพตเทิร์นการคิวรี การแปลงแถวข้อมูล (row) ไปสู่โดเมน และข้อตกลงในการทำไมเกรชัน
สกิลสำหรับเวิร์กโฟลว์แบบขั้นตอน
กฎเกณฑ์ (rules) ทำหน้าที่บอกเอเจนต์ว่า ต้องทำอะไร ส่วนสกิล (skills) ทำหน้าที่บอกมันว่า ต้องทำอย่างไร คุณอาจสงสัยว่าทำไมความแตกต่างนี้ถึงมีความสำคัญ จากประสบการณ์ของผม เอเจนต์ทำตามขั้นตอนแบบเป็นลำดับได้เก่งอย่างน่าทึ่ง แต่กลับแย่มากในการคิดค้นกระบวนการขึ้นมาใหม่ตั้งแต่ต้น สกิลจึงเปรียบเสมือนสูตรสำเร็จสำหรับงานทั่วไปที่เอเจนต์สามารถหยิบมาปฏิบัติตามทีละขั้นเมื่อต้องการ
templates/
.agents/skills/add-endpoint/SKILL.md # Domain -> DB -> Handler -> Test flow
.agents/skills/add-migration/SKILL.md # Migration creation and verification
.agents/skills/review-pr/SKILL.md # Architecture and security review checklist
สกิล add-endpoint จะนำทางคุณผ่านเวอร์ติคอลสไลซ์ทั้งเส้น: ตั้งแต่นิยามชนิดข้อมูลโดเมน สร้างไมเกรชัน อิมพลีเมนต์เมธอดของรีพอสิทอรี ใส่ตรรกะทางธุรกิจในเซอร์วิส เขียน DTO และแฮนด์เลอร์ ลงทะเบียนเส้นทาง เขียนแบบทดสอบ เพิ่ม tracing ไปจนถึงการสั่งรันการตรวจสอบความถูกต้อง นี่คือขั้นตอนที่เราต้องการให้เอเจนต์ทำตามทุกครั้งเมื่อเพิ่มเอนด์พอยต์ API ใหม่ ซึ่งสะท้อนขั้นตอนที่เราจะลงมือทำด้วยตนเองอย่างแท้จริง
ส่วนสกิล review-pr คือเช็กลิสต์ตรวจทานที่ครอบคลุมด้านสถาปัตยกรรม (ทิศทางของดีเพนเดนซี, ความหนาของโค้ดในแฮนด์เลอร์) ความถูกต้อง (ห้าม unwrap, การแปลงข้อผิดพลาดอย่างเหมาะสม) ฐานข้อมูล (คิวรีแบบมีพารามิเตอร์, การแปลงข้อมูลด้วย TryFrom) ความปลอดภัย (การตรวจสอบความถูกต้องของอินพุต, ห้ามมีข้อมูลลับหลุดในล็อก) การทดสอบ (ครอบคลุมทั้ง happy path และ error path) และการปฏิบัติการจริง (tracing, ห้ามมีบล็อกกิ้งคอล, การตั้งค่าการหมดเวลาสำหรับการเชื่อมต่อไปภายนอก)
เช็กลิสต์สำหรับการตรวจทานโดยมนุษย์
แม้ว่าเอเจนต์ AI จะเป็นผู้เขียนโค้ด แต่คุณก็ยังจำเป็นต้องมีมนุษย์คอยตรวจทานอยู่เสมอ อย่ามองข้ามขั้นตอนนี้เป็นอันขาด เช็กลิสต์ฟีเจอร์นี้จะมอบแนวทางการตรวจทานที่มีโครงสร้างชัดเจนให้แก่คุณ:
templates/
docs/checklists/feature.md # End-to-end feature implementation checklist
ลูปการสนทนาสามเฟส
นี่คือเวิร์กโฟลว์ที่ผมตกผลึกหลังจากการลองผิดลองถูกมานับครั้งไม่ถ้วน มันคือลูปสามเฟสที่ได้ผลดีเยี่ยม เพราะมันบีบให้เอเจนต์ต้องคิดตามลำดับเดียวกับวิธีที่มนุษย์เราคิด นั่นคือ กำหนดขอบเขตก่อน แล้วจึงลงมือเขียนโค้ด จากนั้นค่อยตรวจทาน
เฟส 1: วางแผน (Plan). สั่งให้เอเจนต์อ่านไฟล์คำสั่ง สรุปข้อจำกัดทางสถาปัตยกรรมที่เกี่ยวข้อง เสนอเวอร์ติคอลสไลซ์ที่เล็กที่สุดที่จะเริ่มทำ และระบุรายการไฟล์ทั้งหมดที่วางแผนจะแก้ไข อย่าเพิ่งปล่อยให้มันเขียนโค้ดในขั้นตอนนี้ แม้จะดูยุ่งยากและเสียเวลาไปบ้าง แต่ขั้นตอนนี้ช่วยดักจับสมมติฐานที่ผิดพลาดได้ก่อนที่มันจะกลายสภาพเป็นโค้ดที่บกพร่อง
เฟส 2: นำไปใช้ (Implement). ให้เอเจนต์ลงมือเขียนโค้ดทีละสไลซ์ โดยสั่งให้มันหยุดเมื่อโค้ดคอมไพล์ผ่านและรันเทสต์ผ่านเรียบร้อย จากนั้นจึงแสดงให้คุณเห็นว่ามีอะไรเปลี่ยนแปลงไปบ้างและยังเหลือส่วนใดที่ต้องทำต่อ
เฟส 3: ตรวจทาน (Review). สั่งให้เอเจนต์ตรวจทาน diff ของตัวเองเทียบกับเช็กลิสต์การตรวจทาน ให้มันชี้จุดที่สถาปัตยกรรมเริ่มเบี่ยงเบน ชนิดข้อมูลภายในที่รั่วไหล เทสต์ที่ขาดหายไป โค้ดที่อาจบล็อกการทำงาน และช่องโหว่ด้านความปลอดภัย พร้อมทั้งเสนอการแก้ไขที่เจาะจงและกระทบน้อยที่สุด
คุณจะประหลาดใจว่าผลลัพธ์ที่ได้นั้นดีกว่าการสั่งด้วยพรอมพ์ปลายเปิดเพียงประโยคเดียวมากแค่ไหน การบีบให้ทำงานตามเฟสเช่นนี้ช่วยป้องกันไม่ให้เอเจนต์เตลิดออกนอกลู่นอกทาง ไปสร้างสิ่งที่คอมไพล์ผ่านแต่ฉีกกฎสถาปัตยกรรมของคุณทิ้งไปครึ่งเล่ม
อัปเกรดการแก้ไขให้เป็นความทรงจำของรีโพสิทอรี
เมื่อเอเจนต์ทำผิดพลาดในจุดเดิมซ้ำสอง (และเชื่อเถอะว่ามันจะทำแน่ๆ ไม่ว่าจะเป็นการปล่อยให้ชนิดข้อมูลฐานข้อมูลรั่วเข้าไปใน API, การฝัง SQL ไว้ในแฮนด์เลอร์ หรือลืมใส่ instrumentation สำหรับ tracing) อย่าเพียงแค่ทักท้วงและแก้ไขในแชทเท่านั้น แต่จงนำบทเรียนนั้นไปอัปเดตลงในไฟล์คำสั่งระดับรูทหรือไฟล์คำสั่งย่อยทันที เซสชันถัดไปจะเริ่มทำงานได้อย่างฉลาดขึ้น เพราะการแก้ไขดังกล่าวได้กลายเป็นส่วนหนึ่งของบริบทถาวรประจำโปรเจกต์ไปแล้ว
นี่คือจุดกำเนิดของคุณค่าแบบทบต้นอย่างแท้จริง เมื่อเวลาผ่านไป ไฟล์คำสั่งของคุณจะค่อยๆ วิวัฒนาการกลายเป็นมาตรฐานของทีมที่กระชับ แม่นยำ และผ่านการพิสูจน์ใช้งานจริง สิ่งที่ผมค้นพบคือหลังจากผ่านไปเพียงไม่กี่สัปดาห์ ทั้งมนุษย์และเอเจนต์จะปฏิบัติตามกฎเกณฑ์ชุดเดียวกันอย่างสม่ำเสมอ ซึ่งนั่นคือหัวใจสำคัญที่สุดของเรื่องนี้
เริ่มต้นใช้งาน
- คัดลอกเนื้อหาทั้งหมดในไดเรกทอรี
templates/ลงในโปรเจกต์ Rust ของคุณ - เปลี่ยนชื่อไฟล์
AGENTS.mdเป็นCLAUDE.mdหากคุณใช้ Claude Code (หรือจะเก็บไว้ทั้งสองชื่อก็ได้ เพราะไม่มีความขัดแย้งกัน) - ปรับแต่งกฎเกณฑ์ให้เข้ากับโปรเจกต์ของคุณ โดยแก้ไขพาธของเลเยอร์ต่างๆ และใส่ข้อตกลงเฉพาะตัวของโปรเจกต์เข้าไป
- ย้ายตำแหน่งไฟล์คำสั่งย่อยให้ตรงกับโครงสร้างไดเรกทอรี
src/ที่แท้จริงของคุณ - เริ่มต้นเซสชันแชทและสั่งให้เอเจนต์อ่านไฟล์คำสั่งของมันก่อนเริ่มลงมือทำงานใดๆ เสมอ
ขั้นตอนสุดท้ายนี้สำคัญเป็นอย่างยิ่ง หากคุณไม่สั่งให้เอเจนต์อ่านคำสั่งของมันก่อน มันจะมองข้ามกฎทั้งหมดไปอย่างหน้าตาเฉยแล้วทำสิ่งใดก็ตามที่มันอยากทำ เมื่อคุณเซ็ตเวิร์กโฟลว์นี้จนเข้าที่เข้าทางแล้ว คุณจะพบว่าเอเจนต์จะกลายเป็นผู้ร่วมงานที่สร้างประโยชน์ได้อย่างแท้จริง แทนที่จะเป็นเพียงเครื่องกำเนิดโค้ดที่คุณต้องคอยตามเช็ดตามล้างอยู่ตลอดเวลา
ตารางอ้างอิงเครต
ตลอดทั้งเล่มนี้ เราดึงเครตเข้ามาใช้งานอยู่ไม่น้อย หากคุณเคยนึกสงสัยว่า “เดี๋ยว เครตตัวนั้นชื่ออะไรนะ” หน้านี้คือคู่มืออ้างอิงที่คุณสามารถย้อนกลับมาดูได้เสมอ ผมได้จัดหมวดหมู่ทุกอย่างตามขอบเขตการใช้งาน (concern) เพื่อให้คุณค้นหาสิ่งที่ต้องการได้อย่างรวดเร็ว พร้อมทั้งเข้าใจว่าเหตุใดเครตเหล่านี้จึงถูกเลือกเข้ามาอยู่ในสแตกของเรา
เฟรมเวิร์กหลัก
| Crate | Purpose | Notes |
|---|---|---|
| axum | เฟรมเวิร์กสำหรับการเราต์ HTTP, ตัวแยกข้อมูล (extractors) และแฮนด์เลอร์ | รากฐานหลักของระบบ ใช้ร่วมกับฟีเจอร์ macros สำหรับ #[debug_handler] |
| tokio | รันไทม์ async | ใช้ features = ["full"] ยกเว้นในกรณีที่คุณต้องการลดขนาดดีเพนเดนซีให้เหลือน้อยที่สุด |
| tower | นามธรรมและยูทิลิตี้สำหรับมิดเดิลแวร์ | จัดเตรียม ServiceBuilder, ServiceExt (สำหรับ oneshot ในการทดสอบ) และเลเยอร์ที่ประกอบต่อกันได้ |
| tower-http | มิดเดิลแวร์เฉพาะสำหรับ HTTP | CORS, การบีบอัดข้อมูล, tracing, การหมดเวลา (timeouts), หมายเลขคำขอ (request IDs), การจำกัดขนาดบอดี้ และอื่นๆ โดยเปิดใช้ฟีเจอร์ได้ตามต้องการ |
| hyper | อิมพลีเมนเทชันพื้นฐานของ HTTP | แทบจะไม่ได้เรียกใช้ hyper โดยตรงเมื่อพัฒนาบน Axum แต่มันคือเอ็นจิน HTTP ตัวจริงที่ขับเคลื่อนอยู่เบื้องหลัง |
การซีเรียลไลซ์และข้อมูล
| Crate | Purpose | Notes |
|---|---|---|
| serde | เฟรมเวิร์กสำหรับการซีเรียลไลซ์ | ใช้ features = ["derive"] สำหรับแมโคร #[derive(Serialize, Deserialize)] |
| serde_json | การซีเรียลไลซ์และดีซีเรียลไลซ์ JSON | ตัวแยกข้อมูล Json ของ Axum ทำงานโดยใช้ตัวนี้อยู่เบื้องหลัง |
| uuid | การสร้างและการพาร์ส UUID | ใช้ features = ["v4", "serde"] สำหรับการสุ่ม UUID ที่รองรับการทำงานร่วมกับ serde |
| chrono | การจัดการวันและเวลา | ใช้ features = ["serde"] สำหรับการซีเรียลไลซ์ แนะนำให้ใช้ DateTime<Utc> สำหรับการเก็บ timestamp |
ฐานข้อมูล
| Crate | Purpose | Notes |
|---|---|---|
| sqlx | การทำงานกับ SQL แบบ async พร้อมการตรวจสอบความถูกต้องตั้งแต่ตอนคอมไพล์ | ตัวเลือกอันดับหนึ่งสำหรับโปรเจกต์ Axum ส่วนใหญ่ รองรับทั้ง PostgreSQL, MySQL และ SQLite |
| diesel | ORM และตัวสร้างคิวรีที่ปลอดภัยต่อชนิดข้อมูล (type-safe) | เติบโตเต็มที่และผ่านการทดสอบมาอย่างยาวนาน ใช้ diesel-async สำหรับการรองรับ async |
| sea-orm | ORM แบบ async สไตล์ ActiveRecord | น่าสนใจเป็นอย่างยิ่งหากการเขียน Raw SQL ดูยุ่งยากซับซ้อนเกินไปสำหรับความต้องการของคุณ |
| axum-sqlx-tx | ทรานแซกชัน SQLx ที่ผูกขอบเขตกับแต่ละคำขอ (request-scoped) | เปิดทรานแซกชันให้อัตโนมัติในแต่ละคำขอ จากนั้นจะ commit หรือ rollback ตามสถานะการตอบกลับของการร้องขอนั้น |
การจัดการข้อผิดพลาด
| Crate | Purpose | Notes |
|---|---|---|
| thiserror | แมโคร derive สำหรับสร้างชนิดข้อมูลข้อผิดพลาดที่กำหนดขึ้นเอง | เราใช้สิ่งนี้สำหรับข้อผิดพลาดในฝั่งโดเมนและ enum AppError ของเราที่จำเป็นต้อง pattern match แยกตามวาเรียนต์ |
| anyhow | ชนิดข้อมูลข้อผิดพลาดที่ยืดหยุ่นพร้อมการต่อบริบท (context chaining) | เหมาะอย่างยิ่งสำหรับวาเรียนต์แบบครอบจักรวาลอย่าง Internal และในโค้ดส่วนโครงสร้างพื้นฐาน อย่าลังเลที่จะใช้ .context() เพื่อบอกที่มาที่ไป |
การตรวจสอบความถูกต้อง
| Crate | Purpose | Notes |
|---|---|---|
| validator | การตรวจสอบความถูกต้องของอินพุตโดยใช้ derive | รองรับ email, url, length, range ตลอดจนตัวตรวจสอบแบบกำหนดเอง (custom validators) |
| garde | ตัวเลือกการตรวจสอบความถูกต้องทางเลือกที่ใช้ const generics | มิติใหม่ที่ต่อยอดจาก validator พร้อมรูปแบบ API ที่ทันสมัยและแตกต่างออกไป |
| axum-valid | ตัวแยกข้อมูล (extractors) ที่ตรวจสอบความถูกต้องสำเร็จรูปสำหรับ Axum | ทำงานร่วมกับ validator, garde และ validify ได้อย่างแนบเนียน ช่วยให้คุณไม่ต้องเขียนตัวแยกข้อมูลเอง |
การยืนยันตัวตนและความปลอดภัย
| Crate | Purpose | Notes |
|---|---|---|
| jsonwebtoken | การเข้ารหัสและถอดรหัส JWT | ตัวเลือกมาตรฐานสำหรับการยืนยันตัวตนด้วย JWT ใน Rust |
| argon2 | การแฮชรหัสผ่าน | สิ่งที่ผมแนะนำสำหรับการแฮชรหัสผ่านในปัจจุบัน เหมาะสำหรับใช้แทน bcrypt ในโปรเจกต์ยุคใหม่ |
| axum-login | การยืนยันตัวตนผ่านระบบเซสชัน | เหมาะสำหรับเว็บแอปพลิเคชันแบบดั้งเดิมที่ใช้การจัดการเซสชันที่ฝั่งเซิร์ฟเวอร์ |
| axum-csrf-sync-pattern | การป้องกัน CSRF | อิมพลีเมนต์ตามมาตรฐาน OWASP Synchronizer Token Pattern |
| tower-governor | การจำกัดอัตราการเรียกใช้งาน (rate limiting) | การจำกัดอัตราการเรียกใช้งานแบบราย IP โดยใช้อัลกอริทึม governor |
| tower-sessions | มิดเดิลแวร์สำหรับจัดการเซสชัน | จัดการเซสชันฝั่งเซิร์ฟเวอร์พร้อมแบ็กเอนด์ที่สามารถสลับเปลี่ยนได้ตามต้องการ |
การตั้งค่า
| Crate | Purpose | Notes |
|---|---|---|
| config | การโหลดการตั้งค่าแบบแบ่งเลเยอร์ (layered configuration) | รองรับทั้งการอ่านจากไฟล์, ตัวแปรสภาพแวดล้อม และหลากหลายรูปแบบไฟล์ |
| dotenvy | การโหลดค่าจากไฟล์ .env | เครตที่ฟอร์กมาจาก dotenv ดั้งเดิม ควรเรียกใช้ .ok() แทน .unwrap() เพื่อไม่ให้ระบบหยุดทำงานเมื่อขึ้น production |
| secrecy | การปกป้องข้อมูลที่ละเอียดอ่อน | ห่อหุ้มข้อมูลลับด้วย SecretString ซึ่งจะช่วยซ่อนค่าดังกล่าวใน debug log และล้างข้อมูลออกจากหน่วยความจำทันทีเมื่อถูก drop |
การสังเกตการณ์ (Observability)
| Crate | Purpose | Notes |
|---|---|---|
| tracing | การบันทึกข้อมูลแบบมีโครงสร้างและสแปน (structured logging and spans) | หากคุณต้องการทำ structured logging ใน Rust นี่คือเครื่องมือมาตรฐานที่ทุกคนเลือกใช้ |
| tracing-subscriber | การกำหนดค่าเอาต์พุตสำหรับ tracing | ใช้ features = ["env-filter", "json"] สำหรับการกรองล็อกตามตัวแปรสภาพแวดล้อมและการส่งออกในรูปแบบ JSON |
| tracing-opentelemetry | สะพานเชื่อมระหว่าง tracing กับ OpenTelemetry | แปลงสแปนของ tracing ให้กลายเป็นสแปนของ OpenTelemetry สำหรับ distributed tracing |
| opentelemetry | OpenTelemetry API | API แกนหลักสำหรับระบบ distributed tracing และเมตริก |
| opentelemetry-otlp | ตัวส่งออกข้อมูล (exporter) OTLP | ส่งออกข้อมูลเทรซไปยัง Jaeger, Tempo, Datadog และแบ็กเอนด์อื่นๆ ที่รองรับมาตรฐาน OTLP |
| axum-tracing-opentelemetry | การผสานการทำงานระหว่าง OpenTelemetry กับ Axum | กระจาย trace context ไปตามคำขอต่างๆ ของ Axum โดยอัตโนมัติ |
เอกสารประกอบ API
| Crate | Purpose | Notes |
|---|---|---|
| utoipa | การสร้างสเปก OpenAPI ตั้งแต่ตอนคอมไพล์ | สร้างสเปก OpenAPI 3.0 โดยอัตโนมัติจากแอตทริบิวต์ในโค้ด |
| utoipa-swagger-ui | Swagger UI สำหรับ utoipa | ให้บริการหน้าเว็บ UI เอกสาร API แบบโต้ตอบได้ผ่านเส้นทางที่สามารถกำหนดค่าได้ |
การทดสอบ
| Crate | Purpose | Notes |
|---|---|---|
| tower (ServiceExt) | การทดสอบการผสานระบบโดยไม่ต้องสตาร์ตเซิร์ฟเวอร์ | ใช้ oneshot() เพื่อส่งคำขอทดสอบผ่านเราเตอร์โดยตรง |
| mockall | การสร้าง mock อ็อบเจกต์อัตโนมัติ | สร้าง mock implementation ของเทรตต่างๆ สำหรับการทำยูนิตเทสต์ |
| axum-test | ไลบรารีการทดสอบสำหรับ Axum | จัดเตรียม TestClient ที่ใช้งานง่ายและมี API สะดวกกว่าการเรียก oneshot เปล่าๆ |
ไคลเอนต์ HTTP
| Crate | Purpose | Notes |
|---|---|---|
| reqwest | ไคลเอนต์ HTTP แบบ async | ไคลเอนต์ HTTP ที่พบได้บ่อยที่สุดในโปรเจกต์ Rust รองรับ async โดยกำเนิดพร้อมระบบ connection pooling |
gRPC
| Crate | Purpose | Notes |
|---|---|---|
| tonic | เฟรมเวิร์ก gRPC | ไคลเอนต์และเซิร์ฟเวอร์ gRPC แบบ async โดยสมบูรณ์ เชื่อมต่อกับมิดเดิลแวร์ของ Tower ได้อย่างไร้รอยต่อ |
| tonic-prost | รันไทม์ Tonic + Prost | รองรับการทำงานในระดับรันไทม์สำหรับเซอร์วิสของ tonic ที่ใช้ชนิดข้อมูลที่สร้างจาก prost |
| prost | Protocol Buffers | การซีเรียลไลซ์และดีซีเรียลไลซ์ Protobuf ที่ tonic เลือกใช้สำหรับชนิดข้อมูลของข้อความ |
| tonic-prost-build | การสร้างโค้ดจากไฟล์ proto | คอมไพล์ไฟล์ .proto ออกมาเป็นโค้ด Rust ในช่วงบิลด์ โดยระบุไว้ใน [build-dependencies] (เข้ามาแทนที่การใช้ tonic-build โดยตรงตั้งแต่ tonic 0.14) |
| tonic-reflection | ระบบ reflection บนเซิร์ฟเวอร์ gRPC | ช่วยให้เครื่องมืออย่าง grpcurl สามารถค้นหาและตรวจสอบ API ของเซอร์วิสได้โดยตรง |
ยูทิลิตี้แอซิงก์
| Crate | Purpose | Notes |
|---|---|---|
| tokio-util | ยูทิลิตี้เสริมสำหรับ Tokio | จัดเตรียม CancellationToken สำหรับการปิดระบบอย่างเป็นระเบียบ พร้อมทั้ง codecs และตัวช่วยอำนวยความสะดวกอื่นๆ |
| futures | ตัวเชื่อมและประมวลผล future (combinators) | จัดเตรียม FuturesUnordered, StreamExt และยูทิลิตี้อื่นๆ สำหรับการทำงานกับ async streams |
งานเบื้องหลัง
| Crate | Purpose | Notes |
|---|---|---|
| apalis | การประมวลผลงานเบื้องหลัง | ปลอดภัยต่อชนิดข้อมูล (type-safe), ขยายระบบได้ง่าย รองรับแบ็กเอนด์ทั้ง PostgreSQL, Redis และ SQLite พร้อมระบบมอนิเตอร์และการทำ graceful shutdown ในตัว |
| fang | คิวงานแบบคงทนถาวร (persistent) | แยกเวิร์กเกอร์ทำงานบนทาสก์ Tokio ต่างหาก พร้อมระบบรีสตาร์ตอัตโนมัติเมื่อเกิด panic, การตั้งเวลาแบบ cron และระบบหน่วงเวลาก่อนลองใหม่ (backoff) |
| backie | คิวทาสก์แบบ async | ขับเคลื่อนด้วย PostgreSQL ออกแบบมาสำหรับการสเกลในแนวนอนข้ามหลายโพรเซส |
แอนติแพตเทิร์น
ทุกโปรเจกต์เว็บใน Rust ที่ผมเคยร่วมงานด้วย ล้วนเคยสะดุดกับความผิดพลาดเดิมๆ ซ้ำแล้วซ้ำเล่า บางอย่างผมเป็นคนก่อขึ้นมาเอง บางอย่างผมช่วยดักจับได้ระหว่างการรีวิวโค้ด และมีอีกไม่น้อยที่ผมได้รับสืบทอดมาจากโค้ดเบสรุ่นก่อน ซึ่งมอบบทเรียนราคาแพงให้ผมอย่างเจ็บปวด บทนี้จึงได้รวบรวมข้อผิดพลาดที่ผมพบบ่อยที่สุด อธิบายเหตุผลว่าทำไมสิ่งเหล่านั้นถึงส่งผลเสียต่อระบบของคุณ และชี้ทางเลือกที่ดีกว่าซึ่งได้แนะนำไว้ในบทอื่นๆ ของหนังสือเล่มนี้
SQL ในแฮนด์เลอร์
หน้าตาเป็นแบบนี้: ฟังก์ชันแฮนด์เลอร์ที่มีการเรียกใช้ sqlx::query! โดยตรง มีการจัดการทรานแซกชัน และแมปข้อผิดพลาดของฐานข้อมูลอยู่ภายในบอดี้ของแฮนด์เลอร์ HTTP
ทำไมถึงสร้างปัญหา: มันจะผูกมัดเลเยอร์ HTTP ของคุณเข้ากับสกีมาของฐานข้อมูลอย่างถาวร คุณจะไม่สามารถทดสอบแฮนด์เลอร์ได้เลยหากไม่มีฐานข้อมูลจริง และไม่สามารถนำตรรกะการคิวรีกลับมาใช้ซ้ำจากจุดเริ่มต้นอื่น (เช่น คำสั่ง CLI, เวิร์กเกอร์เบื้องหลัง หรือแฮนด์เลอร์ตัวอื่น) ได้เลย นอกจากนี้ เมื่อใดก็ตามที่คิวรีเปลี่ยน คุณจะต้องกลับมาแก้ไขไฟล์ที่ควรจะรับผิดชอบเฉพาะเรื่องของ HTTP
ควรทำอย่างไรแทน: ย้ายโค้ดส่วนการเข้าถึงฐานข้อมูลเข้าไปไว้ใน struct ของรีพอสิทอรีหรือคิวรี ตามที่เราได้อธิบายไว้ในบท เลเยอร์ฐานข้อมูล โดยแฮนด์เลอร์ควรทำหน้าที่เพียงเรียกใช้เมธอดของเซอร์วิสหรือรีพอสิทอรี และทำงานกับชนิดข้อมูลฝั่งโดเมนเท่านั้น โดยไม่ควรแตะต้อง SQL หรือชนิดข้อมูลข้อผิดพลาดเฉพาะของฐานข้อมูลโดยตรง
กรณีที่ยอมรับได้จริงๆ: สำหรับไมโครเซอร์วิสขนาดเล็กแบบ CRUD ที่แต่ละเอนด์พอยต์แมปตรงไปยังคิวรีเพียงหนึ่งหรือสองตัว และไม่มีแนวโน้มที่จะต้องมีจุดเริ่มต้นอื่น การเขียน SQL ในแฮนด์เลอร์อาจถือเป็นการลดความซับซ้อนที่สมเหตุสมผล โปรเจกต์อ้างอิงอย่าง launchbadge/realworld-axum-sqlx ก็เลือกใช้แนวทางนี้โดยตั้งใจ ซึ่งคิวรีแบบอินไลน์ของพวกเขามีโครงสร้างที่ดีและอ่านเข้าใจง่าย หัวใจสำคัญคือการเลือกใช้วิธีนี้ด้วยความตระหนักรู้และมีเจตนาชัดเจน ไม่ใช่เลือกเพราะเป็นค่าเริ่มต้น และต้องรู้ตัวเมื่อแฮนด์เลอร์เริ่มสะสมตรรกะการคิวรีมากจนถึงจุดที่ควรแยกเลเยอร์ออกไป หากคุณพบว่าตัวเองเริ่มเขียนคิวรีซ้ำข้ามแฮนด์เลอร์ หรือแฮนด์เลอร์เริ่มจัดการคิวรีหลายตัวที่ต้องสำเร็จหรือล้มเหลวไปพร้อมกัน นั่นคือสัญญาณเตือนว่าถึงเวลาต้องนำเลเยอร์รีพอสิทอรีหรือเซอร์วิสเข้ามาช่วยแล้ว
แฮนด์เลอร์อ้วน
หน้าตาเป็นแบบนี้: แฮนด์เลอร์ที่รับผิดชอบทุกอย่างในฟังก์ชันเดียว ตั้งแต่ตรวจสอบความถูกต้องของอินพุต, แฮชรหัสผ่าน, คิวรีฐานข้อมูล, ส่งอีเมลแจ้งเตือน, เผยแพร่อีเวนต์ ไปจนถึงประกอบการตอบกลับ HTTP
ทำไมถึงสร้างปัญหา: มันทำให้แฮนด์เลอร์ไม่สามารถแยกทดสอบแบบเดี่ยวๆ ได้ ยากต่อการทำความเข้าใจ และแก้ไขได้ลำบากอย่างยิ่ง อีกทั้งหากต้องการเพิ่มจุดเริ่มต้นที่สองสำหรับตรรกะทางธุรกิจชุดเดียวกัน (เช่น เอนด์พอยต์สำหรับผู้ดูแลระบบ หรือคอนซูเมอร์ของคิวข้อความ) คุณก็จำเป็นต้องคัดลอกตรรกะทั้งหมดเหล่านั้นซ้ำอีกรอบ
ควรทำอย่างไรแทน: รักษาแฮนด์เลอร์ของคุณให้ผอมเพรียว (thin handlers) โดยสกัดตรรกะทางธุรกิจออกไปไว้ในเมธอดของเซอร์วิสในเลเยอร์โดเมน หน้าที่ของแฮนด์เลอร์มีเพียงดึงข้อมูลจากคำขอ เรียกใช้เมธอดของเซอร์วิส และส่งคืนการตอบกลับเท่านั้น หากแฮนด์เลอร์ของคุณยาวเกิน 15 ถึง 20 บรรทัด แสดงว่ามันน่าจะรับหน้าที่มากเกินไปแล้ว
การใช้ unwrap() ในเส้นทางของคำขอ
หน้าตาเป็นแบบนี้: การเรียกใช้ .unwrap() หรือ .expect() บนค่า Result หรือ Option ภายในแฮนด์เลอร์หรือในโค้ดส่วนใดก็ตามที่ทำงานระหว่างการประมวลผลคำขอ
ทำไมถึงสร้างปัญหา: การเกิด panic ภายในแฮนด์เลอร์จะทำให้คำขอนั้นล้มเหลวและส่งข้อผิดพลาด 500 ที่คลุมเครือกลับไป ยิ่งไปกว่านั้น หากเกิด panic ในขณะที่กำลังถือครอง mutex อยู่ มันจะทำให้ mutex นั้นกลายเป็นพิษ (poisoned) จนลุกลามไปส่งผลกระทบต่อคำขออื่นๆ ทั้งระบบ ไคลเอนต์จะไม่ได้รับข้อมูลข้อผิดพลาดที่เป็นประโยชน์ และล็อกของคุณก็อาจเก็บข้อมูลบริบทได้ไม่ครบถ้วน
ควรทำอย่างไรแทน: ให้ใช้โอเปอเรเตอร์ ? เสมอในการส่งต่อข้อผิดพลาดผ่านชนิดข้อมูล Result หากต้องการแปลง Option ให้เป็นข้อผิดพลาด ให้ใช้ .ok_or(AppError::NotFound)? หรือรูปแบบที่ใกล้เคียงกัน จงสงวนการใช้ unwrap() ไว้เฉพาะกรณีที่คุณพิสูจน์ได้อย่างแน่นอนว่าค่านั้นมีอยู่เสมอ (เช่น regex ที่ฮาร์ดโค้ดไว้) และเก็บ expect() ไว้สำหรับโค้ดช่วงเริ่มต้นระบบ (startup) ซึ่งหากค่านั้นขาดหายไป แอปพลิเคชันก็ไม่ควรทำงานต่อได้ตั้งแต่แรก
การปล่อยให้ชนิดข้อมูลฐานข้อมูลรั่วเข้าไปใน API
หน้าตาเป็นแบบนี้: การส่งคืน struct ตัวเดียวกันจากเลเยอร์ฐานข้อมูลไปยังแฮนด์เลอร์ HTTP หรือการ derive ทั้ง sqlx::FromRow และ serde::Serialize บนชนิดข้อมูลเดียวกัน แล้วส่งคืนกลับไปตรงๆ ในรูป Json<UserRow>
ทำไมถึงสร้างปัญหา: หมายความว่าการเพิ่มคอลัมน์ใหม่ในฐานข้อมูล จะเป็นการเพิ่มฟิลด์นั้นเข้าไปในผลลัพธ์ของ API โดยอัตโนมัติ หากคอลัมน์ดังกล่าวเก็บข้อมูลที่ละเอียดอ่อน (เช่น รหัสผ่านที่แฮชแล้ว, แฟล็กภายในระบบ หรือสถานะการลบแบบ soft-delete) ข้อมูลเหล่านั้นจะหลุดไปให้ผู้เรียกใช้ API ทุกคนเห็นทันที นอกจากนี้ การเปลี่ยนชื่อหรือปรับโครงสร้างคอลัมน์ในฐานข้อมูลจะกลายเป็นการทำลายความเข้ากันได้ของ API (breaking change) โดยไม่ตั้งใจ
ควรทำอย่างไรแทน: แยกชนิดข้อมูลออกจากกันให้ชัดเจนตามแต่ละขอบเขตการทำงาน ตามที่เราได้แนะนำไว้ในบท การสร้างแบบจำลองโดเมน ให้ UserRow ทำหน้าที่แมปกับฐานข้อมูล, User ทำหน้าที่เป็นตัวแทนของเอนทิตีฝั่งโดเมน และ UserResponse ทำหน้าที่กำหนดข้อตกลง (contract) ของ API จากนั้นใช้การอิมพลีเมนต์ From อย่างชัดเจนเพื่อเชื่อมโยงข้อมูลข้ามขอบเขต ซึ่งจะช่วยให้การแปลงข้อมูลตรวจสอบได้ง่าย
การเปิดเผยข้อผิดพลาดภายในให้ไคลเอนต์เห็น
หน้าตาเป็นแบบนี้: การส่งคืนข้อความแจ้งข้อผิดพลาดแบบดิบๆ จากฐานข้อมูล, ระบบไฟล์ หรือการเรียกเซอร์วิสภายใน กลับไปในบอดี้ของการตอบกลับ HTTP โดยตรง
ทำไมถึงสร้างปัญหา: ข้อความแจ้งข้อผิดพลาดภายในมักแฝงไปด้วยชื่อตารางฐานข้อมูล, พาธของไฟล์, คำสั่งคิวรี SQL, สแตกเทรซ และข้อมูลเชิงลึกอื่นๆ ที่เปิดโอกาสให้ผู้ไม่หวังดีเข้าใจโครงสร้างภายในของระบบได้ แม้จะไม่มีการโจมตี แต่ข้อความเหล่านี้ก็สร้างความสับสนให้แก่ผู้ใช้งาน API อยู่ดี เพราะมันอธิบายรายละเอียดเชิงเทคนิคของการนำไปใช้ แทนที่จะอธิบายปัญหาในเชิงธุรกิจที่เกิดขึ้นจริง
ควรทำอย่างไรแทน: บันทึกรายละเอียดข้อผิดพลาดฉบับเต็มไว้ที่ฝั่งเซิร์ฟเวอร์ด้วยระดับล็อก error แล้วส่งคืนข้อความระดับทั่วไปที่ผู้ใช้ควรรู้กลับไปให้ไคลเอนต์ ซึ่งวาเรียนต์ AppError::Internal ที่เราได้แนะนำไว้ในบท การจัดการข้อผิดพลาด สามารถจัดการกับแพตเทิร์นนี้ได้อย่างเรียบร้อยและปลอดภัย
ความลับแบบฮาร์ดโค้ด
หน้าตาเป็นแบบนี้: การกำหนดค่า JWT secret หรือรหัสผ่านฐานข้อมูลเป็นข้อความแบบสตริงลิเทอรัลไว้ในซอร์สโค้ดโดยตรง หรือการเผลอคอมมิตไฟล์ .env เข้าสู่ระบบควบคุมเวอร์ชัน (Git)
ทำไมถึงสร้างปัญหา: ใครก็ตามที่สามารถเข้าถึงซอร์สโค้ด (หรือประวัติการคอมมิตใน Git) จะได้กุญแจสำคัญสำหรับระบบ production ของคุณไปทันที ซึ่งรวมถึงนักพัฒนาทุกคนในทีม, ระบบ CI ทุกตัวที่ดึงโค้ดไปบิลด์ และใครก็ตามที่พบเจตรีโพสิทอรีนี้หากวันใดวันหนึ่งมันถูกเปิดเป็นสาธารณะโดยไม่ตั้งใจ
ควรทำอย่างไรแทน: โหลดค่าความลับต่างๆ จากตัวแปรสภาพแวดล้อม (environment variables) ตามที่เราได้แนะนำไว้ในบท การตั้งค่า และใช้ SecretString จากเครต secrecy เพื่อช่วยปกป้องข้อมูลในหน่วยความจำ พร้อมทั้งใส่ .env ลงใน .gitignore และเตรียมไฟล์ .env.example เพื่อบันทึกรายชื่อตัวแปรที่จำเป็นทั้งหมดโดยไม่ต้องใส่ค่าจริงลงไป
การอิมพอร์ตข้ามเลเยอร์
หน้าตาเป็นแบบนี้: การที่โมดูลโดเมนไปอิมพอร์ตบางสิ่งจากโมดูล api (เช่น ชนิดข้อมูลตัวแยกข้อมูลของ Axum) หรือจากโมดูล infra (เช่น PgPool)
ทำไมถึงสร้างปัญหา: มันทำลายกฎทิศทางของดีเพนเดนซี (dependency rule) ซึ่งเป็นหัวใจสำคัญของ Clean Architecture หากโดเมนต้องพึ่งพา Axum คุณจะไม่สามารถนำตรรกะโดเมนนั้นไปใช้ในเครื่องมือ CLI ได้เลยโดยไม่ดึงเฟรมเวิร์ก HTTP ทั้งหมดตามไปด้วย และหากโดเมนต้องพึ่งพา SQLx คุณจะไม่สามารถทดสอบโดเมนได้เลยหากไม่มีฐานข้อมูลจริงรองรับ
ควรทำอย่างไรแทน: ทิศทางของดีเพนเดนซีต้องชี้เข้าหาแกนกลางเสมอ: เลเยอร์ API ต้องพึ่งพาโดเมน, เลเยอร์โครงสร้างพื้นฐานต้องพึ่งพาโดเมน แต่ตัวโดเมนจะต้องไม่พึ่งพาสิ่งใดจากภายนอก หากโดเมนจำเป็นต้องใช้ฟังก์ชันการทำงานจากโลกภายนอก ให้โดเมนนิยามเทรต (พอร์ต) ขึ้นมา แล้วให้เลเยอร์โครงสร้างพื้นฐานเป็นผู้นำไปอิมพลีเมนต์ (ในฐานะอะแดปเตอร์) ซึ่งเราได้ครอบคลุมเรื่องนี้อย่างละเอียดไว้แล้วในบทสถาปัตยกรรม
การบล็อก async runtime
หน้าตาเป็นแบบนี้: การเรียกใช้ฟังก์ชันที่ทำงานหนักบน CPU (เช่น การแฮชรหัสผ่านด้วย Argon2), การทำ I/O กับไฟล์แบบซิงโครนัส หรือการเรียกใช้ไลบรารีแบบบล็อกกิ้ง ภายในแฮนด์เลอร์แบบ async โดยตรง
ทำไมถึงสร้างปัญหา: รันไทม์ของ Tokio ใช้เธรดเวิร์กเกอร์จำนวนไม่มากเพื่อสลับกันประมวลผลทาสก์ async จำนวนมหาศาลแบบสมานฉันท์ (cooperatively) หากมีทาสก์ใดเข้าไปบล็อกเธรดนั้นไว้เพียงเธรดเดียว ทาสก์อื่นๆ ทั้งหมดที่เข้าคิวอยู่บนเธรดดังกล่าวจะไม่สามารถทำงานต่อได้ เมื่อระบบมีโหลดสูง อาการนี้จะทำให้ค่าความหน่วง (latency) พุ่งสูงขึ้นอย่างรวดเร็วและ throughput ลดฮวบ ซึ่งเป็นปัญหาที่ตรวจวิเคราะห์สาเหตุได้ยากมาก
ควรทำอย่างไรแทน: ให้ใช้ tokio::task::spawn_blocking() สำหรับงานที่กินทรัพยากร CPU หนักๆ หรืองานที่เป็นบล็อกกิ้ง, เปลี่ยนมาใช้ tokio::fs แทน std::fs, และตรวจสอบให้แน่ใจว่าไดรเวอร์ฐานข้อมูลของคุณทำงานแบบ async อย่างแท้จริง (เช่น SQLx และ diesel-async เป็น async แท้ ส่วน Diesel รุ่นพื้นฐานไม่ใช่)
ค่าโดเมนที่ใช้ String เป็นชนิด
หน้าตาเป็นแบบนี้: การใช้ชนิดข้อมูล String ธรรมดาๆ เป็นตัวแทนของอีเมล, ชื่อผู้ใช้ และค่าข้อมูลทางธุรกิจอื่นๆ กระจัดกระจายไปทั่วทั้งแอปพลิเคชัน
ทำไมถึงสร้างปัญหา: ฟังก์ชันที่รับพารามิเตอร์เป็น (String, String, String) สำหรับชื่อ, อีเมล และรหัสผ่าน สามารถถูกเรียกใช้งานโดยส่งอาร์กิวเมนต์สลับลำดับกันได้อย่างง่ายดาย โดยที่คอมไพเลอร์ไม่สามารถตรวจจับความผิดพลาดนี้ได้เลย นอกจากนี้ คุณยังสูญเสียจุดศูนย์กลางในการควบคุมกฎเกณฑ์ความถูกต้อง (อินแวเรียนต์ เช่น “อีเมลต้องมีเครื่องหมาย @”) ส่งผลให้ตรรกะการตรวจสอบความถูกต้องกระจัดกระจายไปทั่วทั้งโค้ดเบส
ควรทำอย่างไรแทน: ใช้แพตเทิร์น newtype ตามที่เราได้แนะนำไว้ในบท การสร้างแบบจำลองโดเมน โดยการสร้างชนิดข้อมูลเฉพาะตัวอย่าง Email, UserName และ UserId ที่มีกระบวนการบังคับใช้อินแวเรียนต์ตั้งแต่ขั้นตอนการสร้างค่า (construction time) แม้ว่าในช่วงแรกอาจดูเหมือนมีโค้ด boilerplate เพิ่มขึ้นมาบ้าง แต่มันจะตอบแทนคุณอย่างคุ้มค่าในระยะยาว
การขาด health check
หน้าตาเป็นแบบนี้: แอปพลิเคชันที่ถูกดีพลอยต์ขึ้นสู่ระบบ Container Orchestrator โดยไม่มีเอนด์พอยต์สำหรับการตรวจสุขภาพ (health check) หรือมีการใช้ liveness probe ไปตรวจสอบดีเพนเดนซีภายนอก
ทำไมถึงสร้างปัญหา: หากไม่มีระบบตรวจสุขภาพ ตัว Orchestrator จะไม่มีทางทราบได้เลยว่าแอปพลิเคชันของคุณยังทำงานได้ตามปกติหรือไม่ มันจึงไม่สามารถสั่งรีสตาร์ตโพรเซสที่ค้าง หรือหยุดส่งทราฟฟิกไปยังอินสแตนซ์ที่ขาดการเชื่อมต่อกับฐานข้อมูลได้ และในทางกลับกัน การตั้งค่า liveness probe ให้ตรวจสอบฐานข้อมูล จะทำให้เกิดการรีสตาร์ตระบบโดยไม่จำเป็นเมื่อฐานข้อมูลหยุดทำงานชั่วคราว ซึ่งรังแต่จะทำให้สถานการณ์เลวร้ายลงไปอีก
ควรทำอย่างไรแทน: อิมพลีเมนต์ liveness probe และ readiness probe แยกจากกันอย่างชัดเจน ตามที่อธิบายไว้ในบท การดีพลอยต์ โดย liveness probe ควรทำงานแบบไม่มีเงื่อนไข (ตอบกลับทันทีว่าตัวแอปยังไม่ตาย) ส่วน readiness probe ให้ทำหน้าที่ตรวจสอบความพร้อมของดีเพนเดนซีต่างๆ
การออกแบบเกินจำเป็นตั้งแต่เริ่ม
หน้าตาเป็นแบบนี้: โปรเจกต์ใหม่ที่เพิ่งเริ่มต้นแต่กลับแบ่ง workspace ออกเป็นสามเครต, มีรีพอสิทอรีแบบครอบด้วยเทรตพร้อมเจเนอริกเซอร์วิส, วางแพตเทิร์น CQRS และติดตั้ง event bus ทั้งหมดนี้ทำขึ้นเพื่อรองรับแอปพลิเคชันที่มีเอนด์พอยต์ CRUD เพียง 5 ตัว
ทำไมถึงสร้างปัญหา: การสร้างนามธรรมเร็วเกินไป (premature abstraction) เป็นการเพิ่มความซับซ้อนที่ฉุดรั้งความเร็วในการพัฒนาของคุณ โดยไม่ก่อให้เกิดประโยชน์ที่สมน้ำสมเนื้อเลย ทุกๆ เลเยอร์ที่เพิ่มขึ้นมา หมายถึงสิ่งที่คุณต้องทำความเข้าใจเพิ่มขึ้น, จุดที่บั๊กสามารถแอบซ่อนตัวได้มากขึ้น และเป็นอุปสรรคขัดขวางการเปลี่ยนแปลงโค้ด จากประสบการณ์ของผม โปรเจกต์ที่ส่งมอบงานได้เร็วที่สุด คือโปรเจกต์ที่เริ่มต้นอย่างเรียบง่าย แล้วจึงค่อยๆ ขยายโครงสร้างเมื่อมีความต้องการใช้งานจริงเกิดขึ้น
ควรทำอย่างไรแทน: เริ่มต้นด้วยโครงสร้างที่เรียบง่ายที่สุดแต่มีการแบ่งสัดส่วนที่ชัดเจน ตามที่แนะนำไว้ในบท โครงสร้างโปรเจกต์ และเพิ่มระดับนามธรรมเฉพาะเมื่อความซับซ้อนของปัญหาเรียกร้องจริงๆ เท่านั้น อย่าเพิ่งเพิ่มเพื่อดักทางความซับซ้อนในจินตนาการที่อาจไม่เคยเกิดขึ้นจริง คุณสามารถรีแฟกเตอร์โค้ดจากโครงสร้างแบบเรียบง่ายไปเป็นโครงสร้างแบบหลายเลเยอร์ได้เสมอเมื่อความต้องการชัดเจนขึ้น ดังนั้น อย่าไปกังวลกับการสร้างสถาปัตยกรรมที่ “สมบูรณ์แบบไร้ที่ติ” ตั้งแต่วันแรกของการพัฒนา
แหล่งข้อมูล
ผมตั้งใจรวบรวมหนังสือ, บทความ, รีโพสิทอรี และแหล่งข้อมูลต่างๆ จากคอมมูนิตี้ ที่มีอิทธิพลต่อวิธีคิดของผมในการนำเสนอหัวข้อต่างๆ ในคู่มือเล่มนี้ หากคุณต้องการศึกษาเจาะลึกเพิ่มเติมในเนื้อหาส่วนใดก็ตามที่เราได้กล่าวถึงไป นี่คือจุดเริ่มต้นที่ดีที่สุดที่ผมอยากแนะนำ
หนังสือ
Design Patterns and Best Practices in Rust โดย Evan Williams (2025) เป็นหนังสือที่พาสำรวจดีไซน์แพตเทิร์นแบบ idiomatic ใน Rust ไว้อย่างเข้มข้น ครอบคลุมทั้งแพตเทิร์นของ GoF ที่นำมาปรับใช้ให้เข้ากับธรรมชาติของ Rust, แพตเทิร์นเชิงฟังก์ชัน (functional patterns) ตลอดจนแพตเทิร์นด้านสถาปัตยกรรมที่คุณจะได้นำไปประยุกต์ใช้งานจริงในโปรเจกต์
The Rust Spellbook (2026) อัดแน่นไปด้วยเคล็ดลับและเทคนิคของ Rust หลายร้อยข้อ เหมาะอย่างยิ่งสำหรับการค้นพบฟีเจอร์ที่ไม่ค่อยมีใครรู้จักของภาษา ไลบรารีมาตรฐาน และทูลเชน ซึ่งคุณอาจไม่มีโอกาสได้พบเห็นด้วยตนเองในชีวิตประจำวัน
Rust Web Development เขียนโดยตัวผมเอง (จัดพิมพ์โดย Manning) เล่มนี้คือผลงานเล่มก่อนหน้าของผมที่ว่าด้วยการสร้างเว็บเซอร์วิสใน Rust โดยเน้น Warp และระบบนิเวศโดยรวม หากคุณต้องการทำความเข้าใจบริบทเพิ่มเติมเกี่ยวกับมุมมองและวิธีคิดของผมที่มีต่อปัญหาเหล่านี้ นี่คือจุดเริ่มต้นที่ดีในการศึกษาค้นคว้า
บทความด้านสถาปัตยกรรมและการออกแบบ
Master Hexagonal Architecture in Rust จากประสบการณ์ของผม นี่คือคู่มือที่เจาะลึกและละเอียดถี่ถ้วนที่สุดเกี่ยวกับการอิมพลีเมนต์สถาปัตยกรรม Hexagonal (Ports and Adapters) ใน Rust โดยพาไล่เรียงตั้งแต่การสร้างแบบจำลองโดเมน, การนิยามพอร์ตผ่านเทรต, การเขียนอะแดปเตอร์, การทำ dependency injection, กลยุทธ์การทดสอบ ไปจนถึงข้อดีข้อเสีย (trade-offs) ที่คุณต้องเผชิญระหว่างทาง ซึ่งผมได้หยิบยืมแนวคิดจากบทความนี้มาใช้อย่างมากในการเขียนบทสถาปัตยกรรมของคู่มือนี้
A Rustacean Clean Architecture Approach to Web Development อธิบายสถาปัตยกรรม 4 เลเยอร์ (โมเดล, เลเยอร์การจัดเก็บข้อมูล, เราเตอร์, เอกสารประกอบ) พร้อมมุมมองเชิงปฏิบัติในการลดการพึ่งพาเฟรมเวิร์ก ผมคิดว่าบทความนี้ช่วยเสริมบทความ Hexagonal ได้อย่างลงตัว เพราะแสดงให้เห็นแนวทางที่เรียบง่ายกว่าและทำงานได้ดีเยี่ยมเมื่อระบบของคุณเน้นงานสไตล์ CRUD เป็นหลัก
Rust, Axum, and Onion Architecture พาเดินชมขั้นตอนการนำ Onion Architecture ไปประยุกต์ใช้จริงร่วมกับ Axum ครอบคลุมทั้งเลเยอร์ Presentation, Application, Domain และ Infrastructure พร้อมตัวอย่างโค้ดที่เป็นรูปธรรมซึ่งคุณสามารถทำตามได้ทันที
Building a Clean Rust Backend with Axum, Diesel, PostgreSQL and DDD นำเสนอแพตเทิร์นการออกแบบเชิงโดเมน (Domain-Driven Design หรือ DDD) ร่วมกับ Axum และ Diesel คุณจะได้เห็นตัวอย่างการนำ Repository Pattern, การจัดการข้อผิดพลาดแบบแบ่งเลเยอร์ และการเขียนตัวแยกข้อมูลเฉพาะตัว (custom extractors) มารวมไว้ในที่เดียวกัน
The Best Way to Structure Rust Web Services ครอบคลุมแพตเทิร์นการจัดโครงสร้างโปรเจกต์ ตั้งแต่แบบโมดูลระนาบเดียว (flat modules) ไปจนถึง Clean Architecture ที่แยกเป็น Cargo Workspace สิ่งที่ผมชอบเป็นพิเศษคือคำแนะนำเชิงปฏิบัติว่าสถานการณ์ใดควรเลือกใช้แนวทางไหน
คู่มือเฉพาะของ Axum
The Ultimate Guide to Axum (Shuttle) ครอบคลุมเนื้อหาสำคัญไว้ครบถ้วนรอบด้าน: ทั้งแฮนด์เลอร์, การเราต์, การจัดการสถานะ, ตัวแยกข้อมูลแบบกำหนดเอง, มิดเดิลแวร์, การทดสอบด้วย oneshot ไปจนถึงการดีพลอยต์ หากคุณต้องการอ่านบทความเดียวที่ปูพื้นฐาน Axum ได้ครบทุกมิติ นี่คือตัวเลือกที่ยอดเยี่ยม
How to Build Production-Ready REST APIs in Rust with Axum นำพาคุณผ่านวงจรชีวิตทั้งหมดของการพัฒนา API ระดับ production: ตั้งแต่การเริ่มต้นโปรเจกต์, การจัดการข้อผิดพลาด, การตรวจสอบความถูกต้อง, การยืนยันตัวตน, การประกอบมิดเดิลแวร์, การทำ graceful shutdown ไปจนถึงการดีพลอยต์ด้วย Docker จัดว่าเป็นคู่มืออ้างอิงแบบครบวงจรที่ดีมาก
Building High-Performance APIs with Axum and Rust มุ่งเน้นไปที่การรีดประสิทธิภาพขั้นสูง ซึ่งเป็นจุดที่เราไม่ได้เจาะลึกมากนักในคู่มือนี้ โดยจะครอบคลุมทั้งการวัดประสิทธิภาพ (benchmarking) และกลยุทธ์การปรับแต่งความเร็วที่เจาะจงกับ Axum โดยเฉพาะ
Error Handling in Axum (LogRocket) พาสำรวจแนวทางต่างๆ ในการจัดการข้อผิดพลาดบน Axum ตั้งแต่การส่งคืนสถานะ HTTP แบบง่ายๆ ไปจนถึงการสร้างชนิดข้อมูลข้อผิดพลาดเฉพาะตัวร่วมกับเทรต IntoResponse หากบทการจัดการข้อผิดพลาดของเราทำให้คุณอยากเห็นทางเลือกที่หลากหลายขึ้น ขอแนะนำให้เริ่มจากที่นี่
Elegant Error Handling with IntoResponse (Leapcell) นำเสนอแพตเทิร์นการจับคู่ระหว่าง thiserror กับ IntoResponse เพื่อรวมศูนย์การจัดการข้อผิดพลาด เป็นแนวทางที่สะอาดและทำงานได้ผลดีเยี่ยมในทางปฏิบัติจริง
การสร้างแบบจำลองโดเมนและการออกแบบเชิงชนิดข้อมูล
Using Types to Guarantee Domain Invariants โดย Luca Palmieri เป็นหนึ่งในบทความโปรดของผมว่าด้วยแพตเทิร์น newtype และหลักการ “parse, don’t validate” ที่นำมาประยุกต์ใช้กับเว็บแอปพลิเคชันใน Rust หากคุณประทับใจกับแนวคิดเหล่านี้ในบทก่อนๆ บทความนี้จะพาคุณดำดิ่งลงไปลึกยิ่งขึ้น
Type-Driven Design in Rust and TypeScript เปรียบเทียบแนวทางการออกแบบโดยขับเคลื่อนด้วยระบบชนิดข้อมูล (type-driven design) ระหว่างภาษา Rust และ TypeScript หากคุณมีพื้นฐานมาจาก TypeScript (ซึ่งพวกเราหลายคนเป็นเช่นนั้น) บทความนี้จะช่วยเชื่อมต่อภาพความคิดในหัวของคุณได้อย่างดี
Rust Design Patterns แคตตาล็อกที่รวบรวมและดูแลโดยคอมมูนิตี้ ซึ่งบรรจุดีไซน์แพตเทิร์น, แอนติแพตเทิร์น และสำนวนภาษา (idioms) ของ Rust ไว้อย่างครบถ้วน รวมถึงแพตเทิร์น newtype และแพตเทิร์นอื่นๆ ที่พบได้บ่อยในงานพัฒนาเว็บ ผมมักจะย้อนกลับมาเปิดอ่านหน้านี้อยู่เป็นประจำ
หัวข้อเฉพาะ
Secure Configuration and Secrets Management in Rust เจาะลึกการใช้เครต secrecy, การจัดการตัวแปรสภาพแวดล้อม และการปกป้องข้อมูลลับในหน่วยความจำ หากคุณต้องการยกระดับความปลอดภัยให้ไกลกว่าที่เรากล่าวถึงในบทการตั้งค่า นี่คือก้าวต่อไปที่เหมาะสมอย่างยิ่ง
How to Add Structured Logging to Rust HTTP APIs (techbuddies) อธิบายขั้นตอนการสร้างไปป์ไลน์ structured logging อย่างสมบูรณ์แบบ พร้อม correlation ID และการส่งออกข้อมูลเป็น JSON ใช้งานได้จริงและสามารถทำตามได้ทีละสเต็ป
Instrument Rust Axum with OpenTelemetry ครอบคลุมการตั้งค่า OpenTelemetry อย่างเต็มรูปแบบสำหรับ Axum ตั้งแต่การกระจายเทรซไปจนถึงการกำหนดค่า exporter เนื่องจากการตั้งค่า OTel ให้ถูกต้องนั้นค่อนข้างละเอียดอ่อน การมีคู่มืออ้างอิงที่สมบูรณ์จึงช่วยได้มาก
JWT Authentication in Rust (Shuttle) นำคุณผ่านการอิมพลีเมนต์การยืนยันตัวตนด้วย JWT โดยใช้ตัวแยกข้อมูล (extractor) แบบกำหนดขึ้นเองทีละขั้นตอน
Graceful Shutdown for Axum Servers ครอบคลุมเรื่องการดักจับสัญญาณระบบ, การเคลียร์การเชื่อมต่อที่ค้างอยู่ (connection draining) และแบบแผนการคืนทรัพยากร (cleanup patterns) การทำ graceful shutdown เป็นสิ่งที่เรามักไม่ค่อยนึกถึงจนกว่าจะเจอปัญหาจริง และเมื่อถึงตอนนั้นมันคือสิ่งจำเป็นอย่างยิ่งยวด
Health Checks and Readiness Probes in Rust for Kubernetes ครอบคลุมการสร้าง liveness probe และ readiness probe สำหรับ container orchestrator หากคุณเตรียมดีพลอยต์ระบบขึ้นบน Kubernetes คุณจำเป็นต้องใช้สิ่งเหล่านี้แน่นอน
Axum Backend Series: Models, Migrations, DTOs and Repository Pattern การสาธิตเชิงปฏิบัติในการวางเลเยอร์ฐานข้อมูลด้วย SQLx โค้ดกระชับ นำไปปฏิบัติจริงได้รวดเร็ว
An Ergonomic Pattern for SQLx Queries in Axum อธิบายแพตเทิร์น FromRef สำหรับเข้าถึงฐานข้อมูลในแฮนด์เลอร์อย่างสะอาดตา ใช้เวลาอ่านสั้นๆ แต่เป็นแพตเทิร์นที่ผมหยิบมาใช้งานอยู่เสมอ
รีโพสิทอรีตัวอย่าง
rust10x/rust-web-app พิมพ์เขียวสำหรับเว็บแอปพลิเคชันบน Axum ระดับ production ดูแลรักษาในฐานะโปรเจกต์อ้างอิงมาตรฐาน และมีฟีเจอร์ขั้นสูงอย่างระบบ multi-tenancy ซึ่งหาดูได้ยากในตัวอย่างทั่วไป
launchbadge/realworld-axum-sqlx โปรเจกต์ที่อิมพลีเมนต์ตามสเปกของ RealWorld (API จำลองของ Medium) โดยใช้ Axum และ SQLx ผมชอบโปรเจกต์นี้เพราะเป็นตัวอย่างที่สมบูรณ์และใช้งานได้จริงของ API ที่มีความซับซ้อนระดับหนึ่ง ซึ่งหาตัวอย่างแบบนี้ได้ยาก
JoeyMckenzie/realworld-rust-axum-sqlx อีกหนึ่งโปรเจกต์ RealWorld แต่เลือกใช้แนวคิดทางสถาปัตยกรรมที่แตกต่างออกไป การนำสองตัวอย่างนี้มาเปรียบเทียบกันเคียงข้างกัน เป็นวิธีที่ยอดเยี่ยมในการทำความเข้าใจว่าการตัดสินใจออกแบบในแต่ละแบบส่งผลอย่างไรในทางปฏิบัติจริง
jeremychone-channel/rust-axum-course รวบรวมโค้ดตัวอย่างจากคอร์สวิดีโอสอน Axum ที่ลงลึกและครอบคลุมทุกเรื่องตั้งแต่พื้นฐานไปจนถึงแพตเทิร์นสำหรับ production พร้อมประวัติคอมมิตที่เป็นระบบระเบียบ เหมาะสำหรับการฝึกทำตามทีละขั้น
tokio-rs/axum/examples รวบรวมตัวอย่างทางการมากกว่า 30 รายการที่ดูแลโดยทีมพัฒนา Axum โดยตรง เมื่อใดก็ตามที่ผมไม่แน่ใจว่าฟีเจอร์ใดควรเขียนอย่างไร ที่นี่คือที่แรกที่ผมจะเข้าไปตรวจสอบ ครอบคลุมตั้งแต่การเราต์พื้นฐาน ไปจนถึง WebSockets, การทดสอบ และการทำ graceful shutdown
อ้างอิงระบบนิเวศ
Axum ECOSYSTEM.md แคตตาล็อกทางการที่รวบรวมเครตจากคอมมูนิตี้มากกว่า 70 เครตสำหรับใช้งานร่วมกับ Axum ก่อนที่คุณจะเริ่มเขียนอะไรขึ้นมาเอง ขอแนะนำให้แวะมาสำรวจที่นี่ก่อน ครอบคลุมตั้งแต่ระบบยืนยันตัวตน, มิดเดิลแวร์, การตรวจสอบความถูกต้อง, การสังเกตการณ์ ไปจนถึงฟังก์ชันเฉพาะทางอีกมากมาย
Idiomatic Rust (mre) คอลเลกชันที่ผ่านการคัดสรรจากผู้เชี่ยวชาญ รวบรวมบทความ, วิดีโอบรรยาย และรีโพสิทอรีที่สอนการเขียน Rust แบบ idiomatic ไว้อย่างกระชับและตรงประเด็น แม้เนื้อหาจะลึกมากแต่ก็คุ้มค่าแก่การศึกษาอย่างยิ่ง
Rust API Guidelines รายการคำแนะนำและข้อปฏิบัติสำหรับการออกแบบ API สไตล์ idiomatic ใน Rust ซึ่งมีประโยชน์ทั้งการออกแบบ API ของโมดูลภายในโปรเจกต์ ตลอดจน Public HTTP API ของคุณ และเป็นแหล่งอ้างอิงแรกที่ผมจะแนะนำให้ทุกคนที่ถามว่า “ผมควรออกแบบอินเทอร์เฟซนี้อย่างไร?”