Xây dựng REST API hoàn chỉnh với Spring Boot 3

Spring Boot 3 chạy trên Java 17+, hỗ trợ virtual threads, GraalVM native image và chuẩn hoá xử lý lỗi theo RFC 7807. Trong bài này, chúng ta xây dựng một REST API quản lý sách hoàn chỉnh: từ khởi tạo dự án, entity, repository cho đến validation và xử lý lỗi.

Khởi tạo dự án

Cách nhanh nhất là dùng Spring Initializr với các dependency Web, Data JPA, Validation và PostgreSQL:

curl https://start.spring.io/starter.zip \
  -d dependencies=web,data-jpa,validation,postgresql \
  -d javaVersion=21 -d type=gradle-project \
  -d artifactId=bookstore -o bookstore.zip

Giải nén, mở trong IDE là bạn đã có một project chạy được ngay với ./gradlew bootRun.

Entity và Repository

Spring Data JPA sinh sẵn toàn bộ thao tác CRUD — bạn chỉ cần khai báo interface, thậm chí viết query bằng tên phương thức:

@Entity
public class Book {
    @Id @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String title;
    private String author;
    private BigDecimal price;
    // getters & setters
}

public interface BookRepository extends JpaRepository<Book, Long> {
    List<Book> findByAuthorContainingIgnoreCase(String author);
}

REST Controller và validation

Dùng Java record làm DTO kết hợp Bean Validation — request không hợp lệ sẽ tự động trả về 400 Bad Request kèm chi tiết từng field lỗi:

public record CreateBookRequest(
    @NotBlank String title,
    @NotBlank String author,
    @Positive BigDecimal price) {}

@RestController
@RequestMapping("/api/books")
public class BookController {
    private final BookRepository books;

    public BookController(BookRepository books) {
        this.books = books;
    }

    @GetMapping
    public List<Book> all() {
        return books.findAll();
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Book create(@Valid @RequestBody CreateBookRequest req) {
        var book = new Book(req.title(), req.author(), req.price());
        return books.save(book);
    }

    @GetMapping("/{id}")
    public Book one(@PathVariable Long id) {
        return books.findById(id)
            .orElseThrow(() -> new BookNotFoundException(id));
    }
}

Xử lý lỗi chuẩn RFC 7807 với ProblemDetail

Spring Boot 3 tích hợp sẵn ProblemDetail — chỉ cần một @RestControllerAdvice là mọi lỗi trả về theo cùng một cấu trúc:

@RestControllerAdvice
class GlobalExceptionHandler {

    @ExceptionHandler(BookNotFoundException.class)
    ProblemDetail handleNotFound(BookNotFoundException ex) {
        var pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.NOT_FOUND, ex.getMessage());
        pd.setTitle("Book not found");
        return pd;
    }
}

Client giờ nhận được response lỗi thống nhất, dễ parse:

{
  "type": "about:blank",
  "title": "Book not found",
  "status": 404,
  "detail": "Book 42 does not exist"
}

Kết luận

Chưa đến 100 dòng code, chúng ta đã có một REST API đầy đủ: CRUD, validation và xử lý lỗi chuẩn hoá. Từ nền tảng này, bạn có thể bổ sung phân trang với Pageable, bảo mật với Spring Security, cache với Redis — tất cả đều là những mảnh ghép quen thuộc trong hệ sinh thái Spring.