Giáo trình Spring Boot MVC và REST API · Chương 1/12: Khởi đầu và môi trường 2026 · Bài 02/28 · Biên soạn tháng 10/2026.

Mục tiêu bài học

Tạo dự án Maven đúng phiên bản, hiểu cấu trúc thư mục và chạy HVC Academy trên máy cá nhân.

Chuẩn bị môi trường

Cài JDK 21 rồi kiểm tra java -version và javac -version. IDE và terminal phải dùng cùng JDK: một lỗi phổ biến là IDE biên dịch bằng Java 21 nhưng terminal chạy bằng Java cũ. Maven Wrapper trong mã nguồn giúp dùng bản Maven được ghi lại theo dự án; lần đầu vẫn cần Internet để tải Maven và dependency.

Vào Spring Initializr, chọn Maven, Java, Spring Boot 4.1.1, Java 21, đóng gói JAR; group com.hocvietcode, artifact hvc-academy, package com.hocvietcode.academy. Các nhóm dependency dùng trong bộ bài là Spring Web, Thymeleaf, Validation, Spring Data JPA, Security, H2, MySQL Driver, Flyway, Mail và Actuator. Mã tải về ở mục lục đã có đầy đủ cấu hình và ví dụ, nên có thể chạy trực tiếp thay vì gõ lại toàn bộ từ đầu.

Tệp trong mã nguồn mẫu: pom.xml. Đoạn dưới được trích từ tệp này; xem bản tải về để có đủ import và phần còn lại.

<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>4.1.1</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>

Đọc cấu trúc trước khi chạy

pom.xml quản lý dependency và cách build. src/main/java chứa Java; src/main/resources chứa cấu hình, template HTML, CSS và migration SQL. src/test chứa kiểm thử. target là đầu ra sinh tự động của Maven, có thể tạo lại và không phải nơi sửa nguồn.

Class HvcAcademyApplication nằm ở package gốc. @SpringBootApplication đánh dấu cấu hình chính và điểm bắt đầu quét component; main gọi SpringApplication.run để tạo context, cấu hình các thành phần rồi khởi động web server nhúng. Đặt Controller hoặc Service ngoài cây package này khiến Spring không tự phát hiện chúng.

Tệp trong mã nguồn mẫu: src/main/java/com/hocvietcode/academy/HvcAcademyApplication.java. Đoạn dưới được trích từ tệp này; xem bản tải về để có đủ import và phần còn lại.

package com.hocvietcode.academy;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class HvcAcademyApplication {

	public static void main(String[] args) {
		SpringApplication.run(HvcAcademyApplication.class, args);
	}

}

Chạy bản mẫu trên PowerShell

Biến dưới đây chỉ phục vụ tài khoản demo chạy cục bộ; hãy tự chọn một mật khẩu dài ít nhất 12 ký tự. Ứng dụng không chứa mật khẩu demo mặc định. Teacher và student dùng chung biến này để bạn kiểm tra sự khác nhau về quyền, không phải mô hình cấp tài khoản thật.

$env:HVC_DEMO_PASSWORD = Read-Host "Mật khẩu demo cục bộ (ít nhất 12 ký tự)"
.\mvnw.cmd spring-boot:run

Trên macOS/Linux, cấp quyền chạy cho mvnw nếu cần rồi dùng ./mvnw spring-boot:run với biến HVC_DEMO_PASSWORD đã đặt trong shell. Mở http://localhost:8080/courses; vào /login với teacher hoặc student. Bản mặc định dùng H2 trong bộ nhớ, dữ liệu quay về trạng thái ban đầu sau khi dừng tiến trình. Bài MySQL sẽ chuyển sang lưu bền vững.

Biết dừng và kiểm tra đúng chỗ

Đọc dòng log xác nhận ứng dụng đã started trước khi mở trình duyệt. Nếu cổng 8080 đang bận, dừng tiến trình cũ hoặc đặt SERVER_PORT=8081 rồi chạy lại. Ctrl+C dừng ứng dụng. Chạy ./mvnw test hoặc .\mvnw.cmd test để kiểm tra; cấu hình test riêng đã có mật khẩu chỉ dùng cho kiểm thử.

Khi thay phiên bản Boot sau này, nâng có chủ đích, xem migration guide và chạy lại test. Giáo trình cố định một bộ phiên bản để ví dụ nhất quán; không nên thay số phiên bản giữa các bài chỉ vì Initializr đổi mặc định.

Lỗi thường gặp và lưu ý

• Không chạy lệnh PowerShell trong tệp Java; đây là hai môi trường khác nhau.
• Không commit giá trị mật khẩu, SMTP hoặc DB thật vào application.properties.

Ghi nhớ

Đầu ra của bài là ứng dụng chạy được, hai tài khoản demo và bộ thư mục nguồn có thể đối chiếu xuyên suốt.

Tài liệu đối chiếu

• Spring Initializr
• Maven Wrapper