Có lần mình deploy một service Rust nhận webhook từ đối tác. Chạy êm đúng ba tuần, rồi một sáng log đỏ lòm: missing field và invalid type: null. Đối tác thêm một field mới, đổi một field từ số sang chuỗi, không báo ai. Service của mình parse fail, trả 400, đối tác retry liên tục.

Lỗi không nằm ở Rust, cũng không nằm ở serde. Nó nằm ở chỗ mình chưa quyết định rõ: payload lạ thì nên làm gì? Bài này đi qua mấy attribute của serde giúp mình trả lời câu đó một cách có chủ đích.

Mặc định của serde: lờ field lạ, khắt khe với field thiếu

Với struct bình thường, serde bỏ qua field thừa nhưng báo lỗi nếu thiếu field bắt buộc:

use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Webhook {
    id: String,
    amount: u64,
    note: Option<String>,
}

fn main() {
    // field "currency" thừa -> bị lờ, note thiếu -> None
    let raw = r#"{"id":"w_1","amount":500,"currency":"VND"}"#;
    let w: Webhook = serde_json::from_str(raw).unwrap();
    println!("{w:?}");
}

Option<T> được serde coi là "có thể thiếu", nên note không gây lỗi. Hành vi này hợp lý khi bạn là bên nhận dữ liệu của người khác: đối tác thêm field thì mình không chết theo.

Người gác cổng chặn gói dữ liệu lạ Ảnh: người gác cổng chặn một gói dữ liệu lạ — hình dung cho `deny_unknown_fields`, khi bạn muốn payload phải khớp tuyệt đối với struct. — ảnh minh hoạ do AI tạo (Grok Imagine)

Khi cần khắt khe: deny_unknown_fields

Ngược lại, nếu đây là file config của chính bạn thì field lạ thường là typo. Gõ timeuot thay vì timeout mà serde lờ đi thì app chạy với giá trị mặc định mà không ai biết:

#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
struct Config {
    timeout_secs: u64,
    retries: u32,
}

Giờ {"timeout_secs":5,"retries":3,"timeuot":1} báo lỗi unknown field ngay lúc khởi động. Quy tắc mình dùng: dữ liệu mình sở hữu thì deny, dữ liệu người khác gửi thì lờ. Lưu ý deny_unknown_fields không dùng chung được với #[serde(flatten)], mình từng mất nửa tiếng vì cái này.

Default, rename và alias: hấp thụ thay đổi của đối tác

Phần lớn sự cố kiểu sáng đầu tuần nằm ở field thiếu hoặc đổi tên. Ba attribute sau xử lý được khoảng 80% trường hợp:

fn default_currency() -> String { "VND".to_string() }

#[derive(Debug, Deserialize)]
struct Payment {
    #[serde(rename = "orderId", alias = "order_id")]
    order_id: String,

    #[serde(default = "default_currency")]
    currency: String,

    #[serde(default)]
    tags: Vec<String>,
}
  • rename map tên JSON kiểu camelCase sang tên Rust kiểu snake_case.
  • alias cho phép nhận thêm một tên cũ, rất tiện lúc đối tác chuyển phiên bản API.
  • default điền giá trị khi field thiếu, không cần bọc Option rồi unwrap_or khắp nơi.

Cách này liên quan trực tiếp đến tư duy type system. Nếu bạn đã đọc Send và Sync — vì sao Rc không qua được thread thì ý tưởng giống nhau: để compiler và type ép sự thật lên dữ liệu, thay vì kiểm tra rải rác bằng tay.

Mảnh ghép giá trị mặc định lấp chỗ trống Ảnh: các mảnh ghép giá trị mặc định lấp vào chỗ trống của tấm thẻ dữ liệu — đúng vai trò của `#[serde(default)]` khi field bị thiếu. — ảnh minh hoạ do AI tạo (Grok Imagine)

Một field, nhiều dạng: untagged và enum

Case làm mình đau đầu nhất là đối tác đổi amount lúc số lúc chuỗi (500 rồi "500"). Dùng enum untagged để nhận cả hai, rồi chuẩn hoá ngay ở biên:

#[derive(Debug, Deserialize)]
#[serde(untagged)]
enum Amount {
    Num(u64),
    Text(String),
}

impl Amount {
    fn value(&self) -> Result<u64, std::num::ParseIntError> {
        match self {
            Amount::Num(n) => Ok(*n),
            Amount::Text(s) => s.parse(),
        }
    }
}

Nhược điểm: khi fail, serde chỉ báo data did not match any variant, rất khó debug. Với payload có trường phân biệt rõ như "type": "refund", dùng #[serde(tag = "type")] sẽ cho lỗi dễ đọc hơn nhiều. Chỉ dùng untagged khi thật sự không còn lựa chọn.

Biển chỉ đường với nhiều cánh cửa Ảnh: biển chỉ đường với nhiều cánh cửa, mỗi cửa khớp một hình chìa khoá — giống cách enum `untagged` thử lần lượt từng variant cho đến khi khớp. — ảnh minh hoạ do AI tạo (Grok Imagine)

Lỗi parse: đừng nuốt, cũng đừng unwrap

Trong handler, parse fail nên trả lỗi có ngữ cảnh. Serde cho biết dòng, cột và đường dẫn field, tận dụng luôn:

let parsed: Result<Payment, _> = serde_json::from_slice(&body);
match parsed {
    Ok(p) => handle(p),
    Err(e) => {
        tracing::warn!(line = e.line(), column = e.column(), "bad payload: {e}");
        return Err(ApiError::BadRequest);
    }
}

Mình cũng từng nhắc về thói quen unwrap bừa ở bài đừng unwrap bừa khi xử lý lỗi trong Rust: payload từ bên ngoài là nơi unwrap nguy hiểm nhất, vì kẻ gửi dữ liệu không nằm trong tầm kiểm soát của bạn. Nếu đang chạy trên tokio, đọc thêm Tokio chậm bất thường — một dòng blocking giấu trong async để tránh parse payload khổng lồ ngay trên thread async.

Chốt lại

Hôm đó mình sửa bằng ba dòng: default cho field mới, alias cho tên cũ, enum untagged cho amount. Từ đó, cứ viết struct nhận dữ liệu ngoài là mình tự hỏi ba câu: field thiếu thì sao, field lạ thì sao, field đổi kiểu thì sao. Bạn đang nhận payload nào mà chưa trả lời được cả ba câu?

Tài liệu gốc đáng đọc: serde.rs — container attributes.

📋 Phụ lục thuật ngữ

Thuật ngữ Giải thích ngắn
serde Thư viện serialize/deserialize chuẩn của Rust
deny_unknown_fields Báo lỗi nếu JSON có field struct không khai báo
default Điền giá trị mặc định khi field thiếu
alias Chấp nhận thêm tên field khác khi deserialize
untagged Enum thử lần lượt từng variant, không cần field phân biệt
flatten Gộp field của struct con vào cấp ngoài

Xem các bài viết khác