Xây dựng RESTful API chuẩn "Industry Standard" với Spring Boot

Viết API thì dễ, nhưng viết API để dễ bảo trì, dễ mở rộng và client dễ sử dụng (DX - Developer Experience) thì cần tuân thủ các Best Practices.

1. Luôn sử dụng DTO (Data Transfer Object)

Tuyệt đối không trả về Entity trực tiếp cho Client.

• Lộ thông tin nhạy cảm (password, salt).
• Gây lỗi LazyInitializationException hoặc Infinite Recursion (JSON).

Bad:

@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
    return userRepository.findById(id).get();
}

Good:

@GetMapping("/{id}")
public ResponseEntity<UserResponseDTO> getUser(@PathVariable Long id) {
    User user = userService.getById(id);
    return ResponseEntity.ok(userMapper.toDto(user));
}

2. Global Exception Handling

Đừng try-catch lắt nhắt trong Controller. Hãy dùng @RestControllerAdvice để bắt lỗi tập trung.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ProblemDetail handleNotFound(ResourceNotFoundException ex) {
        return ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
    }
}

Sử dụng ProblemDetail (chuẩn RFC 7807) có sẵn từ Spring Boot 3 để trả về lỗi chuẩn hóa.

3. Pagination & Sorting

Đừng bao giờ findAll() mà không có phân trang. Sử dụng Pageable trong Controller arguments:

@GetMapping
public Page<UserDTO> getUsers(Pageable pageable) {
    return userService.findAll(pageable);
}

Request: GET /users?page=0&size=20&sort=createdAt,desc

4. API Versioning

Luôn luôn versioning API ngay từ ngày đầu tiên.

• URI Versioning: /api/v1/users (Phổ biến nhất)
• Header Versioning: X-API-VERSION: 1

Tổng kết

Một API tốt là một API "nhàm chán" - tức là nó hoạt động đúng như mong đợi, chuẩn mực và không gây bất ngờ cho người sử dụng.