การจัดการข้อผิดพลาด
ถ้าคุณเคยพัฒนาเว็บเซอร์วิสมาระยะหนึ่ง คุณจะตระหนักได้ว่าการจัดการข้อผิดพลาดแท้จริงแล้วคือการตอบสนองความต้องการของผู้รับข้อมูล 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” เชื่อผมเถอะครับว่ามันคุ้มค่าจริงๆ