Tất Tần Tật Về Spring Annotations: Khái Niệm, Lý Do và Cách Sử Dụng

Bạn thêm @Transactional vào một method, transaction vẫn không mở. Bạn thêm @Async, lời gọi vẫn chạy trên thread hiện tại. Nguyên nhân thường giống nhau: annotation chỉ là metadata, và metadata chỉ có tác dụng khi có hạ tầng đọc nó — lời gọi nội bộ trong cùng bean thì không đi qua hạ tầng đó.

Bài này sắp xếp annotation Spring theo vai trò thay vì theo bảng chữ cái, chỉ ra thành phần nào đọc từng nhóm, và dừng ở những lỗi cấu hình gặp hàng ngày. Code dùng Spring Boot 4.1.2, Framework 7.0.10, Java 25 LTS.

Cập nhật 2026

  • Không còn javax.*. Framework 7 bỏ hỗ trợ javax.annotation và javax.inject; dùng jakarta.annotation cho @PostConstruct, @PreDestroy, @Resource và jakarta.inject cho @Inject, @Named. Code copy từ blog cũ sẽ không compile.
  • Auto-configuration viết bằng @AutoConfiguration. Boot 4 vẫn gate bằng @ConditionalOnClass và @ConditionalOnMissingBean; class auto-config phải nằm trong file AutoConfiguration.imports, không phải spring.factories.
  • @MockBean đã bị xóa khỏi Boot 4. Thay bằng @MockitoBean; @SpyBean thay bằng @MockitoSpyBean.
  • Nullness là chuyện khác. Framework 7 chuyển sang JSpecify; @Nullable của org.jspecify.annotations dành cho công cụ phân tích tĩnh, không phải annotation để container đọc lúc runtime.

Cơ chế: annotation không tự làm gì

@Service không tạo bean. @Transactional không mở transaction. @GetMapping không đăng ký route. Mỗi annotation chỉ là một mẩu metadata gắn vào class, method, field hoặc parameter; hành vi đến từ thành phần hạ tầng đọc metadata đó ở một thời điểm cụ thể. Có bốn thời điểm đáng nhớ.

  • Lúc quét và refresh context. ClassPathScanningCandidateComponentProvider đọc stereotype để tạo bean definition; ConfigurationClassPostProcessor đọc @Configuration, @Bean, @Import, @ComponentScan; RequestMappingHandlerMapping đọc @RequestMapping để dựng mapping registry.
  • Lúc tạo bean. Các BeanPostProcessor xử lý phần còn lại: AutowiredAnnotationBeanPostProcessor cho @Autowired và @Value, ConfigurationPropertiesBindingPostProcessor cho @ConfigurationProperties, proxy creator cho @Transactional, @Async và method security.
  • Lúc request. HandlerMethodArgumentResolver đọc @PathVariable, @RequestParam, @RequestBody; HandlerMethodReturnValueHandler xử lý @ResponseBody; ExceptionHandlerExceptionResolver đọc @ExceptionHandler.
  • Ngoài Spring. @Entity, @Id do Hibernate/JPA đọc; @NotNull do Hibernate Validator đọc; annotation nullness do compiler hoặc IDE đọc. Không có hạ tầng Spring nào can thiệp vào nhóm này.

Hệ quả quan trọng nhất nằm ở proxy. Khi bean có @Transactional hoặc @Async, Spring bọc nó trong một proxy; lời gọi từ bean khác đi vào proxy, interceptor chạy, rồi mới đến method thật. Lời gọi bên trong chính bean đó thì không.

// File: src/main/java/com/example/catalog/orders/OrderService.java
package com.example.catalog.orders;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class OrderService {

    private final OrderRepository repository;

    public OrderService(OrderRepository repository) {
        this.repository = repository;
    }

    public void place(Order order) {
        validate(order);
        persist(order);          // gọi trên this, không qua proxy
    }

    @Transactional
    public void persist(Order order) {
        repository.save(order);
    }
}

Đoạn code trên chạy không lỗi, nhưng persist không có transaction riêng vì place gọi nó trên this — TransactionInterceptor không thấy lời gọi. @Async và @PreAuthorize hỏng theo đúng cơ chế này.

Cách sửa: tách method ghi sang bean khác, hoặc dùng TransactionTemplate khi cần ranh giới tường minh. Self-inject qua ObjectProvider chạy được nhưng thường là dấu hiệu class gánh quá nhiều việc.

Stereotype: bốn mức đánh dấu vai trò

Bốn nhóm này cùng đăng ký bean; khác nhau ở tầng và hạ tầng đi kèm.

  • @Component — mặc định chung cho class không thuộc tầng rõ ràng: mapper, publisher, scheduler.
  • @Service — tầng nghiệp vụ. Không thêm hành vi so với @Component, nhưng đúng vai trò và dễ đọc hơn khi review.
  • @Repository — tầng truy cập dữ liệu; PersistenceExceptionTranslationPostProcessor chỉ dịch exception có ý nghĩa với lỗi từ JDBC/JPA. Gắn nó lên class không chạm database chỉ tạo nhãn sai.
  • @Controller / @RestController — tầng web. RequestMappingHandlerMapping chỉ nhận handler có @Controller hoặc @RequestMapping ở cấp type, nên một class chỉ có @Component cùng vài method @GetMapping sẽ không được map.

Meta-annotation và annotation tự viết

@Service được khai báo với @Component bên trong; @Repository và @Controller cũng vậy. @RestController là @Controller cộng @ResponseBody. @GetMapping là @RequestMapping với method = GET. Spring tìm stereotype bằng cách duyệt meta-annotation, nên bạn tự tạo composed annotation được:

// File: src/main/java/com/example/catalog/shared/UseCase.java
package com.example.catalog.shared;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.springframework.stereotype.Service;

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Service
public @interface UseCase {
}

@UseCase là stereotype hợp lệ: class được đánh dấu sẽ được scan như @Service, còn tên annotation nói rõ vai trò trong kiến trúc. Khi composed annotation cần mang thuộc tính, @AliasFor ánh xạ thuộc tính của bạn sang thuộc tính của annotation gốc — ví dụ value của bạn thành path của @GetMapping. Cơ chế này do AnnotatedElementUtils xử lý; chỉ cần nhớ nó tồn tại khi viết annotation dùng lại, không cần thuộc API chi tiết.

Configuration: định nghĩa bean bằng Java

@Configuration là nguồn bean; @Bean trên method biến giá trị trả về thành bean, tham số method là dependency. Dùng @Configuration(proxyBeanMethods = false) cho class cấu hình mới: không cần CGLIB chặn lời gọi giữa các @Bean, startup nhẹ hơn, miễn là bạn không gọi chéo method. @Import kéo config của module khác hoặc config riêng cho test vào context hiện tại, kể cả ImportSelector và ImportBeanDefinitionRegistrar.

@ConfigurationProperties bind một nhóm property theo prefix, có relaxed binding và hỗ trợ record. Nó chỉ hoạt động khi class được đăng ký — bằng @ConfigurationPropertiesScan, @EnableConfigurationProperties, hoặc đặt @Component lên class. Quên bước này là lỗi phổ biến: annotation có mặt nhưng không có bean nào được bind.

// File: src/main/java/com/example/catalog/mail/MailProperties.java
package com.example.catalog.mail;

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

@ConfigurationProperties(prefix = "app.mail")
public record MailProperties(String host, int port) {
}

@EnableAutoConfiguration là annotation được gộp vào @SpringBootApplication, cùng với @SpringBootConfiguration và @ComponentScan. Nó nạp danh sách auto-configuration và để @ConditionalOnClass, @ConditionalOnMissingBean quyết định cái nào chạy. Khi viết module riêng, dùng @AutoConfiguration thay @Configuration và đăng ký trong file imports.

Dependency Injection: năm annotation đi cùng nhau

@Autowired đánh dấu điểm inject. Với class chỉ có một constructor, Spring tự dùng constructor đó nên @Autowired không cần thiết; viết constructor injection trơn là style mặc định hiện nay. Field injection vẫn chạy nhưng che dependency và làm test khó hơn, vì bạn phải dựng cả context hoặc dùng reflection.

Khi có nhiều candidate cùng kiểu, @Primary chọn mặc định ở cấp bean, còn @Qualifier chọn ở điểm inject và thắng @Primary. Đừng trộn hai cơ chế trong cùng một nhóm bean mà không có lý do. @Value phù hợp với một scalar như ${app.timeout}; với nhóm cấu hình, @ConfigurationProperties cho type-safety và validation tốt hơn.

@Lazy hoãn khởi tạo bean hoặc tạo proxy ở điểm inject, hữu ích khi phá vòng phụ thuộc tạm thời. ObjectProvider<T> xử lý trường hợp không có bean, có nhiều bean, hoặc bean chỉ nên tạo khi thật sự dùng — tốt hơn @Autowired(required = false).

Web: annotation được đọc lúc startup và lúc request

@RequestMapping ở cấp class đặt prefix, ở cấp method đặt phần còn lại; hai phần được nối, không thay thế nhau. Vì vậy class map /api/users và method map /api/users/{id} cho ra /api/users/api/users/{id}. Lỗi này xuất hiện khi copy method từ controller khác. Các shortcut @GetMapping, @PostMapping, @PutMapping, @DeleteMapping, @PatchMapping chỉ là @RequestMapping đã gắn method HTTP.

@RestController = @Controller + @ResponseBody: mọi method trả về body thay vì view name, nên đừng thêm @ResponseBody lần nữa. @PathVariable lấy biến trong path, @RequestParam lấy query parameter, @RequestBody đọc body qua message converter. Ba annotation này do argument resolver đọc theo từng request, không phải lúc startup.

@ControllerAdvice gom @ExceptionHandler dùng chung cho nhiều controller; handler trong chính controller vẫn được ưu tiên. Nếu advice không được áp dụng, kiểm tra package của nó có nằm trong vùng scan — advice đặt trong thư viện ngoài package gốc thường bị bỏ sót.

Data: ba annotation của JPA, hai của Spring

@Entity, @Id, @GeneratedValue thuộc jakarta.persistence và do Hibernate đọc, không phải Spring. @Transactional và @Query mới là của Spring: @Query được Spring Data JPA đọc lúc bootstrap repository và validate câu JPQL; @Transactional do proxy đọc như phần trên.

// File: src/main/java/com/example/catalog/orders/OrderRepository.java
package com.example.catalog.orders;

import java.util.List;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

public interface OrderRepository extends JpaRepository<Order, Long> {

    @Query("select o from Order o where o.status = :status")
    List<Order> findByStatus(@Param("status") Status status);
}

Mặc định rollback chỉ xảy ra với RuntimeException và Error; checked exception không rollback trừ khi bạn khai báo rollbackFor. Với method chỉ đọc, @Transactional(readOnly = true) là hint hữu ích cho Hibernate và cho người đọc code, không phải khóa bảo vệ dữ liệu.

Security: bật hạ tầng trước, annotation sau

@EnableWebSecurity bật hạ tầng filter chain; bạn vẫn khai báo SecurityFilterChain bằng bean, không quay lại WebSecurityConfigurerAdapter đã bị xóa từ Security 6. Với kiểm tra ở tầng method, cần @EnableMethodSecurity; annotation này bật @PreAuthorize, @PostAuthorize, @PreFilter, @PostFilter theo mặc định.

@Secured là lựa chọn cũ và không bật mặc định: cần @EnableMethodSecurity(securedEnabled = true). @PreAuthorize diễn đạt được nhiều điều kiện hơn và là chuẩn hiện tại, nên đừng trộn hai kiểu trong cùng dự án.

Testing: slice nào đọc annotation nào

@SpringBootTest dựng gần đủ context; từ Boot 4 nó không còn tự cấp MockMvc, nên test controller cần thêm @AutoConfigureMockMvc. @WebMvcTest chỉ nạp tầng web — controller, advice, converter, filter — và không tạo @Service hay @Repository. @DataJpaTest chỉ nạp JPA, mặc định thay datasource bằng database nhúng và rollback sau mỗi test.

// File: src/test/java/com/example/catalog/orders/OrderControllerTest.java
@WebMvcTest(OrderController.class)
class OrderControllerTest {

    @Autowired
    MockMvc mvc;

    @MockitoBean
    OrderService orderService;
}

@MockitoBean thay bean thật trong context test bằng mock; nó thay @MockBean đã bị xóa ở Boot 4. Với test cần database thật, @Testcontainers trên class cùng @Container trên field khởi động container; @ServiceConnection để Boot tự nối datasource, không cần viết @DynamicPropertySource thủ công.

Annotation nào của ai

Phân biệt ba nhóm. Nhóm Spring (@Component, @Autowired, @Transactional, @RequestMapping) được container đọc lúc runtime. Nhóm Jakarta (jakarta.persistence, jakarta.validation, jakarta.annotation) do JPA provider, Hibernate Validator hoặc hạ tầng annotation của Spring đọc; các API này không còn bản javax. Nhóm nullness (org.jspecify.annotations.Nullable, @NonNull) chỉ cho compiler và IDE, không tạo bean và không đổi hành vi runtime.

Lỗi thường gặp

  • @Autowired trên field static. Spring bỏ qua field static, log cảnh báo và không inject. Chuyển dependency thành tham số constructor, hoặc gán trong @PostConstruct nếu thật sự cần static.
  • @Transactional trên method private, final hoặc static. Proxy không override được, nên interceptor không chạy. Method phải public và được gọi từ ngoài bean.
  • @Async gọi nội bộ. Cùng lý do proxy; tách sang bean khác thay vì self-inject chỉ để chạy async.
  • @Value trên field static. Giá trị luôn null hoặc giá trị mặc định. Dùng constructor injection cho scalar, @ConfigurationProperties cho nhóm cấu hình.
  • @RequestMapping cấp class trùng path với method. Path bị nối, URL thành /api/users/api/users/{id}. Giữ prefix ở class và phần thay đổi ở method.
  • @Repository trên class không chạm database. Không có exception dịch nào để dịch; dùng @Component hoặc @Service đúng vai trò.
  • @Component cho mọi thứ. Controller mất mapping, advice không được nhận, và người đọc mất tín hiệu về tầng. Chọn stereotype theo vai trò, không theo thói quen.

Bảng tra nhanh

Annotation Ai đọc Hiệu ứng
@Component, @Service, @Repository Component scan Tạo bean definition; @Repository thêm dịch exception DB
@Configuration, @Bean ConfigurationClassPostProcessor Đăng ký bean từ factory method
@ConfigurationProperties Binding post-processor Bind property vào object; cần được đăng ký trước
@Autowired, @Value AutowiredAnnotationBeanPostProcessor Inject dependency hoặc giá trị
@RequestMapping, @GetMapping RequestMappingHandlerMapping Dựng mapping lúc startup; resolver đọc tham số lúc request
@RequestBody, @ResponseBody Argument/return value handler Đọc hoặc ghi body qua message converter
@Transactional AOP proxy + TransactionInterceptor Mở, commit, rollback quanh lời gọi qua proxy
@Entity, @Id, @GeneratedValue Hibernate/JPA, không phải Spring Map class sang bảng và sinh khóa
@PreAuthorize Method-security interceptor Kiểm tra quyền trước khi gọi method
@MockitoBean Mockito post-processor trong test context Thay bean thật bằng mock

Nhìn về 2027

Boot 4.2 và Framework 7.1 đ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 theo nhịp hai năm, dự kiến 2027. Bộ annotation cốt lõi nhiều khả năng giữ nguyên; thay đổi đáng theo dõi nằm ở đóng gói auto-configuration và công cụ nullness, không ở tên annotation.

Checklist

  • Kiểm tra mọi method @Transactional/@Async có được gọi từ ngoài bean không.
  • Giữ constructor injection; bỏ @Autowired khi class chỉ có một constructor.
  • Đặt prefix ở cấp class, phần thay đổi ở method; không lặp path.
  • Đăng ký @ConfigurationProperties bằng scan hoặc @EnableConfigurationProperties.
  • Dùng @WebMvcTest/@DataJpaTest cho test hẹp; chỉ @SpringBootTest khi cần cả context.
  • Với Boot 4, thay @MockBean bằng @MockitoBean và thêm @AutoConfigureMockMvc khi cần MockMvc.

Hiểu cơ chế đọc annotation giúp debug nhanh hơn nhớ danh sách. Proxy — nơi @Transactional và @Async thực sự sống — được giải thích trong bài Aspect-Oriented Programming với Spring AOP. Nền tảng đăng ký bean nằm ở Spring IoC trong thực tế, cách chọn dependency ở Hiểu về Dependency Injection; bước tiếp theo là Spring MVC Giải Mã.