Từ Zero đến CRUD - Boilerplate Spring Boot H2 Dễ Dàng Sử Dụng

TL;DR: Một bộ khởi động Spring Boot thân thiện cung cấp cho bạn một API Book CRUD hoạt động với H2, DTOs, lớp dịch vụ và xử lý lỗi toàn cầu — chỉ cần clone, chạy và bắt đầu thử nghiệm trong chưa đầy một phút.

Giới thiệu

Khi tôi mới bắt đầu làm việc với backend, tôi đã lãng phí cả buổi chiều chỉ để kết nối một cơ sở dữ liệu chỉ để thử nghiệm một endpoint. Điều đó thật nhàm chán và không cần thiết. Boilerplate này thay đổi điều đó: nó là một khung xương nhỏ gọn, thực tế giúp bạn tập trung vào ý tưởng mà bạn thực sự quan tâm.

Kho lưu trữ này giải quyết vấn đề thời gian thiết lập lãng phí bằng cách cung cấp một ví dụ tối thiểu, được cấu trúc tốt mà bạn có thể an toàn sửa đổi, mở rộng và sao chép vào các dự án thực tế.
Lý tưởng cho: sinh viên, cựu sinh viên bootcamp, lập trình viên tự do và bất kỳ ai muốn một prototype nhanh và sạch.

Tại sao nên sử dụng boilerplate này?

Tiết kiệm thời gian: Clone, chạy và có một API CRUD đầy đủ trong khoảng 60 giây. Không cần cài đặt cơ sở dữ liệu, không cần cấu hình đau đớn.
Thực tế nhưng tối thiểu: Cấu trúc phản ánh các ứng dụng sản xuất (DTOs, lớp dịch vụ, kho lưu trữ, trình xử lý ngoại lệ toàn cầu) để việc học có thể chuyển giao cho các dự án thực tế.
Thực hành tốt nhất được xác định rõ: Thực thi phân chia mối quan tâm (controller → service → repo), hình dạng lỗi nhất quán, và sử dụng DTO để API của bạn vẫn duy trì được tính bảo trì khi phát triển.
Bao gồm: Cơ sở dữ liệu H2 trong bộ nhớ với dữ liệu mẫu data.sql, một bộ sưu tập Postman và các bài kiểm tra cơ bản để bạn bắt đầu.

Tính năng

API CRUD Spring Boot 3 tối thiểu cho tài nguyên Book — id, title, author.
Cơ sở dữ liệu H2 trong bộ nhớ giúp thử nghiệm cục bộ không cần cấu hình (với bảng điều khiển H2).
Các yêu cầu/phản hồi dựa trên DTO để giữ cho các controller gọn gàng và có thể phiên bản.
Lớp dịch vụ tách biệt logic kinh doanh để dễ dàng kiểm tra.
Xử lý ngoại lệ toàn cầu với một ResourceNotFoundException tùy chỉnh để đảm bảo lỗi frontend nhất quán.
Dữ liệu mẫu được tải khi khởi động thông qua data.sql.

Lộ trình (ngắn gọn và có thể thực hiện):

Thêm Swagger/OpenAPI cho tài liệu tương tác.
Ví dụ xác thực JWT + kiểm soát truy cập dựa trên vai trò.
Postgres + Flyway để di chuyển dữ liệu bền vững.
Phân trang, sắp xếp và lọc trên các endpoint danh sách.

Thiết lập nhanh, đơn giản

Tôi thích hướng dẫn đơn giản mà bạn có thể thực hiện theo.

Thiết lập cục bộ (phiên bản năm phút)

Clone:

bash Copy

git clone https://github.com/boileragents/springboot-h2-crud-demo
cd springboot-h2-crud-demo

Mở trong IDE của bạn (IntelliJ, VS Code hoặc Eclipse).
Chạy:

bash Copy

mvn spring-boot:run

Truy cập http://localhost:8080 — API của bạn đã hoạt động.
Thử nghiệm với bảng điều khiển H2 tại http://localhost:8080/h2-console (JDBC: jdbc:h2:mem:testdb, user: sa, mật khẩu trống).

Để xây dựng và chạy jar:

bash Copy

mvn clean package
java -jar target/springboot-h2-crud-demo-0.0.1-SNAPSHOT.jar

Cách sử dụng & Ví dụ

Các endpoint API (tên thân thiện)

Phương thức	Endpoint	Tên thân thiện
POST	`/books`	Tạo Sách
GET	`/books`	Danh sách Sách
GET	`/books/{id}`	Lấy Sách theo ID
PUT	`/books/{id}`	Cập nhật Sách
DELETE	`/books/{id}`	Xóa Sách

Thử nghiệm: lấy tất cả sách

bash Copy

GET http://localhost:8080/books

Ví dụ phản hồi:

json Copy

[
  { "id": 1, "title": "Spring Boot Basics", "author": "John Doe" },
  { "id": 2, "title": "A Practical Guide", "author": "Jane Smith" }
]

Tạo một cuốn sách (cURL)

bash Copy

curl -X POST "http://localhost:8080/books" \
  -H "Content-Type: application/json" \
  -d '{"title":"Spring Boot Basics","author":"John Doe"}'

Ví dụ phản hồi:

json Copy

{ "id": 3, "title": "Spring Boot Basics", "author": "John Doe" }

Cấu hình

Các tệp và cài đặt quan trọng:

application.properties — cổng máy chủ, bảng điều khiển H2 và các thuộc tính mặc định của datasource.
data.sql — dữ liệu khởi tạo được tải khi khởi động.
Chuyển sang cơ sở dữ liệu sản xuất bằng cách cập nhật các thuộc tính datasource và thêm các di chuyển (Flyway / Liquibase).

Cấu trúc Dự án (thực và nhỏ)

Copy

.
├── src/
│   ├── main/java/com/demo
│   │   ├── controller/        # BookController.java
│   │   ├── dto/               # BookDTO.java
│   │   ├── entity/            # Book.java
│   │   ├── service/           # BookService.java
│   │   ├── repository/        # BookRepository.java
│   │   └── exception/         # GlobalExceptionHandler.java, ResourceNotFoundException.java
│   └── main/resources/
│       ├── application.properties
│       └── data.sql
├── springboot-h2-crud-demo.postman_collection.json     #Bộ sưu tập Postman để kiểm tra
├── pom.xml
└── README.md

Nhỏ gọn, rõ ràng và dễ mở rộng.

Bài học nhỏ, thực tiễn (lời khuyên thực tế)

DTOs sớm: Chúng giúp việc phiên bản và định hình phản hồi trở nên dễ dàng.
Giữ cho controller mỏng: Controller nên điều phối, không thực hiện các quy tắc kinh doanh. Đặt logic trong các dịch vụ.
Định dạng lỗi toàn cầu: Một hình dạng lỗi cho tất cả các endpoint giúp các nhà phát triển frontend rất hài lòng.
Kiểm tra lớp dịch vụ: Các bài kiểm tra đơn vị cho logic kinh doanh nhanh chóng và ổn định; các bài kiểm tra tích hợp có thể bao gồm việc lưu trữ.

Và hãy nhớ: kho lưu trữ này khuyến khích các thực hành tốt nhất — hãy áp dụng chúng để prototype tiếp theo của bạn không trở thành cơn ác mộng bảo trì.

Kiểm tra

Chạy các bài kiểm tra đơn vị:

bash Copy

mvn test

Thêm các bài kiểm tra tích hợp với Testcontainers nếu bạn muốn chạy CI với cơ sở dữ liệu.

Triển khai & Ý tưởng CI

Xây dựng và phát hành một hình ảnh Docker:

bash Copy

docker build -t boileragents/springboot-h2-crud-demo:latest .

Quy trình CI (được khuyến nghị): Xây dựng → Kiểm tra → Phát hành hình ảnh → Triển khai lên staging → Thăng tiến lên sản xuất.
Muốn một đoạn mã GitHub Actions? Tôi có thể thêm một workflow đơn giản cho việc xây dựng/kiểm tra/phát hành.

Mở rộng & Tùy chỉnh

Thêm các endpoint: Controller mới + DTO + dịch vụ + kho lưu trữ. Giữ cho các bài kiểm tra đồng bộ.
Thay thế DB: Thay đổi các thuộc tính datasource và thêm di chuyển (Flyway được khuyến nghị).
Thêm xác thực: Kết nối Spring Security + JWT; bảo vệ các controller bằng các chú thích.

Khắc phục sự cố / Câu hỏi thường gặp

Ứng dụng không khởi động? Kiểm tra phiên bản Java (17+), xung đột cổng, và nhật ký để tìm các bean bị thiếu.
Bảng điều khiển H2 không thể truy cập? Đảm bảo spring.h2.console.enabled=true và URL JDBC chính xác.
Cần lưu trữ bền vững giữa các lần khởi động? Sử dụng H2 dựa trên tệp hoặc cơ sở dữ liệu bền vững (Postgres/MySQL).

Đóng góp

Các yêu cầu kéo, báo cáo lỗi và các cải tiến nhỏ đều được hoan nghênh.

Fork kho lưu trữ
Tạo một nhánh: git checkout -b feat/my-change
Chạy các bài kiểm tra và trình kiểm tra địa phương
Mở một yêu cầu kéo với mô tả rõ ràng

Vui lòng làm theo CONTRIBUTING.md và CODE_OF_CONDUCT khi có.

Giấy phép

MIT — xem LICENSE để biết chi tiết.

Về Boileragents

Boileragents xây dựng các khởi động tập trung để bạn có thể bỏ qua thiết lập và bắt đầu xây dựng.
GitHub: https://github.com/boileragents • Email: boileragents@gmail.com

Liên kết & Tài nguyên

Kho lưu trữ: https://github.com/boileragents/springboot-h2-crud-demo

Nếu bài viết này giúp bạn tiết kiệm thời gian, hãy ⭐ kho lưu trữ và để lại một ghi chú ngắn về những gì bạn muốn tiếp theo — Swagger, ví dụ về xác thực, Docker Compose, hoặc điều gì khác. Muốn một điều chỉnh tùy chỉnh? Email boileragents@gmail.com và hãy để chúng tôi thực hiện điều đó.

Từ Zero đến CRUD - Boilerplate Spring Boot H2 Dễ Dàng Sử Dụng

Từ Zero đến CRUD - Boilerplate Spring Boot H2 Dễ Dàng Sử Dụng

Giới thiệu

Tại sao nên sử dụng boilerplate này?

Tính năng

Thiết lập nhanh, đơn giản

Thiết lập cục bộ (phiên bản năm phút)

Cách sử dụng & Ví dụ

Các endpoint API (tên thân thiện)

Thử nghiệm: lấy tất cả sách

Tạo một cuốn sách (cURL)

Cấu hình

Cấu trúc Dự án (thực và nhỏ)

Bài học nhỏ, thực tiễn (lời khuyên thực tế)

Kiểm tra

Triển khai & Ý tưởng CI

Mở rộng & Tùy chỉnh

Khắc phục sự cố / Câu hỏi thường gặp

Đóng góp

Giấy phép

Về Boileragents

Liên kết & Tài nguyên

Bình luận