Ngày 23/10/2026, FastAPI phát hành phiên bản 0.162.0 với một thay đổi breaking change: trường form kiểu boolean bị bỏ trống sẽ không còn tự động được hiểu là False nữa. Thay vào đó, nó dùng giá trị mặc định đã khai báo, hoặc báo lỗi thiếu trường nếu không có mặc định. Thay đổi áp dụng cho tham số Form riêng lẻ, form model và union của các form model.

Nếu bạn từng viết form HTML có checkbox bằng FastAPI, tin này liên quan trực tiếp tới bạn. Chỉ bốn ngày trước đó, phiên bản 0.147.0 còn quy định checkbox không được tick sẽ thành False; 0.162.0 đã đảo ngược quyết định đó.

Chuyện gì đã xảy ra?

Trình duyệt có một hành vi đặc biệt với checkbox: khi người dùng không tick, trình duyệt không gửi gì về trường đó. Server nhận được một form thiếu hẳn trường boolean, chứ không phải giá trị False.

Phiên bản 0.147.0, phát hành ngày 19/10/2026, chọn cách suy luận: trường boolean vắng mặt được hiểu là False, kể cả khi đó là trường bắt buộc hay có mặc định là True hoặc None. Phiên bản 0.162.0, qua pull request #16605 của Sebastián Ramírez, khôi phục cách xử lý mặc định như mọi trường khác, nhất quán với hành vi của Pydantic.

Cụ thể, trường boolean bị bỏ trống trong model sẽ không xuất hiện trong kết quả model_dump(exclude_unset=True), vì nó không được tính là trường đã gửi. Nói ngắn gọn, 0.162.0 chỉ xóa đi ngoại lệ mà 0.147.0 từng tạo ra, để trường boolean trở lại giống mọi trường khác.

Cách viết đúng cho checkbox HTML

Tài liệu FastAPI hướng dẫn rất rõ cho trường hợp phổ biến nhất: với checkbox HTML, hãy khai báo trường boolean kèm giá trị mặc định là False. Ví dụ:

from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/subscribe")
def subscribe(newsletter: bool = Form(False)):
    return {"newsletter": newsletter}

Với cách khai báo này, khi người dùng không tick checkbox, FastAPI dùng mặc định False và mọi thứ hoạt động đúng như bạn mong đợi. Ngược lại, trường boolean bắt buộc không có mặc định sẽ khiến form thiếu checkbox bị từ chối bằng lỗi validation.

Điều này có ý nghĩa gì với bạn

Trước hết, hãy kiểm tra các endpoint nhận form HTML có checkbox trước khi nâng cấp lên 0.162.0. Nếu bạn đang dựa vào hành vi “vắng mặt thành False” của 0.147.0, hãy thêm = False tường minh vào các trường checkbox. Sửa đổi này nhỏ nhưng biến hành vi ẩn thành hợp đồng rõ ràng trong code.

Thứ hai, đừng xem sự đảo ngược này là dấu hiệu framework thiếu ổn định: mục tiêu là một bộ quy tắc nhất quán, giá trị vắng mặt dùng mặc định, giá trị gửi lên thì được validate. Cuối cùng, nếu dự án của bạn chỉ nhận JSON chứ không nhận form HTML, thay đổi này gần như không ảnh hưởng tới bạn.

Bài viết liên quan

Câu hỏi thường gặp

FastAPI 0.162.0 thay đổi gì so với 0.147.0?

Phiên bản 0.147.0 suy luận trường boolean bị bỏ trống trong form thành False. Phiên bản 0.162.0 bỏ suy luận đó: trường vắng mặt dùng giá trị mặc định đã khai báo, hoặc báo lỗi thiếu trường nếu không có mặc định.

Checkbox HTML không tick có còn hoạt động không?

Có, nếu bạn khai báo trường với mặc định False, ví dụ newsletter: bool = Form(False). Khi checkbox không được tick, trình duyệt không gửi trường này và FastAPI dùng mặc định False.

Thay đổi này có ảnh hưởng tới API nhận JSON không?

Không. Request JSON và validation trực tiếp bằng Pydantic không thay đổi. Thay đổi chỉ áp dụng cho form data từ trình duyệt.

💬 Tin này ảnh hưởng tới dự án của bạn thế nào? Chia sẻ góc nhìn của bạn trong phần bình luận — mình đọc hết và sẽ tổng hợp những ý hay nhất.

Nguồn tham khảo