Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

ตารางอ้างอิงเครต

ตลอดทั้งเล่มนี้ เราดึงเครตเข้ามาใช้งานอยู่ไม่น้อย หากคุณเคยนึกสงสัยว่า “เดี๋ยว เครตตัวนั้นชื่ออะไรนะ” หน้านี้คือคู่มืออ้างอิงที่คุณสามารถย้อนกลับมาดูได้เสมอ ผมได้จัดหมวดหมู่ทุกอย่างตามขอบเขตการใช้งาน (concern) เพื่อให้คุณค้นหาสิ่งที่ต้องการได้อย่างรวดเร็ว พร้อมทั้งเข้าใจว่าเหตุใดเครตเหล่านี้จึงถูกเลือกเข้ามาอยู่ในสแตกของเรา

เฟรมเวิร์กหลัก

CratePurposeNotes
axumเฟรมเวิร์กสำหรับการเราต์ HTTP, ตัวแยกข้อมูล (extractors) และแฮนด์เลอร์รากฐานหลักของระบบ ใช้ร่วมกับฟีเจอร์ macros สำหรับ #[debug_handler]
tokioรันไทม์ asyncใช้ features = ["full"] ยกเว้นในกรณีที่คุณต้องการลดขนาดดีเพนเดนซีให้เหลือน้อยที่สุด
towerนามธรรมและยูทิลิตี้สำหรับมิดเดิลแวร์จัดเตรียม ServiceBuilder, ServiceExt (สำหรับ oneshot ในการทดสอบ) และเลเยอร์ที่ประกอบต่อกันได้
tower-httpมิดเดิลแวร์เฉพาะสำหรับ HTTPCORS, การบีบอัดข้อมูล, tracing, การหมดเวลา (timeouts), หมายเลขคำขอ (request IDs), การจำกัดขนาดบอดี้ และอื่นๆ โดยเปิดใช้ฟีเจอร์ได้ตามต้องการ
hyperอิมพลีเมนเทชันพื้นฐานของ HTTPแทบจะไม่ได้เรียกใช้ hyper โดยตรงเมื่อพัฒนาบน Axum แต่มันคือเอ็นจิน HTTP ตัวจริงที่ขับเคลื่อนอยู่เบื้องหลัง

การซีเรียลไลซ์และข้อมูล

CratePurposeNotes
serdeเฟรมเวิร์กสำหรับการซีเรียลไลซ์ใช้ features = ["derive"] สำหรับแมโคร #[derive(Serialize, Deserialize)]
serde_jsonการซีเรียลไลซ์และดีซีเรียลไลซ์ JSONตัวแยกข้อมูล Json ของ Axum ทำงานโดยใช้ตัวนี้อยู่เบื้องหลัง
uuidการสร้างและการพาร์ส UUIDใช้ features = ["v4", "serde"] สำหรับการสุ่ม UUID ที่รองรับการทำงานร่วมกับ serde
chronoการจัดการวันและเวลาใช้ features = ["serde"] สำหรับการซีเรียลไลซ์ แนะนำให้ใช้ DateTime<Utc> สำหรับการเก็บ timestamp

ฐานข้อมูล

CratePurposeNotes
sqlxการทำงานกับ SQL แบบ async พร้อมการตรวจสอบความถูกต้องตั้งแต่ตอนคอมไพล์ตัวเลือกอันดับหนึ่งสำหรับโปรเจกต์ Axum ส่วนใหญ่ รองรับทั้ง PostgreSQL, MySQL และ SQLite
dieselORM และตัวสร้างคิวรีที่ปลอดภัยต่อชนิดข้อมูล (type-safe)เติบโตเต็มที่และผ่านการทดสอบมาอย่างยาวนาน ใช้ diesel-async สำหรับการรองรับ async
sea-ormORM แบบ async สไตล์ ActiveRecordน่าสนใจเป็นอย่างยิ่งหากการเขียน Raw SQL ดูยุ่งยากซับซ้อนเกินไปสำหรับความต้องการของคุณ
axum-sqlx-txทรานแซกชัน SQLx ที่ผูกขอบเขตกับแต่ละคำขอ (request-scoped)เปิดทรานแซกชันให้อัตโนมัติในแต่ละคำขอ จากนั้นจะ commit หรือ rollback ตามสถานะการตอบกลับของการร้องขอนั้น

การจัดการข้อผิดพลาด

CratePurposeNotes
thiserrorแมโคร derive สำหรับสร้างชนิดข้อมูลข้อผิดพลาดที่กำหนดขึ้นเองเราใช้สิ่งนี้สำหรับข้อผิดพลาดในฝั่งโดเมนและ enum AppError ของเราที่จำเป็นต้อง pattern match แยกตามวาเรียนต์
anyhowชนิดข้อมูลข้อผิดพลาดที่ยืดหยุ่นพร้อมการต่อบริบท (context chaining)เหมาะอย่างยิ่งสำหรับวาเรียนต์แบบครอบจักรวาลอย่าง Internal และในโค้ดส่วนโครงสร้างพื้นฐาน อย่าลังเลที่จะใช้ .context() เพื่อบอกที่มาที่ไป

การตรวจสอบความถูกต้อง

CratePurposeNotes
validatorการตรวจสอบความถูกต้องของอินพุตโดยใช้ deriveรองรับ email, url, length, range ตลอดจนตัวตรวจสอบแบบกำหนดเอง (custom validators)
gardeตัวเลือกการตรวจสอบความถูกต้องทางเลือกที่ใช้ const genericsมิติใหม่ที่ต่อยอดจาก validator พร้อมรูปแบบ API ที่ทันสมัยและแตกต่างออกไป
axum-validตัวแยกข้อมูล (extractors) ที่ตรวจสอบความถูกต้องสำเร็จรูปสำหรับ Axumทำงานร่วมกับ validator, garde และ validify ได้อย่างแนบเนียน ช่วยให้คุณไม่ต้องเขียนตัวแยกข้อมูลเอง

การยืนยันตัวตนและความปลอดภัย

CratePurposeNotes
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มิดเดิลแวร์สำหรับจัดการเซสชันจัดการเซสชันฝั่งเซิร์ฟเวอร์พร้อมแบ็กเอนด์ที่สามารถสลับเปลี่ยนได้ตามต้องการ

การตั้งค่า

CratePurposeNotes
configการโหลดการตั้งค่าแบบแบ่งเลเยอร์ (layered configuration)รองรับทั้งการอ่านจากไฟล์, ตัวแปรสภาพแวดล้อม และหลากหลายรูปแบบไฟล์
dotenvyการโหลดค่าจากไฟล์ .envเครตที่ฟอร์กมาจาก dotenv ดั้งเดิม ควรเรียกใช้ .ok() แทน .unwrap() เพื่อไม่ให้ระบบหยุดทำงานเมื่อขึ้น production
secrecyการปกป้องข้อมูลที่ละเอียดอ่อนห่อหุ้มข้อมูลลับด้วย SecretString ซึ่งจะช่วยซ่อนค่าดังกล่าวใน debug log และล้างข้อมูลออกจากหน่วยความจำทันทีเมื่อถูก drop

การสังเกตการณ์ (Observability)

CratePurposeNotes
tracingการบันทึกข้อมูลแบบมีโครงสร้างและสแปน (structured logging and spans)หากคุณต้องการทำ structured logging ใน Rust นี่คือเครื่องมือมาตรฐานที่ทุกคนเลือกใช้
tracing-subscriberการกำหนดค่าเอาต์พุตสำหรับ tracingใช้ features = ["env-filter", "json"] สำหรับการกรองล็อกตามตัวแปรสภาพแวดล้อมและการส่งออกในรูปแบบ JSON
tracing-opentelemetryสะพานเชื่อมระหว่าง tracing กับ OpenTelemetryแปลงสแปนของ tracing ให้กลายเป็นสแปนของ OpenTelemetry สำหรับ distributed tracing
opentelemetryOpenTelemetry APIAPI แกนหลักสำหรับระบบ distributed tracing และเมตริก
opentelemetry-otlpตัวส่งออกข้อมูล (exporter) OTLPส่งออกข้อมูลเทรซไปยัง Jaeger, Tempo, Datadog และแบ็กเอนด์อื่นๆ ที่รองรับมาตรฐาน OTLP
axum-tracing-opentelemetryการผสานการทำงานระหว่าง OpenTelemetry กับ Axumกระจาย trace context ไปตามคำขอต่างๆ ของ Axum โดยอัตโนมัติ

เอกสารประกอบ API

CratePurposeNotes
utoipaการสร้างสเปก OpenAPI ตั้งแต่ตอนคอมไพล์สร้างสเปก OpenAPI 3.0 โดยอัตโนมัติจากแอตทริบิวต์ในโค้ด
utoipa-swagger-uiSwagger UI สำหรับ utoipaให้บริการหน้าเว็บ UI เอกสาร API แบบโต้ตอบได้ผ่านเส้นทางที่สามารถกำหนดค่าได้

การทดสอบ

CratePurposeNotes
tower (ServiceExt)การทดสอบการผสานระบบโดยไม่ต้องสตาร์ตเซิร์ฟเวอร์ใช้ oneshot() เพื่อส่งคำขอทดสอบผ่านเราเตอร์โดยตรง
mockallการสร้าง mock อ็อบเจกต์อัตโนมัติสร้าง mock implementation ของเทรตต่างๆ สำหรับการทำยูนิตเทสต์
axum-testไลบรารีการทดสอบสำหรับ Axumจัดเตรียม TestClient ที่ใช้งานง่ายและมี API สะดวกกว่าการเรียก oneshot เปล่าๆ

ไคลเอนต์ HTTP

CratePurposeNotes
reqwestไคลเอนต์ HTTP แบบ asyncไคลเอนต์ HTTP ที่พบได้บ่อยที่สุดในโปรเจกต์ Rust รองรับ async โดยกำเนิดพร้อมระบบ connection pooling

gRPC

CratePurposeNotes
tonicเฟรมเวิร์ก gRPCไคลเอนต์และเซิร์ฟเวอร์ gRPC แบบ async โดยสมบูรณ์ เชื่อมต่อกับมิดเดิลแวร์ของ Tower ได้อย่างไร้รอยต่อ
tonic-prostรันไทม์ Tonic + Prostรองรับการทำงานในระดับรันไทม์สำหรับเซอร์วิสของ tonic ที่ใช้ชนิดข้อมูลที่สร้างจาก prost
prostProtocol Buffersการซีเรียลไลซ์และดีซีเรียลไลซ์ Protobuf ที่ tonic เลือกใช้สำหรับชนิดข้อมูลของข้อความ
tonic-prost-buildการสร้างโค้ดจากไฟล์ protoคอมไพล์ไฟล์ .proto ออกมาเป็นโค้ด Rust ในช่วงบิลด์ โดยระบุไว้ใน [build-dependencies] (เข้ามาแทนที่การใช้ tonic-build โดยตรงตั้งแต่ tonic 0.14)
tonic-reflectionระบบ reflection บนเซิร์ฟเวอร์ gRPCช่วยให้เครื่องมืออย่าง grpcurl สามารถค้นหาและตรวจสอบ API ของเซอร์วิสได้โดยตรง

ยูทิลิตี้แอซิงก์

CratePurposeNotes
tokio-utilยูทิลิตี้เสริมสำหรับ Tokioจัดเตรียม CancellationToken สำหรับการปิดระบบอย่างเป็นระเบียบ พร้อมทั้ง codecs และตัวช่วยอำนวยความสะดวกอื่นๆ
futuresตัวเชื่อมและประมวลผล future (combinators)จัดเตรียม FuturesUnordered, StreamExt และยูทิลิตี้อื่นๆ สำหรับการทำงานกับ async streams

งานเบื้องหลัง

CratePurposeNotes
apalisการประมวลผลงานเบื้องหลังปลอดภัยต่อชนิดข้อมูล (type-safe), ขยายระบบได้ง่าย รองรับแบ็กเอนด์ทั้ง PostgreSQL, Redis และ SQLite พร้อมระบบมอนิเตอร์และการทำ graceful shutdown ในตัว
fangคิวงานแบบคงทนถาวร (persistent)แยกเวิร์กเกอร์ทำงานบนทาสก์ Tokio ต่างหาก พร้อมระบบรีสตาร์ตอัตโนมัติเมื่อเกิด panic, การตั้งเวลาแบบ cron และระบบหน่วงเวลาก่อนลองใหม่ (backoff)
backieคิวทาสก์แบบ asyncขับเคลื่อนด้วย PostgreSQL ออกแบบมาสำหรับการสเกลในแนวนอนข้ามหลายโพรเซส