@ConfigurationProperties vs @Value: Type-Safe Binding

TL;DR: @Value thích hợp để inject giá trị đơn lẻ hoặc tính toán biểu thức SpEL, nhưng thiếu kiểm tra kiểu dữ liệu và không hỗ trợ validation. @ConfigurationProperties gom nhóm cấu hình vào một Java record type-safe, tự động chuyển đổi kiểu, hỗ trợ xác thực qua Jakarta Validation và kích hoạt gợi ý autocomplete trong IDE. Record kết hợp @ConfigurationProperties và @Validated tạo nên chuẩn quản trị cấu hình bất biến, báo lỗi sớm ngay khi ứng dụng khởi động.

Khi nào nên dùng Properties thay vì YAML?

Spring Boot hỗ trợ đọc cấu hình từ cả hai định dạng application.properties và application.yml. Mỗi định dạng phục vụ thế mạnh riêng:

# application.properties: Flat key-value
app.name=OLHub
app.max-orders=500
app.database.url=jdbc:postgresql://localhost/app
app.database.pool-size=30

# application.yml: Hierarchical tree
app:
  name: OLHub
  max-orders: 500
  database:
    url: jdbc:postgresql://localhost/app
    pool-size: 30

Khi dùng YAML, việc lệch khoảng trắng có thể khiến parser gộp nhầm nhánh con vào nhánh cha mà không báo lỗi tường minh. Hãy đảm bảo quy tắc 2 hoặc 4 spaces đồng nhất trong toàn bộ dự án.

Spring Boot ghi đè file cấu hình theo profile như thế nào?

Khi một profile được kích hoạt, Spring Boot nạp file cấu hình cơ sở trước rồi nạp tiếp file riêng của profile để ghi đè các khóa trùng lặp:

# Activate production profile via environment variable
SPRING_PROFILES_ACTIVE=prod java -jar app.jar

# application.yml: Base defaults for development
app:
  name: OLHub
  max-orders: 100
  database:
    url: jdbc:postgresql://localhost/dev

# application-prod.yml: Production overrides
app:
  max-orders: 2000
  database:
    url: jdbc:postgresql://prod-db.internal:5432/app

Khi profile prod chạy, giá trị app.name vẫn được giữ nguyên từ application.yml, trong khi max-orders và database.url nhận giá trị mới từ application-prod.yml.

Điểm mạnh và hạn chế của annotation @Value là gì?

Annotation @Value cho phép gắn trực tiếp một khóa cấu hình vào biến nội bộ của bean:

@Service
public class NotificationService {

    @Value("<code>{'${app.name}'}</code>")
    private String appName;

    @Value("<code>{'${app.max-orders:100}'}</code>")
    private int maxOrders;

    @Value("<code>{'#{systemProperties[\'user.timezone\']}'}</code>")
    private String timezone;
}

Thế mạnh độc nhất của @Value là hỗ trợ SpEL (Spring Expression Language) qua cú pháp #{...} để tính toán giá trị động.

Tuy nhiên, khi số lượng thuộc tính tăng lên, @Value bộc lộ nhiều hạn chế:

• Dễ gõ sai chính tả chuỗi literal mà IDE không thể kiểm tra lúc viết mã.
• Thiếu cơ chế kiểm tra tính hợp lệ của tham số lúc khởi động.
• Không hỗ trợ cấu trúc dữ liệu lồng nhau phức tạp.

Cách bind nhóm thuộc tính type-safe bằng @ConfigurationProperties?

Kết hợp Java record với @ConfigurationProperties tạo ra giải pháp mô hình hóa cấu hình an toàn và gọn gàng:

@ConfigurationProperties(prefix = "app.email")
@Validated
public record EmailProperties(
    @NotBlank String host,
    @Min(1) @Max(65535) int port,
    @NotBlank String username,
    @NotBlank String password,
    boolean tlsEnabled,
    @NotNull Duration timeout
) {
    public EmailProperties {
        if (port == 0) port = 587;
        if (timeout == null) timeout = Duration.ofSeconds(30);
    }
}

File cấu hình YAML tương ứng:

app:
  email:
    host: smtp.internal.org
    port: 587
    username: admin
    password: <code>{'${SMTP_PASS}'}</code>
    tls-enabled: true
    timeout: PT30S

Spring Boot tự động chuyển đổi chuỗi PT30S thành đối tượng Duration chuẩn Java. Đồng thời, cơ chế relax binding tự khớp tls-enabled dạng kebab-case vào biến tlsEnabled dạng camelCase.

Để Spring Boot nhận diện record, bạn khai báo quét cấu hình ở lớp khởi động:

@SpringBootApplication
@ConfigurationPropertiesScan
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Inject record này vào các service thông qua constructor thông thường:

@Service
public class EmailService {
    private final EmailProperties config;

    public EmailService(EmailProperties config) {
        this.config = config;
    }
}

Quá trình binding thuộc tính diễn ra ở tầng thấp như thế nào?

Toàn bộ quá trình binding diễn ra trong giai đoạn tiền khởi tạo của Spring Container:

1. ConfigDataEnvironmentPostProcessor nạp toàn bộ file cấu hình và biến môi trường vào đối tượng Environment.
2. ConfigurationPropertiesBindingPostProcessor (đóng vai trò BeanFactoryPostProcessor) duyệt qua các lớp có đánh dấu @ConfigurationProperties.
3. Bộ xử lý trích xuất tiền tố prefix và gọi ConversionService để chuyển đổi kiểu chuỗi sang các kiểu dữ liệu tương ứng.
4. Nếu lớp có khai báo @Validated, cơ chế Bean Validation sẽ kiểm tra các điều kiện ràng buộc. Bất kỳ vi phạm nào cũng kích hoạt BindValidationException và chặn đứng quá trình khởi động.

Vì diễn ra ở tầng BeanFactoryPostProcessor, cấu hình đã hoàn tất việc binding trước khi bất kỳ business bean nào được khởi tạo.

Vì sao nên ưu tiên @ConfigurationProperties hơn @Value?

Bảng so sánh hai giải pháp quản lý cấu hình:

Để kích hoạt gợi ý thông minh trong IDE, bạn bổ sung dependency hỗ trợ sinh metadata:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

Công cụ này phân tích mã nguồn lúc compile để tạo file META-INF/spring-configuration-metadata.json, giúp IDE hiển thị tooltip và cảnh báo khi bạn nhập sai thuộc tính trong YAML.

Những lỗi sai phổ biến khi binding thuộc tính là gì?

Dưới đây là bốn lỗi thường gặp khi triển khai cấu hình:

1. Quên khai báo annotation @Validated: Nếu thiếu annotation này, các trường rỗng sẽ giữ giá trị null mà không kích hoạt ngoại lệ startup. Lỗi chỉ phát tác dưới dạng NullPointerException khi người dùng gọi API.
2. Quên kích hoạt quét cấu hình: Không khai báo @ConfigurationPropertiesScan ở lớp main khiến Spring bỏ sót record và ném ngoại lệ NoSuchBeanDefinitionException.
3. Dùng @Value phân tách mảng thủ công: Sử dụng @Value để nhận chuỗi phân cách dấu phẩy rồi tự gọi hàm split() rất dễ gây lỗi định dạng thay vì để @ConfigurationProperties tự ánh xạ thành List<String>.
4. Gán trực tiếp mật khẩu vào YAML: Luôn dùng cú pháp tham chiếu biến môi trường thay vì commit trực tiếp khóa bí mật lên repository.

Tóm tắt

• application.properties phù hợp với cấu hình đơn giản; application.yml vượt trội khi cấu trúc phân cấp nhiều tầng.
• Profile-specific files (application-prod.yml) tự động ghi đè thuộc tính khi môi trường tương ứng được kích hoạt.
• Dùng @Value cho các giá trị riêng lẻ cần biểu thức động SpEL; dùng @ConfigurationProperties cho các nhóm cấu hình có cấu trúc.
• Java record kết hợp @ConfigurationProperties và @Validated tạo nên chuẩn quản trị cấu hình type-safe, bất biến và fail-fast.
• ConfigurationPropertiesBindingPostProcessor hoàn tất việc chuyển đổi kiểu dữ liệu trước khi các bean nghiệp vụ được tạo.

Tự kiểm tra

Bài tiếp theo: Profiles — activation & @Profile