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.
Ả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>,
}
renamemap tên JSON kiểu camelCase sang tên Rust kiểu snake_case.aliascho 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ọcOptionrồiunwrap_orkhắ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.
Ả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.
Ả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 |
