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
@SpringBootApplication
Annotation 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.
@Bean
Khai 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
@Component
Stereotype tổng quát: class được Spring quản lý thành bean và được component scan phát hiện.
@Service
Stereotype 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.
@Repository
Stereotype 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
@RestController
Gộ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 / @PostMapping
Dạ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.
@RequestBody
Bind 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.
@PathVariable
Lấy giá trị từ biến đường dẫn trong URL template, ví dụ /members/{id} thì @PathVariable Long id.
@RequestParam
Lấ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 đá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.
@Version
Bậ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ẽ.
@Transactional
Mở 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.
@Async
Chạ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
@EnableMethodSecurity
Bậ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.
@Validated
Bậ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
@SpringBootTest
Nạ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.