application.properties vs application.yml — externalized configuration

Auto-config (bài 03) tạo bean dựa vào classpath. Nhưng config giá trị (DB URL, API key, pool size) đến từ đâu? Đó là externalized configuration — Boot 1 trong 5 trụ cột. Bài này bóc cơ chế: 17 nguồn property xếp ưu tiên, 2 format file (properties/YAML), 2 cách inject (@Value vs @ConfigurationProperties), profile-specific, relax binding, và pattern thực tế cho production.

Đa phần dev biết "config trong application.yml". Bài này trả lời câu hỏi sâu: nếu cùng property db.url xuất hiện ở 5 nguồn, nguồn nào win? Khi nào dùng @Value thay @ConfigurationProperties? Vì sao K8s env var DB_URL map được sang db.url mà không phải config?

1. Vì sao externalize config

Spring 4 era — cấu hình hardcode trong code:

public class App {
    DataSource ds = new HikariDataSource("jdbc:postgresql://localhost/dev", "user", "pass");
}

Pain rõ ràng:

• Build per env: dev/staging/prod khác URL → build 3 jar khác nhau, không reproducible.
• Secret leak: password trong source code → commit lên git → security incident.
• Khó debug: muốn override 1 setting cho 1 lần test → phải sửa code, rebuild.

Lời giải: externalize — config sống ngoài jar, đọc tại runtime:

@Value("${db.url}")
private String dbUrl;

# application.yml
db.url: jdbc:postgresql://localhost/dev

# Override khi run:
java -Ddb.url=jdbc:postgresql://prod/app -jar app.jar
java -jar app.jar --db.url=jdbc:postgresql://prod/app
DB_URL=jdbc:postgresql://prod/app java -jar app.jar

3 cách override khác nhau (system prop, command line, env var). Boot quản theo ưu tiên — section 2.

2. 17 nguồn PropertySource — ưu tiên cao đến thấp

Boot 3.4 có 17 nguồn property. Khi resolve \${db.url}, Boot tra theo thứ tự:

Đảo ngược thứ tự ưu tiên — cao xuống thấp:

flowchart TB
    L1["1. Command line args<br/>--db.url=..."]
    L2["2. SPRING_APPLICATION_JSON"]
    L3["3. Java System Properties<br/>-Ddb.url=..."]
    L4["4. OS Environment Variables<br/>DB_URL=..."]
    L5["5. application-\{profile\}.properties"]
    L6["6. application.properties / .yml"]
    L7["7. @PropertySource"]
    L8["8. Default properties"]

    L1 --> L2 --> L3 --> L4 --> L5 --> L6 --> L7 --> L8

    style L1 fill:#fef3c7
    style L4 fill:#fef3c7
    style L6 fill:#d1fae5

Quy tắc nhớ: càng "ngoài" (command line) → càng cao priority. application.yml ở giữa — base default, override được từ trên (env var, command line) và override từ dưới (default properties).

2.1 Pattern thực tế deployment

# application.yml (commit git, default cho dev)
db:
  url: jdbc:postgresql://localhost:5432/dev
  username: dev_user
spring:
  profiles:
    active: dev

# application-prod.yml (commit git, override cho prod)
db:
  url: jdbc:postgresql://prod-db.internal:5432/app
  username: app_prod

# K8s deployment.yaml (production secrets)
spec:
  containers:
    - name: app
      env:
        - name: SPRING_PROFILES_ACTIVE
          value: prod
        - name: DB_PASSWORD                    # Secret, override application.yml
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: password

Boot resolve db.password:

1. Check command line — không có.
2. Check env var DB_PASSWORD — có (relax binding → match db.password). Win. ← prod secret từ K8s Secret.

Pattern này standard 2026:

• application.yml ↔ default + dev.
• application-\{profile\}.yml ↔ prod-specific non-secret.
• Env var ↔ secrets từ Vault/K8s Secret.
• Command line ↔ ad-hoc override (debug, smoke test).

3. Properties vs YAML — chọn cái nào

Boot support cả 2 format. Cùng config viết 2 cách:

application.properties:

spring.datasource.url=jdbc:postgresql://localhost/app
spring.datasource.username=app
spring.datasource.password=secret
spring.datasource.hikari.maximum-pool-size=20
spring.jpa.hibernate.ddl-auto=update
spring.jpa.properties.hibernate.format_sql=true
logging.level.com.olhub=DEBUG

application.yml:

spring:
  datasource:
    url: jdbc:postgresql://localhost/app
    username: app
    password: secret
    hikari:
      maximum-pool-size: 20
  jpa:
    hibernate:
      ddl-auto: update
    properties:
      hibernate:
        format_sql: true

logging:
  level:
    com.olhub: DEBUG

Khuyến nghị 2026:

• YAML cho file lớn (>30 entry) — hierarchical đọc dễ hơn.
• Properties cho file nhỏ hoặc khi tool không support YAML.
• Mix được — 1 project có cả application.properties và application.yml (Boot merge cả 2). Nhưng tránh mix — confusing.

Cảnh báo YAML:

# YAML — indent matters!
spring:
  datasource:
    url: jdbc:postgresql://...
   username: app           # 3 space thay 4 → typo, parse fail

vs:

# Properties — flat, no indent risk
spring.datasource.url=jdbc:postgresql://...
spring.datasource.username=app

Khoá này dùng YAML mặc định, properties cho ví dụ ngắn.

4. Profile-specific configuration

3 file phổ biến:

src/main/resources/
├── application.yml              <- chung cho moi profile
├── application-dev.yml          <- override khi profile=dev active
├── application-staging.yml      <- override khi profile=staging
└── application-prod.yml         <- override khi profile=prod

Activate profile qua:

# Cach 1: command line
java -jar app.jar --spring.profiles.active=prod

# Cach 2: env var
SPRING_PROFILES_ACTIVE=prod java -jar app.jar

# Cach 3: trong application.yml (rare, tu activate)
spring:
  profiles:
    active: dev

Boot load application.yml → đè bằng application-prod.yml. Property nào không có trong prod.yml → giữ giá trị từ application.yml.

4.1 Profile groups (Boot 2.4+)

Group nhiều profile thành 1 logic:

spring:
  profiles:
    group:
      prod: prod-db, prod-cache, prod-tracing
      staging: staging-db, staging-cache

Activate prod → tự include prod-db, prod-cache, prod-tracing. Tách thành 3 file:

application-prod-db.yml          # config DB cho prod
application-prod-cache.yml       # config cache
application-prod-tracing.yml     # config tracing

Lợi ích: tách concern, file nhỏ dễ maintain. Khi 1 file lớn 100 dòng, group là cách clean.

4.2 Multi-document YAML (Boot 2.4+)

Spring Boot 2.4 cho phép nhiều "document" trong 1 YAML file, ngăn cách bằng ---:

# application.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost/dev   # default cho dev

---
spring:
  config:
    activate:
      on-profile: prod
  datasource:
    url: jdbc:postgresql://prod/app

---
spring:
  config:
    activate:
      on-profile: staging
  datasource:
    url: jdbc:postgresql://staging/app

3 document trong 1 file — Boot pick document có profile match. Dùng khi không muốn tách nhiều file.

5. @Value vs @ConfigurationProperties — 2 cách inject

5.1 @Value — inline injection

@Service
public class OrderService {
    @Value("${app.max-orders:100}")            // default 100 neu thieu
    private int maxOrders;

    @Value("${app.allowed-origins}")            // CSV → split
    private List<String> allowedOrigins;

    @Value("#{systemProperties['user.home']}")  // SpEL
    private String userHome;
}

Pros: đơn giản, inline. Cons:

• Không type-safe khi property phức tạp.
• Spread khắp class — khó refactor.
• Không validate (typo property name → fail runtime).
• Không IDE autocomplete (string literal).

Khi dùng: 1-2 property đơn giản, hoặc khi property là SpEL expression động.

5.2 @ConfigurationProperties — type-safe binding

@ConfigurationProperties(prefix = "app")
@Validated                                     // bat validation
public class AppProperties {

    @NotBlank
    private String name;

    @Min(1) @Max(1000)
    private int maxOrders = 100;

    @NotEmpty
    private List<String> allowedOrigins;

    private Database database = new Database();

    public static class Database {
        @NotBlank
        private String url;

        private int poolSize = 10;
        // getters/setters
    }

    // getters/setters
}

app:
  name: OLHub
  max-orders: 500
  allowed-origins:
    - https://olhub.org
    - https://www.olhub.org
  database:
    url: jdbc:postgresql://localhost/app
    pool-size: 30

Register:

@SpringBootApplication
@ConfigurationPropertiesScan                   // scan @ConfigurationProperties
public class App { ... }

// Hoac:
@EnableConfigurationProperties(AppProperties.class)
@Configuration
public class AppConfig { ... }

Sử dụng:

@Service
public class OrderService {
    private final AppProperties props;

    public OrderService(AppProperties props) {
        this.props = props;
    }

    public void process() {
        if (orders.size() > props.getMaxOrders()) { ... }
    }
}

Pros:

• Type-safe: int, List, nested object đúng kiểu.
• Validation: @NotBlank, @Min, @Max từ Jakarta Validation.
• IDE autocomplete: nếu generate metadata (qua spring-boot-configuration-processor), IDE hint property + Javadoc.
• Nested: object lồng nhau, inject 1 lần dùng nhiều nơi.
• Refactor-friendly: rename property qua IDE, IDE tự update YAML.

Cons:

• Setup nhiều (class + getters/setters + register).
• Verbose cho 1-2 property.

Khi dùng: mọi config domain-specific cho app/feature. Đây là best practice 2026.

5.3 Records cho immutable config (Boot 2.6+)

Java 17 records giúp @ConfigurationProperties cực kỳ gọn:

@ConfigurationProperties(prefix = "app")
@Validated
public record AppProperties(
    @NotBlank String name,
    @Min(1) @Max(1000) int maxOrders,
    @NotEmpty List<String> allowedOrigins,
    Database database
) {
    public record Database(
        @NotBlank String url,
        int poolSize
    ) {}
}

Tương đương 50 dòng class trên — gọn hơn 5x. Immutable (record final by default), thread-safe, no setter pollution.

Đây là pattern khoá này dùng — record + @ConfigurationProperties + @Validated.

5.4 Generate IDE metadata

Thêm dependency:

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

Annotation processor đọc @ConfigurationProperties class lúc compile, sinh file META-INF/spring-configuration-metadata.json. IDE (IntelliJ, VSCode) đọc file này → autocomplete property + show Javadoc + warn typo.

app:
  ma|        # IDE goi y: max-orders, name

6. Relax binding — cứu cánh K8s/Docker

Boot có cơ chế relax binding: 1 property name match nhiều format khác nhau:

Quy tắc canonical: kebab-case (app.max-orders) trong YAML/properties. Boot tự convert kebab ↔ camel ↔ env var.

6.1 Cơ chế relax cụ thể

Khi Boot resolve app.max-orders:

1. Convert kebab → uppercase + underscore: APP_MAX_ORDERS.
2. Tra env var: tìm APP_MAX_ORDERS → có → dùng.
3. Nếu không, tra system prop: app.max-orders literal.
4. Nếu không, tra config file.
5. Default value (nếu có).

Pattern K8s/Docker:

# K8s deployment.yaml
spec:
  containers:
    - name: app
      env:
        - name: SPRING_DATASOURCE_URL          # → spring.datasource.url
          value: jdbc:postgresql://prod/app
        - name: APP_MAX_ORDERS                  # → app.max-orders
          value: "1000"
        - name: SPRING_PROFILES_ACTIVE          # → spring.profiles.active
          value: prod

K8s standard dùng UPPER_SNAKE_CASE env var. Boot relax binding tự match → không cần file config trong container.

6.2 Edge case

SPRING_APPLICATION_JSON — env var đặc biệt accept JSON object:

SPRING_APPLICATION_JSON='{"app":{"max-orders":1000,"allowed-origins":["https://olhub.org"]}}'
java -jar app.jar

Hữu ích khi cần override nhiều property cùng lúc qua 1 env var (vd CI/CD inject config block).

7. Pattern thực tế cho production

7.1 Tách config theo concern

application.yml                 # default + dev
application-staging.yml         # staging override
application-prod.yml            # prod override (non-secret)

# Secrets KHONG commit vao git:
.env (local)                    # symlink to actual values
K8s Secret (prod)               # mount qua env var hoac file
Vault (prod)                    # Spring Cloud Config / Spring Cloud Vault

Quy tắc: không bao giờ commit secret vào git. Repository scanner (GitGuardian, GitHub Secret Scanning) detect và alert. Mọi password/API key qua env var hoặc secrets manager.

7.2 Reference env var trong YAML

spring:
  datasource:
    url: ${DB_URL}                              # required
    username: ${DB_USER:app}                    # default 'app'
    password: ${DB_PASS}                        # required, fail nếu thiếu
    hikari:
      maximum-pool-size: ${DB_POOL_SIZE:20}    # default 20

Cú pháp \${VAR:default} — fallback nếu env var không có. Required (no default) → app fail to start nếu thiếu, log clear error message.

7.3 Spring Cloud Config Server (preview)

Cho enterprise có nhiều service, centralize config qua Config Server:

# bootstrap.yml (special file load truoc application.yml)
spring:
  config:
    import: configserver:https://config.acme.internal
  application:
    name: order-service

Config Server expose REST API trả config cho order-service. Service start → fetch config → merge với local → start app. Module 11 (Microservices) sẽ đào sâu.

8. Pitfall tổng hợp

❌ Nhầm 1: Hardcode secret trong application.yml commit git.

spring:
  datasource:
    password: prod-secret-2026     # LO TREN GITHUB

✅ Reference env var: password: \${DB_PASS}. Set env var qua K8s Secret hoặc Vault.

❌ Nhầm 2: Dùng @Value cho 20 property cùng prefix.

@Value("${app.name}") String name;
@Value("${app.max-orders}") int maxOrders;
@Value("${app.allowed-origins}") List<String> origins;
// ... 17 dong nua

✅ Bind qua @ConfigurationProperties(prefix = "app") — type-safe, validate, refactor.

❌ Nhầm 3: YAML indent inconsistent.

spring:
  datasource:
    url: jdbc:postgresql://...
   username: app          # 3 space — parse fail

✅ Dùng IDE với YAML linter (IntelliJ, VSCode YAML extension), hoặc dùng application.properties cho file ngắn.

❌ Nhầm 4: Tin "env var override application.yml luôn." ✅ Đúng cho hầu hết case, nhưng command line args override env var (priority cao hơn). Verify thứ tự ưu tiên.

❌ Nhầm 5: Không validate @ConfigurationProperties.

@ConfigurationProperties(prefix = "app")
public record Props(String url) {}

User quên set app.url → field null → NPE runtime sau khi app đã start. ✅ Thêm @Validated + @NotBlank/@NotNull → fail-fast tại startup nếu thiếu.

❌ Nhầm 6: Nhầm application.yml và bootstrap.yml. ✅ application.yml — config app thường. bootstrap.yml — load trước application.yml, dùng cho Spring Cloud Config bootstrap. Không nhầm — Boot 3+ migrate sang spring.config.import, dần bỏ bootstrap.yml.

❌ Nhầm 7: Dùng underscore trong YAML key.

app_max_orders: 100      # Boot van resolve, nhung khong canonical

✅ Dùng kebab-case canonical: app.max-orders: 100 hoặc app:\n max-orders: 100.

❌ Nhầm 8: Quên @ConfigurationPropertiesScan hoặc @EnableConfigurationProperties. ✅ Add 1 trong 2 vào @SpringBootApplication class. Class @ConfigurationProperties không tự register.

9. 📚 Deep Dive Spring Reference

10. Tóm tắt

• Externalize config = config sống ngoài jar, đọc tại runtime — giải quyết build-per-env, secret leak, debug khó.
• Boot có 17 PropertySource xếp ưu tiên: command line > env var > application-{profile}.yml > application.yml > default.
• 2 format file: application.properties (flat) và application.yml (hierarchical). YAML tốt hơn cho file lớn.
• Profile-specific files (application-prod.yml) override application.yml. Activate qua --spring.profiles.active=prod hoặc SPRING_PROFILES_ACTIVE.
• Profile groups (Boot 2.4+) gom profile thành logic: prod = prod-db + prod-cache + prod-tracing.
• Multi-document YAML (Boot 2.4+) — nhiều profile trong 1 file qua --- separator + spring.config.activate.on-profile.
• 2 cách inject: @Value("${...}") cho 1-2 property đơn giản; @ConfigurationProperties cho group config — type-safe, validate, IDE autocomplete.
• Records + @ConfigurationProperties + @Validated = pattern modern 2026 — gọn, immutable, fail-fast.
• spring-boot-configuration-processor annotation processor sinh spring-configuration-metadata.json cho IDE hint.
• Relax binding: kebab-case canonical match camelCase/snake_case/UPPER_SNAKE_CASE. K8s env var SPRING_DATASOURCE_URL → spring.datasource.url tự nhiên.
• \${VAR:default} syntax cho fallback. Required env var (no default) → fail-fast nếu thiếu.
• Production pattern: non-secret trong git (application.yml, application-prod.yml); secret qua env var (K8s Secret, Vault). Không bao giờ commit secret.
• Debug runtime: /actuator/env + /actuator/configprops. Dev local: --debug flag.

11. Tự kiểm tra

@Service
public class HealthCheck {
  @Value("#{T(java.time.Instant).now()}")     // SpEL
  private Instant startedAt;

  @Value("${git.commit.id:unknown}")          // 1 prop don gian
  private String commitId;
}

@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,
  Duration timeout,
  List<String> ccAddresses
) {}

spring:
datasource:
  url: jdbc:postgresql://prod-db.internal:5432/app
  username: app_prod
  password: prod-secret-2026
 hikari:
    maximum-pool-size: 50

logging:
level:
  com.olhub: DEBUG

spring:
datasource:
  url: ${DB_URL}
  username: ${DB_USER:app}
  password: ${DB_PASSWORD}
  hikari:
    maximum-pool-size: ${DB_POOL_SIZE:20}

logging:
level:
  com.olhub: ${LOG_LEVEL:INFO}

@ConfigurationProperties(prefix = "app.email")
public record EmailProps(
  String host,
  int port,
  String username,
  String password,
  boolean tlsEnabled
) {}

// Trong App.java:
@SpringBootApplication
public class App { ... }

// pom.xml: them spring-boot-configuration-processor (optional)

@ConfigurationProperties(prefix = "app.email")
@Validated
public record EmailProps(
  /** SMTP server host. */
  @NotBlank String host,
  /** SMTP port. Common: 25, 465 (SSL), 587 (TLS). */
  @Min(1) @Max(65535) int port,
  /** SMTP username. */
  @NotBlank String username,
  /** SMTP password. */
  @NotBlank String password,
  /** Enable TLS encryption. */
  boolean tlsEnabled
) {}

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

# application.yml
app:
email:
  host: ${SMTP_HOST}
  port: ${SMTP_PORT:587}
  username: ${SMTP_USER}
  password: ${SMTP_PASS}
  tls-enabled: true

Bài tiếp theo: Profiles — dev/staging/prod activation, profile-specific bean, profile group