Bước Tiếp Theo Trên Hành Trình Java Spring Roadmap: Làm Chủ Cấu Hình Với XML và Annotations

Niềm tin phổ biến là cấu hình Spring có hai lựa chọn ngang hàng: XML hoặc annotation. Năm 2026 điều đó không còn đúng: dự án mới viết bằng Java config và auto-configuration của Boot 4.1.2, còn XML chỉ là định dạng bạn phải đọc, sửa và migrate trong code cũ. Bài này đặt XML vào đúng vai trò đó: hiểu để bảo trì hệ thống legacy, không phải để chọn cho module tiếp theo.

Bạn sẽ thấy ba kiểu cấu hình và thời kỳ của chúng, một context XML nhỏ cùng bản tương đương bằng Java, playbook migration từng bean, và những lỗi làm startup fail khi hai thế giới gặp nhau. Code dùng Boot 4.1.2, Framework 7.0.10, Java 25 LTS.

Cập nhật 2026

  • Namespace XML của MVC đã deprecated, không phải bị xóa. Từ Framework 7.0, các thẻ <mvc:*> vẫn chạy nhưng không còn được cập nhật theo Java config; bean XML (<bean>, <context:component-scan>) vẫn được hỗ trợ.
  • Jakarta EE 11 làm XML cũ mất hiệu lực. File XML trỏ tới javax.persistence, javax.annotation hay javax.inject sẽ fail: Framework 7 bỏ hỗ trợ javax và class đã chuyển sang jakarta.*. Ngược lại, javax.sql.DataSource vẫn hợp lệ vì thuộc Java SE.
  • Boot 4 chia jar theo công nghệ nhưng không đổi cách cấu hình. Bạn vẫn dùng @Configuration, @Bean, @ComponentScan; thứ thay đổi là vị trí artifact và auto-configuration đi kèm.
  • Auto-configuration luôn ở lite mode. @AutoConfiguration được meta-annotate bằng @Configuration(proxyBeanMethods = false). @Configuration bạn tự viết mặc định vẫn full mode, nên chi phí CGLIB chỉ xuất hiện khi bạn không chọn false.

Ba kiểu cấu hình và thời kỳ của chúng

XML. Spring 1.x quản lý mọi thứ qua một hoặc vài file applicationContext.xml. Mỗi bean là một thẻ <bean> với id và class; dependency nối bằng <constructor-arg ref="..."> hoặc <property ref="...">, và mọi liên kết đều là chuỗi.

Annotation scanning. Từ Spring 2.5 (2007), @Component, @Service, @Repository đánh dấu class là bean, @Autowired chỉ định điểm tiêm. Scan phải được bật: ban đầu bằng <context:component-scan base-package="com.example"/>, sau này bằng @ComponentScan.

Java config. Từ Spring 3.0 (2009), @Configuration và @Bean biến cấu hình thành code Java có kiểu, khởi tạo bằng AnnotationConfigApplicationContext. Không còn tên class dưới dạng chuỗi, IDE rename được, compiler bắt lỗi sớm.

Boot. Từ Boot 1.0, @SpringBootApplication đóng gói cả ba: @SpringBootConfiguration cộng @EnableAutoConfiguration cộng @ComponentScan. Auto-configuration đóng góp thêm bean definition có điều kiện, và đó là lý do một app Boot chỉ cần vài chục dòng config thay vì vài trăm dòng XML.

Ba kiểu không loại trừ nhau: app Boot 4.1 vẫn nạp được XML qua @ImportResource, và việc đó không biến nó thành app XML. Câu hỏi đúng là bean này thuộc nguồn nào và ai sở hữu nó, không phải chọn kiểu nào. Bài Spring IoC trong thực tế đi sâu vào bốn đường đăng ký bean definition.

Một context XML nhỏ, đủ để đọc code cũ

File dưới đây là dạng bạn sẽ gặp trong các dự án 10–15 năm tuổi: một DataSource, một repository, một service, dependency nối bằng ref, property nạp từ file .properties.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:context="http://www.springframework.org/schema/context"
       xsi:schemaLocation="
           http://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans.xsd
           http://www.springframework.org/schema/context https://www.springframework.org/schema/context/spring-context.xsd">

    <context:property-placeholder location="classpath:legacy.properties"/>

    <bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
        <property name="driverClassName" value="org.postgresql.Driver"/>
        <property name="url" value="${db.url}"/>
        <property name="username" value="${db.username}"/>
        <property name="password" value="${db.password}"/>
    </bean>

    <bean id="priceRepository" class="com.example.legacy.JdbcPriceRepository">
        <constructor-arg ref="dataSource"/>
    </bean>

    <bean id="pricingService" class="com.example.legacy.PricingService">
        <constructor-arg ref="priceRepository"/>
    </bean>
</beans>

Khởi tạo container từ file này trông như sau. Đoạn main chỉ để hiểu cơ chế; trong Boot bạn không viết nó, vì SpringApplication.run đã dựng context cho bạn.

// File: src/main/java/com/example/legacy/LegacyMain.java
package com.example.legacy;

import org.springframework.context.support.ClassPathXmlApplicationContext;

public class LegacyMain {

    public static void main(String[] args) {
        try (ClassPathXmlApplicationContext context =
                 new ClassPathXmlApplicationContext("legacy/beans.xml")) {
            PricingService service = context.getBean("pricingService", PricingService.class);
            service.quote("SKU-1", 3);
        }
    }
}

Điểm cần nhận ra: không có gì kiểm tra kiểu trong file XML. Tên class, ref và ${db.url} đều là chuỗi cho tới khi container resolve. Gõ sai một ký tự trong tên class, bạn nhận CannotLoadBeanClassException lúc refresh(); sai một ref, bạn nhận NoSuchBeanDefinitionException cùng lúc. Cả hai đều không thể phát hiện lúc compile.

Bản tương đương bằng Java config

Cùng ba bean đó, viết theo kiểu bạn dùng trong Boot 4.1. DataSource không cần khai báo vì spring-boot-starter-jdbc đã auto-configure nó từ spring.datasource.*; đây chính là lợi ích lớn nhất của Java config so với XML.

// File: src/main/java/com/example/legacy/PricingConfig.java
package com.example.legacy;

import javax.sql.DataSource;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class PricingConfig {

    @Bean
    JdbcPriceRepository priceRepository(DataSource dataSource) {
        return new JdbcPriceRepository(dataSource);
    }

    @Bean
    PricingService pricingService(JdbcPriceRepository priceRepository) {
        return new PricingService(priceRepository);
    }
}

Hai @Bean method nhận dependency qua tham số, nên không cần ref, không cần gọi chéo method, không cần @Autowired. Tên bean mặc định là tên method: priceRepository và pricingService. Nếu class có @Repository thì scan tạo bean cùng tên — chi tiết quan trọng khi migrate, sẽ nói ở phần sau.

Đừng bắt đầu dự án mới bằng XML

Nói thẳng: không có lý do kỹ thuật nào để viết applicationContext.xml cho module mới trong 2026. Bạn mất type safety, mất refactor, mất IDE completion, và phải duy trì một định dạng không được cập nhật theo Java config.

XML còn chỗ trong ba tình huống: đọc một hệ thống cũ, migrate nó, hoặc chạy một thư viện chỉ cung cấp mẫu XML và chưa có auto-configuration. Cả ba là bài toán tương thích, không phải thiết kế.

Playbook migration: từ XML sang Java config

Migration đúng là thay từng bean, không phải viết lại toàn bộ. Làm theo thứ tự sau để mỗi bước đều build và test được.

1. Kiểm kê nguồn cấu hình

Tìm mọi file XML còn được nạp và mọi chỗ có @ImportResource. Ghi lại số lượng <bean> trong từng file — con số này là tiến độ migration. Đừng sửa nội dung trước khi biết mình có bao nhiêu thứ phải chuyển.

2. Cho hai thế giới cùng chạy

Đặt @ImportResource trong một class riêng, tên thể hiện rõ đây là cầu tạm. Một file cho một legacy context, đừng gom tất cả vào một chỗ.

// File: src/main/java/com/example/shop/legacy/LegacyImportConfig.java
package com.example.shop.legacy;

import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.ImportResource;

@Configuration(proxyBeanMethods = false)
@ImportResource("classpath:legacy/beans.xml")
public class LegacyImportConfig {
}

@ImportResource đọc file theo Resource pattern, nên classpath: và classpath*: đều dùng được; đường dẫn tính từ src/main/resources. Mỗi <bean> trở thành một bean definition bình thường, không có gì đặc biệt so với bean từ scan.

3. Chuyển từng bean, giữ nguyên tên

Thêm một @Bean method với tên trùng id cũ, rồi xóa thẻ <bean> tương ứng trong cùng một commit. Giữ tên là bắt buộc: các ref còn lại trong XML trỏ theo chuỗi, đổi tên sẽ làm chúng gãy.

Thứ tự hợp lý là đi từ dưới lên theo đồ thị dependency: DataSource, repository, service, controller. Mỗi bước xong, chạy test và khởi động app. Nếu bạn thêm annotation cho một class trong khi XML vẫn khai báo nó, hai nguồn tạo bean cùng tên và startup fail — dấu hiệu bạn làm sai thứ tự, không phải lỗi ngẫu nhiên.

4. Thay ref bằng constructor injection

Khi một class rời XML, sửa constructor của nó nhận dependency trực tiếp thay vì để container tiêm qua setter. Đây là lúc bạn chuyển từ “container nối dây” sang “code tự khai báo phụ thuộc”, đúng nguyên tắc trong bài Hiểu về Dependency Injection. Một constructor, tham số là collaborator, không cần @Autowired.

Với bean không phải class của bạn — DataSource, ObjectMapper, RestClient — bạn không sửa constructor mà thay bằng auto-configuration hoặc một @Bean method. Đó là lý do nhiều file XML biến mất gần như toàn bộ khi chuyển sang Boot: phần lớn bean trong đó là hạ tầng Boot đã tự tạo.

5. Xóa cầu nối khi không còn tham chiếu

Khi file XML không còn <bean> nào, phần còn lại thường chỉ là <context:component-scan> và <context:property-placeholder>. Thay chúng bằng @ComponentScan và @ConfigurationProperties, xóa file XML, xóa LegacyImportConfig trong cùng commit. Đừng để cầu nối “phòng khi cần” — nó sẽ được copy sang module tiếp theo.

@Configuration(proxyBeanMethods = false) nghĩa là gì

@Configuration có hai chế độ. Full mode (mặc định, proxyBeanMethods = true) làm Spring tạo subclass CGLIB, chặn lời gọi giữa các @Bean method và trả về singleton. Lite mode (false) không tạo proxy: lời gọi method là Java thường, mỗi lần gọi tạo instance mới.

Boot dùng lite mode cho toàn bộ auto-configuration vì các class đó không gọi chéo nhau; bỏ CGLIB giúp startup nhanh hơn và tránh giới hạn subclass. Bạn cũng nên dùng lite mode cho config của mình, trừ khi thật sự cần ngược lại.

Lỗi kinh điển của lite mode là gọi một @Bean method từ một @Bean method khác:

// File: src/main/java/com/example/shop/report/ReportConfig.java
package com.example.shop.report;

import java.time.Clock;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration(proxyBeanMethods = false)
public class ReportConfig {

    @Bean
    Clock clock() {
        return Clock.systemUTC();
    }

    @Bean
    ReportService reportService() {
        return new ReportService(clock());   // Java thường: một Clock mới, không phải bean
    }
}

Ở đây clock() tạo thêm một instance, không lấy bean trong container. Trong test bạn thay Clock bằng Clock.fixed sẽ thấy reportService vẫn dùng clock hệ thống. Cách sửa đúng là thêm tham số, để container tiêm:

    @Bean
    ReportService reportService(Clock clock) {
        return new ReportService(clock);
    }

Chỉ bật full mode khi bạn không thể thêm tham số, ví dụ một factory method dựng cả object graph bên trong và cần đúng instance singleton. Lưu ý full mode không dùng được với class final, vì CGLIB cần subclass. Với hầu hết config hiện đại, câu trả lời là false cộng tham số method.

Bốn lỗi làm startup fail khi XML gặp annotation

Trùng bean definition giữa XML và scan

Đây là lỗi số một khi migrate. XML khai báo id="pricingService", class PricingService được scan với @Service → cùng tên pricingService. Trong Boot, spring.main.allow-bean-definition-overriding mặc định là false, nên app fail với BeanDefinitionOverrideException lúc refresh. Ở plain Spring, definition sau lặng lẽ thắng — nguy hiểm hơn vì bạn không biết bean nào đang chạy. Nguyên tắc: một bean chỉ thuộc một nguồn; khi chuyển, xóa bên cũ trong cùng commit.

XML không có type safety và không refactor được

Tên class và ref là chuỗi. IDE rename class Java không sửa XML, compiler không thấy gì, nên lỗi chỉ lộ khi khởi động, đôi khi ở môi trường khác vì file XML được chọn theo profile. Khi đọc code cũ, coi mỗi <bean> là một dòng nợ kỹ thuật; đừng thêm bean mới vào đó chỉ vì “đã có sẵn file”.

Property placeholder, @Value và @ConfigurationProperties

Ba cơ chế này không tương đương. <context:property-placeholder> cộng ${...} trong XML chỉ thay chuỗi, không convert sang Duration, không validate, không metadata cho IDE. @Value("${app.pricing.cache-ttl}") có conversion nhưng vẫn là từng giá trị rời. @ConfigurationProperties bind cả nhóm, hỗ trợ relaxed binding, validation và metadata:

// File: src/main/java/com/example/shop/pricing/PricingProperties.java
package com.example.shop.pricing;

import java.time.Duration;

import org.springframework.boot.context.properties.ConfigurationProperties;

@ConfigurationProperties("app.pricing")
public record PricingProperties(Duration cacheTtl, int maxItems) {
}

Đăng ký bằng @EnableConfigurationProperties(PricingProperties.class) trên một class config, hoặc @ConfigurationPropertiesScan trên main class. Trong Boot bạn cũng không cần <context:property-placeholder>, vì Environment đã đọc application.properties và biến môi trường sẵn.

Profile: <beans profile="dev"> và @Profile

XML lọc bean bằng thuộc tính profile trên thẻ <beans>; annotation dùng @Profile("dev") trên class hoặc method, điều khiển bằng spring.profiles.active. Cả hai vẫn chạy, nhưng đừng trộn trong cùng module: một nửa cấu hình biến mất theo file, nửa kia theo điều kiện. Khi migrate, chuyển profile filter sang @Profile cùng lúc với bean cuối cùng của file.

Khi nào dùng kiểu nào

Kiểu Dùng khi Không dùng khi
XML (<bean>) Hệ thống legacy còn chạy, cần đọc hoặc migrate Module mới, dự án mới
Component scan Class của bạn, phần lớn service/repository/controller Class thư viện, object cần điều kiện
Java config (@Bean) Class bên thứ ba, nhiều biến thể cùng kiểu, logic dựng phức tạp Chỉ để gom code khởi tạo vào một chỗ

Trong một app Boot 4.1 khỏe mạnh, tỉ lệ là scan cho code của bạn, @Bean cho thứ bạn không sở hữu, gần như không có XML. Nếu buộc phải có @ImportResource, đặt nó trong class riêng, tên nói rõ mục đích và có ngày xóa.

Nhìn về 2027

Framework 7.1 và Boot 4.2 đang ở RC, đừng viết tài liệu nội bộ dựa trên chúng. Java 29 là LTS kế tiếp, dự kiến 2027. Với XML, xu hướng rất rõ: namespace MVC đã deprecated và sẽ không được cập nhật; bean XML vẫn được hỗ trợ nhưng không nhận tính năng mới. Đừng chờ XML biến mất — module nào chạm tới thì migrate module đó.

Checklist

  • Không tạo file applicationContext.xml mới; dự án mới dùng @Configuration và @Bean.
  • Đặt @ImportResource trong một class cầu nối riêng, một file cho một context.
  • Giữ nguyên tên bean khi chuyển, xóa <bean> cùng commit với @Bean mới.
  • Thay ref bằng tham số constructor; không dùng setter injection để né circular dependency.
  • Dùng @Configuration(proxyBeanMethods = false) và truyền dependency qua tham số method.
  • Chuyển property sang @ConfigurationProperties, profile sang @Profile, rồi xóa file XML.

Bài về annotations là Tất tần tật về Spring Annotations, nơi bạn gặp lại @Component, @Bean và @Configuration với ví dụ đầy đủ hơn. Sau khi nắm cấu hình, bước tiếp theo là hiểu cách Boot biến cấu hình của bạn thành auto-configuration trong bài Spring Boot Autoconfiguration.