Cheat Sheet — Spring Annotations (Boot 3.3 / Framework 6.1 / Security 6.3)

Tra cứu nhanh các annotation Spring Boot 3.3, Spring Framework 6.1, Spring Data JPA, Spring Security 6.3 và testing — kèm lưu ý constructor injection thay cho field injection.

Module 02

Khởi động & cấu hình ứng dụng

Khởi động & cấu hình ứng dụng
MụcÝ nghĩa & cách dùng
@SpringBootApplicationAnnotation gốc trên class main: gộp @Configuration + @EnableAutoConfiguration + @ComponentScan. Đặt ở package gốc để component scan quét được toàn bộ package con.
@ConfigurationĐánh dấu class chứa định nghĩa bean bằng các method @Bean; mặc định proxyBeanMethods = true để lời gọi @Bean lồng nhau vẫn trả về cùng singleton.
@BeanKhai báo bean do method tạo ra trong class @Configuration — dùng cho thư viện bên thứ ba hoặc khi cần logic khởi tạo tùy biến mà annotation stereotype không làm được.
@ConfigurationProperties(prefix = "app.loyalty")Bind nhóm thuộc tính trong application.yml/properties vào một class (thường là record hoặc class có setter) theo kiểu type-safe; cần @EnableConfigurationProperties hoặc @ConfigurationPropertiesScan để kích hoạt.
@Value("${app.timeout-ms:5000}")Tiêm một giá trị cấu hình đơn lẻ, hỗ trợ giá trị mặc định sau dấu hai chấm. Với nhóm cấu hình có cấu trúc, ưu tiên @ConfigurationProperties thay vì rải @Value khắp nơi.
@Profile("prod")Bean/class chỉ được tạo khi profile tương ứng đang active (ví dụ qua -Dspring.profiles.active=prod); hay dùng để tách cấu hình dev/prod hoặc thay bean thật bằng bean giả trong test.

Stereotype & Dependency Injection

Stereotype & Dependency Injection
MụcÝ nghĩa & cách dùng
@ComponentStereotype tổng quát: class được Spring quản lý thành bean và được component scan phát hiện.
@ServiceStereotype cho tầng nghiệp vụ (service layer). Về kỹ thuật giống @Component, khác ở ý nghĩa ngữ nghĩa; đây là nơi thường đặt @Transactional.
@RepositoryStereotype cho tầng truy cập dữ liệu; ngoài vai trò bean, nó còn bật chuyển đổi exception của persistence thành DataAccessException của Spring.
Constructor injection (khuyến nghị)Tiêm dependency qua constructor (một constructor duy nhất thì không cần @Autowired): dependency là final, dễ test bằng object thật/mock mà không cần Spring, và lỗi vòng lặp dependency lộ ra ngay. Tránh field injection bằng @Autowired trên field vì khó test và che giấu phụ thuộc.

Web MVC — Controller & request mapping

Web MVC — Controller & request mapping
MụcÝ nghĩa & cách dùng
@RestControllerGộp @Controller + @ResponseBody: mọi method trả về dữ liệu (thường serialize JSON) thay vì tên view. Dùng cho REST API.
@RequestMapping("/api/v1/points")Khai báo đường dẫn gốc (và method/media type nếu cần) cho cả controller hoặc cho từng method handler.
@GetMapping / @PostMappingDạng rút gọn của @RequestMapping theo HTTP method: @GetMapping cho truy vấn đọc, @PostMapping cho tạo mới/thao tác. Tương tự còn có @PutMapping, @PatchMapping, @DeleteMapping.
@RequestBodyBind body của request (JSON) vào tham số method; kết hợp @Validated trên tham số để Bean Validation chạy trên DTO đầu vào.
@PathVariableLấy giá trị từ biến đường dẫn trong URL template, ví dụ /members/{id} thì @PathVariable Long id.
@RequestParamLấy tham số query string (?page=0&size=20); hỗ trợ required, defaultValue — hay dùng cho phân trang và bộ lọc.
@RestControllerAdvice + @ExceptionHandler@RestControllerAdvice đánh dấu class xử lý exception tập trung cho toàn bộ controller; mỗi @ExceptionHandler xử lý một loại exception và trả ResponseEntity/ProblemDetail nhất quán thay vì để lỗi thô lọt ra ngoài.

JPA, transaction, cache & tác vụ nền

JPA, transaction, cache & tác vụ nền
MụcÝ nghĩa & cách dùng
@EntityĐánh dấu class là entity JPA được Hibernate 6 ánh xạ tới bảng; entity cần constructor không tham số (có thể protected).
@Id + @GeneratedValue(strategy = GenerationType.IDENTITY)@Id đánh dấu khóa chính; @GeneratedValue nhờ database sinh giá trị (IDENTITY dùng cột auto-increment/identity của DB). Thuộc package jakarta.persistence trong Boot 3.
@ManyToOne(fetch = FetchType.LAZY)Quan hệ nhiều-một với nạp lười (LAZY): dữ liệu phía 'một' chỉ được tải khi thực sự truy cập, tránh N+1 ngầm. Quan hệ @ManyToOne mặc định là EAGER nên phải ghi rõ LAZY.
@VersionBật optimistic locking: Hibernate tự kiểm tra và tăng cột version mỗi lần update; xung đột ghi đồng thời sẽ ném OptimisticLockException thay vì ghi đè lặng lẽ.
@TransactionalMở transaction quanh method/class: commit khi kết thúc bình thường, rollback khi có RuntimeException. Khi ứng dụng có nhiều datasource (multi-datasource không JTA), phải ghi rõ transactionManager, ví dụ @Transactional(transactionManager = "loyaltyTransactionManager"), để dùng đúng EntityManager/transaction của datasource đó.
@Cacheable("memberTier")Cache kết quả method theo key (mặc định là tham số) trong cache manager đã cấu hình (Caffeine/Redis); cần @EnableCaching. Các annotation anh em: @CachePut luôn chạy method rồi cập nhật cache, @CacheEvict xóa mục cache.
@AsyncChạy method trên thread pool riêng thay vì thread gọi; cần @EnableAsync. Lưu ý: tự gọi method @Async trong cùng class (self-invocation) sẽ không qua proxy nên không bất đồng bộ.
@Scheduled(cron = "0 0 2 * * *")Lập lịch chạy method theo fixedRate, fixedDelay hoặc cron; cần @EnableScheduling. Trên cụm nhiều instance, cân nhắc cơ chế khóa (ví dụ ShedLock) để job không chạy trùng.

Security & validation

Security & validation
MụcÝ nghĩa & cách dùng
@EnableMethodSecurityBật bảo mật ở tầng method trong Spring Security 6.3 (annotation duy nhất cho method security ở bản 6.x, thay cho cơ chế global cũ đã bị loại bỏ); đặt trên class cấu hình security.
@PreAuthorize("hasRole('ADMIN')")Kiểm tra quyền bằng SpEL trước khi method chạy; còn có @PostAuthorize kiểm tra sau khi có kết quả. Dùng trên service/controller để chặn truy cập theo role/authority.
@ValidatedBật Bean Validation: đặt trên class để validate tham số method (ví dụ @RequestParam @Positive), hoặc trên tham số @RequestBody trong controller để kích hoạt các annotation ràng buộc như @NotNull, @Size trên DTO.

Testing

Testing
MụcÝ nghĩa & cách dùng
@SpringBootTestNạp toàn bộ ApplicationContext để viết integration test; kết hợp webEnvironment = RANDOM_PORT khi cần gọi HTTP thật qua cổng ngẫu nhiên.
@WebMvcTest(MemberController.class)Slice test chỉ nạp tầng web (controller, filter, MockMvc) cho một controller chỉ định, không nạp service/repository thật — các bean cộng tác được thay bằng @MockBean. Nhanh và tập trung vào mapping/validation/status code.