Spring IoC và Dependency Injection: dựng order-api đầu tiên

Spring IoC và Dependency Injection là gì? Dựng project order-api bằng Spring Boot 4, hiểu bean, constructor injection và sửa lỗi khởi động hay gặp.

Spring IoC nghĩa là thay vì code tự new các đối tượng mà nó cần, bạn khai báo mình cần gì, và Spring tạo ra, quản lý rồi đưa chúng vào cho bạn. Việc đưa vào đó gọi là Dependency Injection, và cách nên dùng nhất là truyền qua constructor.

Ở bài trước, mình thiết kế ba bảng cho đơn hàng của quán Mộc (quán cà phê tình huống minh họa của loạt bài), nhưng mọi thứ mới dừng ở SQL gõ tay. Giờ là lúc dựng ứng dụng web đầu tiên của loạt bài, tên là order-api. Từ bài này, mỗi bài sẽ thêm một phần vào project đó. Trước hết, mình cho bạn thấy project trông thế nào, rồi hiểu cái cốt lõi nhất của Spring: nó tạo và nối các đối tượng cho bạn ra sao.

Dựng project Spring Boot đầu tiên như thế nào?

Cách thông dụng nhất là dùng Spring Initializr, trang web sinh sẵn một project Spring Boot. Bạn chọn công cụ build, ngôn ngữ, phiên bản và các thư viện cần dùng. Mình chọn: Maven, Java, Spring Boot 4.1.2, Java 25, group vn.moc, artifact order-api, và một dependency là Spring Web. Spring Boot 4.1.2 yêu cầu tối thiểu Java 17 và tương thích tới Java 27, theo trang yêu cầu hệ thống của Spring Boot (mình kiểm ngày 17/11/2026). Nhiều bài hướng dẫn trên mạng vẫn dùng Spring Boot 3, nên nếu bạn thấy tên thư viện hay đường dẫn hơi khác thì nhớ bản mình dùng là 4.1.2.

Initializr trả về một file zip. Sau khi giải nén, project có cấu trúc Maven mà bạn đã gặp ở bài về Maven, cộng thêm vài file:

Cấu trúc project order-api
order-api/
├── pom.xml
├── mvnw, mvnw.cmd, .mvn/           <- Maven wrapper: chạy Maven không cần cài sẵn
└── src/
    ├── main/
    │   ├── java/vn/moc/orderapi/OrderApiApplication.java
    │   └── resources/application.properties
    └── test/java/vn/moc/orderapi/OrderApiApplicationTests.java

File pom.xml do Initializr sinh có một khác biệt lớn so với bài Maven: nó khai báo spring-boot-starter-parent làm project cha, nên bạn không phải ghi số phiên bản cho từng thư viện Spring, vì project cha đã chốt sẵn bộ phiên bản chạy tốt cùng nhau. Mình dọn bớt các thẻ rỗng mà Initializr thêm vào, còn lại là:

pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.1.2</version>
    <relativePath/>
  </parent>

  <groupId>vn.moc</groupId>
  <artifactId>order-api</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <name>order-api</name>

  <properties>
    <java.version>25</java.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-webmvc</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-webmvc-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

Hai dependency đều là "starter", một gói thư viện đặt sẵn cho một mục đích. spring-boot-starter-webmvc kéo theo mọi thứ cần để viết API web (Spring MVC, máy chủ Tomcat nhúng, thư viện JSON). Mình gặp tên này khi tạo project với 4.1.2; nếu bạn từng thấy spring-boot-starter-web trong tài liệu cũ thì đó là tên ở các bản trước. Dòng spring-boot-maven-plugin là thứ giúp đóng gói code cùng mọi thư viện vào một file jar tự chạy được, và là lời giải cho chuyện java -jar báo thiếu manifest ở bài Maven.

Class chứa main do Initializr sinh sẵn chỉ có vài dòng:

OrderApiApplication.java
package vn.moc.orderapi;

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

@SpringBootApplication
public class OrderApiApplication {

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

}

Chú thích @SpringBootApplication đánh dấu class này là điểm bắt đầu của ứng dụng Spring, và SpringApplication.run khởi động Spring. Hai thứ này làm hai việc mà bài sau sẽ mổ xẻ. Bây giờ bạn chỉ cần biết một việc: Spring bắt đầu tìm các thành phần của bạn từ package chứa class này, tức vn.moc.orderapi, và đi xuống mọi package con.

Không có Spring thì code nối các đối tượng thế nào?

Trước khi nói Spring giúp gì, mình xem việc đó khó ở đâu. API thực đơn của quán có ba tầng, mỗi tầng làm một việc: tầng controller nhận request web, tầng service chứa logic, tầng repository lấy dữ liệu. Controller cần service, service cần repository. Cách trực tiếp nhất là mỗi lớp tự new thứ nó cần:

Cách trực tiếp (minh họa, không nằm trong repo)
public class MenuService {
    private final MenuRepository repository = new InMemoryMenuRepository();
    // ...
}

public class MenuController {
    private final MenuService service = new MenuService();
    // ...
}

Chạy được, nhưng có hai chỗ hỏng. Chỗ thứ nhất, MenuService dính chặt với InMemoryMenuRepository: mình đã viết kiểu của biến là interface MenuRepository để linh hoạt, nhưng dòng new InMemoryMenuRepository() lại chốt cứng một lớp cụ thể. Ở bài sau, khi thực đơn chuyển sang lưu trong PostgreSQL, bạn phải đi sửa mọi chỗ có new InMemoryMenuRepository(). Chỗ thứ hai, bạn không thể thay kho dữ liệu bằng một cái giả khi muốn thử riêng logic của service, vì lớp tự tạo thứ nó cần từ bên trong.

Hướng giải quyết là đảo ngược trách nhiệm: lớp không tự tạo thứ nó cần, mà nhận từ bên ngoài. Đó là ý tưởng của IoC.

IoC và Dependency Injection là gì, và Spring làm thế nào?

IoC (Inversion of Control, đảo ngược quyền điều khiển) nghĩa là quyền tạo và nối các đối tượng không còn nằm trong code của bạn, mà thuộc về một thành phần khác gọi là IoC container. Trong Spring, container đó là ApplicationContext. Các đối tượng mà container tạo và quản lý gọi là bean. Dependency Injection (DI) là cách container giao hàng: lớp A khai báo nó cần lớp B, container đưa B cho A. Bạn có thể đọc định nghĩa gốc trong phần IoC container của tài liệu Spring.

Spring tạo và nối các bean khi khởi động
  Code của bạn khai báo               ApplicationContext (container) làm
  ---------------------               ---------------------------------
  MenuController cần MenuService  --> 1. thấy các lớp có chú thích @RestController, @Service, @Repository
  MenuService cần MenuRepository  --> 2. tạo InMemoryMenuRepository
  InMemoryMenuRepository          --> 3. tạo MenuService, đưa repository vào constructor
                                      4. tạo MenuController, đưa service vào constructor

Để container biết lớp nào cần quản lý, bạn gắn chú thích lên lớp. @RestController, @Service và @Repository đều là các dạng của @Component ("lớp này là một bean"), khác nhau ở ý nghĩa: controller nhận web, service chứa logic, repository truy cập dữ liệu. Khi khởi động, Spring quét package của class @SpringBootApplication và các package con để tìm những lớp này, nên một lớp nằm ngoài package đó sẽ không được tìm thấy.

Mình viết bốn lớp cho API thực đơn. Lớp đầu tiên là dữ liệu, MenuItem, khai báo bằng record (một cách ngắn gọn để viết lớp chỉ chứa dữ liệu, bài sau về record sẽ nói kỹ). Giá price tính bằng đồng và là số nguyên, như đã thống nhất ở bài kiểu dữ liệu:

MenuItem.java
package vn.moc.orderapi;

public record MenuItem(long id, String name, long price) {
}

Tiếp theo là interface mô tả việc lấy dữ liệu và lớp cài đặt lưu trong bộ nhớ. Mình để dữ liệu năm món của quán ngay trong lớp:

MenuRepository.java
package vn.moc.orderapi;

import java.util.List;
import java.util.Optional;

public interface MenuRepository {
    List<MenuItem> findAll();

    Optional<MenuItem> findById(long id);
}
InMemoryMenuRepository.java
package vn.moc.orderapi;

import java.util.List;
import java.util.Optional;
import org.springframework.stereotype.Repository;

@Repository
public class InMemoryMenuRepository implements MenuRepository {

    private final List<MenuItem> items = List.of(
            new MenuItem(1, "Cà phê sữa", 35000),
            new MenuItem(2, "Bạc xỉu", 39000),
            new MenuItem(3, "Trà đào", 45000),
            new MenuItem(4, "Bánh mì que", 15000),
            new MenuItem(5, "Cà phê đen", 29000));

    @Override
    public List<MenuItem> findAll() {
        return items;
    }

    @Override
    public Optional<MenuItem> findById(long id) {
        return items.stream().filter(item -> item.id() == id).findFirst();
    }
}

Optional<MenuItem> là cách Java nói "có thể có, có thể không": tìm món số 99 thì không có món nào, và Optional rỗng buộc người gọi phải xử lý trường hợp đó thay vì nhận về null. Hai lớp cuối là service và controller, và đây là chỗ DI xuất hiện: cả hai nhận thứ chúng cần qua constructor.

MenuService.java
package vn.moc.orderapi;

import java.util.List;
import java.util.Optional;
import org.springframework.stereotype.Service;

@Service
public class MenuService {

    private final MenuRepository repository;

    public MenuService(MenuRepository repository) {
        this.repository = repository;
    }

    public List<MenuItem> listAll() {
        return repository.findAll();
    }

    public Optional<MenuItem> find(long id) {
        return repository.findById(id);
    }
}
MenuController.java
package vn.moc.orderapi;

import java.util.List;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class MenuController {

    private final MenuService service;

    public MenuController(MenuService service) {
        this.service = service;
    }

    @GetMapping("/menu")
    public List<MenuItem> list() {
        return service.listAll();
    }

    @GetMapping("/menu/{id}")
    public ResponseEntity<MenuItem> get(@PathVariable long id) {
        return service.find(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }
}

Chú thích @GetMapping("/menu") nói rằng method list xử lý request GET /menu; Spring sẽ tự đổi danh sách trả về thành JSON. {id} trong đường dẫn là biến, và @PathVariable đưa nó vào tham số id. Cả hai constructor đều không có chú thích nào, vì khi một lớp chỉ có một constructor, Spring tự dùng nó. Nhìn lại: không dòng new nào nối các lớp với nhau. MenuService chỉ biết nó nhận một MenuRepository, còn InMemoryMenuRepository là cái nào thì do container chọn.

Mình build rồi chạy. Mình dùng cổng 18080 (--server.port=18080) để khỏi trùng với chương trình khác trên máy; nếu bạn chạy bình thường, cổng mặc định là 8080 và bạn đổi URL cho khớp.

Chạy (trong thư mục order-api)
mvn package
java -Dstdout.encoding=UTF-8 -jar target/order-api-0.0.1-SNAPSHOT.jar --server.port=18080

Lệnh đầu build và chạy luôn bài kiểm tra mà Initializr tạo sẵn (một test chỉ kiểm tra ứng dụng khởi động được). Lệnh thứ hai chạy file jar tự đóng gói. Nếu thành công bạn thấy các dòng log, trong đó đáng chú ý là hai dòng:

Kết quả (hai dòng log chính)
 :: Spring Boot ::                (v4.1.2)
... Tomcat started on port 18080 (http) with context path '/'
... Started OrderApiApplication in 1.217 seconds (process running for 1.54)

Phiên bản trong banner khớp 4.1.2, và Tomcat started cho biết một máy chủ web đã chạy sẵn dù bạn chưa viết dòng cấu hình nào. Điều đó nằm ở bài sau. Để tận mắt xem Spring giữ những bean nào, mình thêm một lớp nhỏ InDanhSachBean in ra danh sách khi khởi động xong (chỉ để học, không phải thứ bạn cần trong dự án thật):

InDanhSachBean.java
package vn.moc.orderapi;

import java.util.Arrays;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;

@Component
public class InDanhSachBean implements ApplicationRunner {

    private final ApplicationContext context;

    public InDanhSachBean(ApplicationContext context) {
        this.context = context;
    }

    @Override
    public void run(ApplicationArguments args) {
        System.out.println("=== Bean của vn.moc mà Spring đang giữ ===");
        Arrays.stream(context.getBeanDefinitionNames())
                .filter(name -> context.getType(name) != null
                        && context.getType(name).getName().startsWith("vn.moc"))
                .sorted()
                .forEach(name -> System.out.println(name + " -> " + context.getType(name).getSimpleName()));
    }
}
Kết quả khi khởi động
=== Bean của vn.moc mà Spring đang giữ ===
inDanhSachBean -> InDanhSachBean
inMemoryMenuRepository -> InMemoryMenuRepository
menuController -> MenuController
menuService -> MenuService
orderApiApplication -> OrderApiApplication

Mỗi lớp mình gắn chú thích đều là một bean, tên bean mặc định là tên lớp viết thường chữ đầu. Cả InDanhSachBean cũng là bean, và nó xin container cung cấp chính ApplicationContext, một ví dụ nữa của DI. Giờ gọi API bằng curl:

Chạy
curl http://localhost:18080/menu
curl http://localhost:18080/menu/3
curl -i http://localhost:18080/menu/99
Kết quả
[{"id":1,"name":"Cà phê sữa","price":35000},{"id":2,"name":"Bạc xỉu","price":39000},{"id":3,"name":"Trà đào","price":45000},{"id":4,"name":"Bánh mì que","price":15000},{"id":5,"name":"Cà phê đen","price":29000}]
{"id":3,"name":"Trà đào","price":45000}
HTTP/1.1 404 
Content-Length: 0

Lệnh thứ nhất trả cả năm món dạng JSON. Lệnh thứ hai trả món số 3. Lệnh thứ ba, món số 99, trả 404 vì Optional rỗng đi vào nhánh notFound. Dữ liệu đúng với năm món của quán mà bài SQL đã dùng, và price là số nguyên đúng như quy ước tiền đồng.

Vì sao nên truyền qua constructor?

Spring cho phép đưa thứ cần thiết vào bằng nhiều cách, và cách bạn hay thấy trong code cũ là gắn @Autowired lên trường (field) của lớp. Mình nghiêng hẳn về constructor, và tài liệu Spring cũng khuyến nghị cách này, với hai lý do: nó giúp bạn viết thành phần dạng bất biến (khai báo final) và bảo đảm thứ cần thiết không bao giờ là null, và đối tượng luôn ở trạng thái đã khởi tạo đầy đủ khi tới tay người gọi.

Lý do thứ ba mình thấy hữu ích nhất khi làm việc thật: lớp dùng constructor vẫn tạo được mà không cần Spring. Mình viết một chương trình main thường, tự new và tự nối, rồi đưa vào một kho dữ liệu giả:

thuchanh/KhongDungSpring.java
package vn.moc.orderapi.thuchanh;

import java.util.List;
import java.util.Optional;
import vn.moc.orderapi.InMemoryMenuRepository;
import vn.moc.orderapi.MenuItem;
import vn.moc.orderapi.MenuRepository;
import vn.moc.orderapi.MenuService;

public class KhongDungSpring {

    public static void main(String[] args) {
        MenuService thatService = new MenuService(new InMemoryMenuRepository());
        System.out.println("Kho thật   : " + thatService.listAll().size() + " món");

        MenuRepository khoGia = new MenuRepository() {
            public List<MenuItem> findAll() {
                return List.of(new MenuItem(99, "Món thử", 1000));
            }

            public Optional<MenuItem> findById(long id) {
                return Optional.empty();
            }
        };
        MenuService serviceGia = new MenuService(khoGia);
        System.out.println("Kho giả    : " + serviceGia.listAll());
    }
}
Chạy (sau mvn package)
java -Dstdout.encoding=UTF-8 -cp target/classes vn.moc.orderapi.thuchanh.KhongDungSpring
Kết quả
Kho thật   : 5 món
Kho giả    : [MenuItem[id=99, name=Món thử, price=1000]]

Cùng một MenuService, lần đầu nhận kho thật cho năm món, lần sau nhận kho giả cho một món thử. Đây là cách các bài sau viết test cho logic mà không cần database thật. Nếu bạn dùng @Autowired trên trường private, bạn không có constructor để làm việc này, và phải dựa vào Spring hoặc dùng kỹ thuật "chọc" vào trường riêng tư, rắc rối hơn nhiều.

Spring báo lỗi khi khởi động thì làm sao?

Vì Spring nối các bean lúc khởi động, thiếu hay thừa một mối nối là ứng dụng không lên được, và điều này tốt vì lỗi lộ ra ngay thay vì lúc có request. Hai lỗi người mới hay gặp nhất đều có thể tạo lại trong một phút.

Lỗi thứ nhất: quên chú thích. Mình xóa dòng @Service khỏi MenuService rồi build và chạy lại:

Kết quả khi thiếu @Service
APPLICATION FAILED TO START
***************************
Description:
Parameter 0 of constructor in vn.moc.orderapi.MenuController required a bean of type 'vn.moc.orderapi.MenuService' that could not be found.
Action:
Consider defining a bean of type 'vn.moc.orderapi.MenuService' in your configuration.

Thông báo chỉ đúng nơi: MenuController cần một MenuService, nhưng container không có, vì MenuService không còn là bean. Lỗi thường là quên chú thích, hoặc đặt lớp ngoài package mà Spring quét.

Lỗi thứ hai: có hai bean cùng loại. Mình thêm một lớp FileMenuRepository cũng cài đặt MenuRepository và gắn @Repository:

Kết quả khi có hai MenuRepository
APPLICATION FAILED TO START
***************************
Description:
Parameter 0 of constructor in vn.moc.orderapi.MenuService required a single bean, but 2 were found:
	- fileMenuRepository: defined in URL [...]
	- inMemoryMenuRepository: defined in URL [...]
Action:
Consider marking one of the beans as @Primary, updating the consumer to accept multiple beans, or using @Qualifier to identify the bean that should be consumed

Giờ MenuService xin một MenuRepository, mà có hai ứng viên, nên Spring không dám đoán. Dòng Action gợi ý cách sửa: đánh dấu một bean là @Primary (ưu tiên khi có nhiều lựa chọn), hoặc dùng @Qualifier("tênBean") ở chỗ nhận để chỉ đích danh. Mình tách riêng hai lỗi này vì thông báo của Spring khá rõ, và việc của bạn chỉ là đọc phần Description và Action thay vì cuộn qua dãy stack trace dài.

Hỏi phỏng vấn thế nào?

Câu hỏi hay gặp ở mọi buổi phỏng vấn Spring: "IoC là gì, Dependency Injection khác IoC thế nào, bạn thích kiểu injection nào?". Câu trả lời mạch lạc: IoC là nguyên tắc (container nắm quyền tạo và nối), DI là cách thực hiện nó (đưa thứ cần thiết vào từ ngoài), và bạn nghiêng về constructor injection vì bất biến, không null và dễ test. Nếu nhắc được thêm một lỗi như NoUniqueBeanDefinitionException và cách xử lý, bạn cho người phỏng vấn thấy bạn đã làm thật. Bạn có thể xem câu hỏi này ở mục phỏng vấn.

Bước tiếp theo là gì?

Bạn đã có order-api chạy được, với ba tầng nối nhau bằng DI. Nhưng có một điều mình để lơ lửng ở trên: mình chỉ thêm một dependency, và một máy chủ Tomcat tự chạy trên cổng 18080, JSON tự được dựng, mà bạn chưa cấu hình gì. Ai đã làm những việc đó, bằng cách nào, và khi cần đổi cổng hay đổi cấu hình thì làm ở đâu? Câu trả lời là cơ chế auto-configuration cùng file application của Spring Boot, và nó là nội dung bài kế tiếp trong series Học Spring Boot: xây API đặt hàng từ con số 0.

Nhận bài tiếp theo qua email.

Một email mỗi tuần, chỉ khi có điều đáng đọc. Không spam.