Fix lỗi Rust panic 'attempt to add with overflow' — Tràn số nguyên

Chuyện gì đã xảy ra

Bạn chạy chương trình Rust ở chế độ debug và gặp lỗi này:

thread 'main' panicked at 'attempt to add with overflow', src/main.rs:5:15

Lỗi này xuất hiện khi phép tính số nguyên cho ra kết quả vượt ngoài phạm vi kiểu dữ liệu có thể chứa. Cộng thêm 1 vào u8 đang ở giá trị 255 là ví dụ điển hình. Tương tự với một bộ đếm i32 vượt quá i32::MAX (2.147.483.647).

Đây là cái bẫy: panic này chỉ xảy ra trong bản build debug. Ở chế độ release (--release), Rust âm thầm wrap around — không panic, chỉ là giá trị sai. Đó là lý do bạn có thể gặp một bug vượt qua toàn bộ test ở staging rồi phát nổ trên production.

Tái hiện lỗi

fn main() {
    let x: u8 = 255;
    let y = x + 1; // thread 'main' panicked at 'attempt to add with overflow'
    println!("{}", y);
}

Chạy với cargo run (debug) và bạn sẽ thấy panic. Chuyển sang cargo run --release thì thay vì panic, bạn sẽ âm thầm nhận được 0 — điều này còn tệ hơn, vì không có gì báo cho bạn biết đã có sự cố.

Debug: tìm nguồn gốc lỗi

Thông báo panic đã bao gồm tên file và số dòng. Thông thường thế là đủ. Với call stack sâu, hãy chạy:

RUST_BACKTRACE=1 cargo run

Quét backtrace để tìm frame đầu tiên trong code của bạn — bỏ qua các phần nội bộ của std và core. Đó chính là nơi xảy ra overflow.

Một điều nữa cần kiểm tra: bạn có đang ép kiểu giữa các loại dữ liệu trước khi thực hiện phép tính không? Một cái bẫy phổ biến là thu hẹp u64 xuống u32 bằng as rồi thực hiện số học trên giá trị đã bị cắt. Overflow xảy ra sau khi ép kiểu, còn giá trị ban đầu trông vẫn ổn.

Các giải pháp

Tùy chọn 1: Dùng checked arithmetic (khuyến nghị khi logic có thể thất bại)

checked_add, checked_sub và checked_mul trả về Option<T>. Overflow sẽ cho bạn None — bạn xử lý tường minh thay vì để panic.

fn main() {
    let x: u8 = 255;
    match x.checked_add(1) {
        Some(result) => println!("Result: {}", result),
        None => println!("Overflow! Handle it here."),
    }
}

Dùng cách này khi overflow thực sự có nghĩa là có sự cố — tính độ dài byte, chỉ số mảng, tổng tiền, số thứ tự message.

Tùy chọn 2: Dùng saturating arithmetic (giới hạn ở min/max)

Các phép tính saturating giới hạn tại biên của kiểu dữ liệu thay vì wrap hoặc panic. Chạm trần thì dừng ở đó.

fn main() {
    let x: u8 = 255;
    let y = x.saturating_add(1); // y == 255, not 0
    println!("{}", y);
}

Phù hợp cho bộ đếm, thanh máu, chỉ số cường độ tín hiệu — những nơi mà "kẹt ở max" tốt hơn là panic hay giá trị rác.

Tùy chọn 3: Dùng wrapping arithmetic (wrap-around có chủ ý)

Hashing, checksum và thao tác byte cấp thấp đôi khi cần modular arithmetic một cách có chủ ý. wrapping_add làm rõ ý định đó trong code:

fn main() {
    let x: u8 = 255;
    let y = x.wrapping_add(1); // y == 0
    println!("{}", y);
}

Bất kỳ ai đọc code này đều biết việc wrap là cố ý, không phải một bug đang chờ được phát hiện.

Tùy chọn 4: Dùng kiểu số nguyên lớn hơn

Đôi khi giải pháp đúng đắn chỉ là dùng kiểu lớn hơn. Nếu bạn đang lưu điểm số dưới dạng u32 nhưng tổng điểm của hai người chơi có thể vượt quá 4.294.967.295, hãy chuyển sang u64:

fn add_scores(a: u64, b: u64) -> u64 {
    a + b // safe up to 18,446,744,073,709,551,615
}

Hiệu quả khi phạm vi giá trị có giới hạn và bạn chỉ cần thêm dư địa. Không phải cách sửa phù hợp nếu đầu vào thực sự không có giới hạn — checked arithmetic xử lý trường hợp đó tốt hơn.

Tùy chọn 5: Bật kiểm tra overflow trong release mode

Bản build release bỏ qua kiểm tra overflow theo mặc định. Bật toàn cục trong Cargo.toml:

[profile.release]
overflow-checks = true

Tốn thêm một chút hiệu năng, nhưng nó bắt được overflow trên production. Đáng làm với code quan trọng về an toàn hoặc khi đang truy tìm một bug số học khó phát hiện.

Chọn cách sửa phù hợp

Overflow là bug → dùng checked_* và xử lý None tường minh
Overflow nên giới hạn lại → dùng saturating_*
Overflow là có chủ ý → dùng wrapping_*
Chỉ cần thêm dư địa → dùng kiểu rộng hơn (u64, i64, hoặc usize)

Xác nhận bản sửa

Kiểm tra cả hai chế độ build sau khi thay đổi:

# Debug build — trước đây bị panic
cargo run

# Release build — trước đây bị sai âm thầm
cargo run --release

Nếu bạn dùng checked_add, hãy viết test bao phủ trường hợp overflow:

#[cfg(test)]
mod tests {
    #[test]
    fn test_no_overflow() {
        let x: u8 = 255;
        assert_eq!(x.checked_add(1), None);
    }

    #[test]
    fn test_normal_add() {
        let x: u8 = 100;
        assert_eq!(x.checked_add(50), Some(150));
    }
}

Chạy với cargo test để xác nhận.

Bài học rút ra

Sự khác biệt giữa debug và release thực sự rất nguy hiểm. Test vượt qua trong debug vì overflow gây panic ầm ĩ. Ship bản build release và overflow đó sẽ wrap âm thầm — output sai, không có lỗi, không có dấu hiệu gì. Rất nhiều bug Rust ngoài thực tế đi theo đúng mô hình này.

Mục tiêu không chỉ là dừng panic. Mà là làm cho hành vi overflow trở nên có chủ ý — để người đọc code tiếp theo biết rằng wrap, clamp hay lỗi là lựa chọn đúng.

Khi kiểm tra code nặng về số học, hãy chú ý đến các phép tính liên quan đến kiểu nhỏ: u8, u16, i32. Với mỗi phép tính, hãy hỏi: điều gì xảy ra khi nó chạm giới hạn? Nếu câu trả lời đòi hỏi phải đọc ba hàm ngược lên call stack, đó là tín hiệu — hãy thay toán tử trần bằng checked_* hoặc saturating_* để ý định trở nên không thể bỏ qua.