Sửa lỗi javax.validation.ConstraintViolationException trong Spring Boot Persistence

Thông báo lỗiCó khả năng bạn đang nhìn thấy một stack trace (truy vết ngăn xếp) trông như thế này trong log ứng dụng của mình:

javax.validation.ConstraintViolationException: Validation failed for classes [com.example.entity.User] during persist time for groups [javax.validation.groups.Default]
    at org.hibernate.cfg.beanvalidation.TypeSafeActivator.getValidator(TypeSafeActivator.java:155)
    at org.hibernate.cfg.beanvalidation.BeanValidationEventListener.validate(BeanValidationEventListener.java:140)
    at org.hibernate.cfg.beanvalidation.BeanValidationEventListener.onPreInsert(BeanValidationEventListener.java:80)

Tại sao lỗi này xảy ra ở lớp cơ sở dữ liệuNgoại lệ này thường xảy ra ngay khi bạn nghĩ rằng dữ liệu của mình đã an toàn. Bạn đã vượt qua các bước kiểm tra ban đầu của Controller, logic Service đã hoàn tất và transaction (giao dịch) đã sẵn sàng để commit. Đột nhiên, Hibernate báo lỗi.

Khác với MethodArgumentNotValidException, vốn bắt lỗi ở cấp độ @RequestBody, ngoại lệ này được kích hoạt bởi BeanValidationEventListener của Hibernate. Nó là một tấm lưới an toàn cuối cùng. Hibernate thực hiện kiểm tra vào giây cuối cùng trước khi gửi câu lệnh SQL đến cơ sở dữ liệu.

Nó đảm bảo rằng entity tuân thủ các annotation như @NotNull, @Size, hoặc @Email. Nếu một trường duy nhất không đạt yêu cầu, toàn bộ transaction sẽ bị rollback. Điều gây khó chịu nhất là thông báo lỗi mặc định sẽ không cho bạn biết chính xác trường nào đã gây ra lỗi.

Các bước khắc phục### 1. Hiển thị các vi phạm bị ẩnRào cản chính ở đây là khả năng hiển thị. Hibernate biết chính xác cái gì đã lỗi, nhưng nó không ghi chi tiết vào log theo mặc định. Bạn có thể hiển thị các vi phạm này bằng cách bao bọc lệnh gọi save hoặc triển khai một global exception handler để trích xuất metadata.

try {
    userRepository.save(user);
} catch (ConstraintViolationException e) {
    e.getConstraintViolations().forEach(violation -> {
        log.error("Validation failed for property: {}", violation.getPropertyPath());
        log.error("Invalid value: {}", violation.getInvalidValue());
        log.error("Reason: {}", violation.getMessage());
    });
    throw e;
}

2. Đồng bộ hóa ràng buộc giữa DTO và EntityRàng buộc không khớp là nguyên nhân hàng đầu dẫn đến lỗi này. Nếu API của bạn chấp nhận một giá trị null vì DTO lỏng lẻo, nhưng Entity lại nghiêm ngặt, lớp persistence sẽ từ chối bản ghi đó. Hãy xem xét trường hợp trường email là tùy chọn trong JSON nhưng lại bắt buộc trong cơ sở dữ liệu.

- **Entity:** ` @website/content/errors/en/excel/fix-ref-error-in-excel-invalid-cell-references-after-deleting-rows-or-columns.md(nullable = false) @NotNull private String username;`
- **DTO:** ` @NotBlank private String username;`

Hãy luôn đảm bảo rằng mọi ràng buộc trên Entity của bạn đều được phản ánh hoặc thắt chặt hơn bởi DTO đổ dữ liệu vào đó. Điều này giúp đẩy các lỗi ngược về Controller, nơi chúng dễ xử lý hơn.

3. Kiểm tra các logic mapping đối tượng thủ côngNếu bạn sử dụng MapStruct hoặc các builder thủ công để chuyển đổi DTO sang Entity, hãy kiểm tra logic mapping. Rất dễ vô tình ghi đè một trường bắt buộc bằng giá trị null từ một trường DTO tùy chọn. Đây là một mẫu lỗi phổ biến trong các thao tác cập nhật (update) khi chỉ một nửa đối tượng được cung cấp trong request body.

4. Xác minh các dependency cho ValidationNếu validation hoàn toàn không chạy, hoặc nếu bạn đang chuyển sang Spring Boot 3, hãy đảm bảo bạn có starter chính xác. Trong Spring Boot 3, package được chuyển từ javax.validation sang jakarta.validation.

<!-- Cần thiết cho Spring Boot 2.x và 3.x -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

Xác minh cách khắc phụcSử dụng @DataJpaTest để tái hiện lỗi. Điều này cho phép bạn kiểm tra lớp persistence một cách cô lập mà không cần khởi động toàn bộ web server, giúp tiết kiệm 30-60 giây cho mỗi lần chạy test.

 @DataJpaTest
public class UserRepositoryTest {
    @Autowired
    private UserRepository userRepository;

    @website/content/errors/en/react/fix-warning-an-update-to-inside-a-test-was-not-wrapped-in-act-in-react-testing.md
    public void should_FailOnEmptyUsername() {
        User user = new User();
        user.setUsername(""); // Kích hoạt @NotBlank
        
        assertThrows(ConstraintViolationException.class, () -> {
            userRepository.saveAndFlush(user);
        });
    }
}

Lưu ý việc sử dụng saveAndFlush(). Hibernate thường trì hoãn việc validation cho đến khi session thực hiện flush. Sử dụng flush() buộc việc validation phải xảy ra ngay lập tức trong phạm vi của test.

Mẹo xử lý sự cố

- **Chuyển đổi sang Jakarta:** Nếu bạn đang dùng Spring Boot 3+, hãy thay đổi tất cả các import từ `javax.persistence` và `javax.validation` sang `jakarta.persistence` và `jakarta.validation`.
- **Ghi log SQL:** Thiết lập `logging.level.org.hibernate.type.descriptor.sql.BasicBinder=TRACE`. Điều này giúp hiển thị các giá trị chính xác mà Hibernate đang gắn (bind) vào câu lệnh SQL, giúp bạn phát hiện các giá trị null hoặc chuỗi bị cắt ngắn.
- **Chế độ Validation:** Tránh thiết lập `javax.persistence.validation.mode` thành `none`. Mặc dù điều này giúp dừng ngoại lệ, nhưng nó chỉ đơn thuần là trì hoãn việc báo lỗi cho đến khi xuống đến cơ sở dữ liệu, dẫn đến lỗi `DataIntegrityViolationException` ít thông tin hữu ích hơn.