{}KDevTool
← Tất cả bài viết

YAML vs .properties trong Spring Boot: chọn cái nào?

19/07/2026

Khi khởi tạo một dự án Spring Boot, một trong những quyết định đầu tiên bạn phải đưa ra là: cấu hình ứng dụng bằng application.properties hay application.yml? Cả hai đều được Spring Boot hỗ trợ mặc định, đều nạp cùng một tập thuộc tính và cho ra kết quả giống hệt nhau khi ứng dụng chạy. Nhưng cú pháp, khả năng đọc và những cái bẫy đi kèm lại khác nhau đáng kể. Bài viết này so sánh trực tiếp hai định dạng, chỉ ra các lỗi thường gặp và đưa ra khuyến nghị chọn cái nào cho từng tình huống thực tế.

Spring Boot đọc cấu hình như thế nào?

Spring Boot tự động tìm và nạp file cấu hình từ classpath (thường là src/main/resources) hoặc thư mục làm việc. Thứ tự ưu tiên mặc định là application.properties được nạp sau application.yml, nghĩa là nếu tồn tại cả hai và cùng khai báo một key, giá trị trong .properties sẽ ghi đè. Trong thực tế, bạn nên chọn một định dạng cho toàn dự án để tránh nhầm lẫn.

Điều quan trọng cần nhớ: dù bạn viết bằng định dạng nào, Spring Boot đều quy về cùng một cấu trúc key phẳng dạng a.b.c trong Environment. YAML chỉ là một cách trình bày khác của cùng tập key đó.

Cú pháp .properties

File .properties dùng các cặp key=value phẳng, mỗi dòng một key. Các key lồng nhau được biểu diễn bằng dấu chấm phân tách:

server.port=8080
server.servlet.context-path=/api

spring.datasource.url=jdbc:postgresql://localhost:5432/devhub
spring.datasource.username=admin
spring.datasource.password=secret
spring.datasource.hikari.maximum-pool-size=10

spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=true

logging.level.org.springframework=INFO
logging.level.com.devhub=DEBUG

Ưu điểm dễ thấy: mỗi key là một dòng độc lập, không phụ thuộc thụt lề, nên rất khó viết sai. Nhược điểm: khi có nhiều key cùng tiền tố (như spring.datasource.*), bạn phải lặp lại tiền tố đó ở từng dòng, khiến file dài và rườm rà.

Cú pháp YAML

YAML thể hiện cấu trúc phân cấp bằng thụt lề (indentation), gộp các key cùng tiền tố lại thành một khối. Cùng cấu hình trên viết lại bằng YAML:

server:
  port: 8080
  servlet:
    context-path: /api

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/devhub
    username: admin
    password: secret
    hikari:
      maximum-pool-size: 10
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: true

logging:
  level:
    org.springframework: INFO
    com.devhub: DEBUG

Với YAML, tiền tố spring.datasource chỉ viết một lần, các key con nằm gọn bên dưới. Khi cấu hình có nhiều tầng lồng nhau, YAML rõ ràng và ngắn hơn hẳn. Nếu bạn cần chuyển đổi qua lại giữa hai định dạng để so sánh hoặc migrate dần, có thể dùng công cụ YAML ⇄ Properties Converter để tránh gõ tay dễ sai.

So sánh khả năng đọc và cấu trúc

YAML thắng rõ ở các cấu hình lồng sâu và ở việc biểu diễn cấu trúc dữ liệu phức tạp. YAML hỗ trợ list và map một cách tự nhiên, trong khi .properties phải mô phỏng chúng bằng cú pháp index hoặc key phẳng khá gượng ép.

Ngược lại, .properties đơn giản đến mức gần như không thể viết sai cú pháp: không có khái niệm thụt lề, không có kiểu dữ liệu ngầm gây bất ngờ. Nó cũng dễ override qua biến môi trường và tham số dòng lệnh hơn, vì key phẳng ánh xạ trực tiếp:

# Override qua biến môi trường (dấu chấm -> gạch dưới, viết hoa)
SPRING_DATASOURCE_PASSWORD=prod-secret

# Override qua command line khi chạy
java -jar app.jar --server.port=9090 --spring.jpa.show-sql=false

Danh sách (list/array): YAML vs properties

Đây là chỗ khác biệt lớn nhất về cú pháp. Trong YAML, list viết bằng dấu gạch đầu dòng:

app:
  cors:
    allowed-origins:
      - https://chovn.site
      - https://admin.chovn.site
    allowed-methods: [GET, POST, PUT, DELETE]

Trong .properties, cùng list đó phải viết bằng chỉ số [0], [1]... hoặc gộp một dòng ngăn cách bằng dấu phẩy:

app.cors.allowed-origins[0]=https://chovn.site
app.cors.allowed-origins[1]=https://admin.chovn.site
app.cors.allowed-methods=GET,POST,PUT,DELETE

Khi list dài, cú pháp index của .properties trở nên khó bảo trì (thêm/bớt phần tử phải đánh lại số thứ tự), còn YAML chỉ cần thêm/xóa một dòng gạch đầu dòng.

Những cái bẫy của YAML

YAML gọn hơn nhưng cũng nhiều cạm bẫy hơn. Đây là những lỗi hay gặp nhất:

  • Thụt lề phải dùng dấu cách (SPACE), tuyệt đối không dùng TAB. Trình phân tích YAML sẽ báo lỗi hoặc hiểu sai cấu trúc nếu bạn nhấn Tab. Nên cấu hình editor tự chuyển Tab thành 2 dấu cách.
  • Kiểu dữ liệu ngầm. YAML tự suy luận kiểu. Các giá trị như yes, no, on, off, true, false có thể bị hiểu thành boolean thay vì chuỗi. Ví dụ mã quốc gia country: NO (Na Uy) sẽ thành false!
  • Số có số 0 đứng đầu. Ở YAML 1.1, giá trị như 010 có thể bị hiểu là số bát phân (octal) = 8. Điều này gây rắc rối với mã PIN, mã bưu điện hay version.
  • Số thực và chuỗi trông giống nhau. version: 3.10 sẽ được đọc là số 3.1 (mất số 0 cuối), còn version: "3.10" giữ nguyên chuỗi. Rất dễ sai khi khai báo phiên bản.
  • Ký tự đặc biệt cần đặt trong nháy. Các giá trị chứa :, #, {, @, * hoặc bắt đầu bằng ký tự đặc biệt nên bọc trong nháy đơn hoặc nháy kép, ví dụ mật khẩu password: "p@ss:word#1".

Nguyên tắc an toàn: khi giá trị có nguy cơ bị hiểu nhầm kiểu, hãy luôn bọc nó trong nháy để ép về chuỗi.

Nhiều profile: multi-document YAML vs properties

YAML cho phép gộp cấu hình của nhiều profile vào một file duy nhất, ngăn cách bằng dấu --- (multi-document):

spring:
  application:
    name: devhub

---
spring:
  config:
    activate:
      on-profile: dev
server:
  port: 8080

---
spring:
  config:
    activate:
      on-profile: prod
server:
  port: 80

Bên .properties không có cú pháp multi-document, nên cách làm chuẩn là tách thành nhiều file theo tên profile: application-dev.properties, application-prod.properties, và một application.properties chung. Bạn kích hoạt profile qua spring.profiles.active=dev. Cách tách file này thực ra cũng áp dụng được cho YAML và thường được coi là gọn gàng hơn multi-document khi cấu hình mỗi profile lớn.

Bảng so sánh nhanh

Tiêu chí YAML (.yml) .properties
Cấu hình lồng nhau Gọn, dễ đọc, không lặp tiền tố Lặp tiền tố ở mỗi dòng, dài dòng
List / Map Hỗ trợ tự nhiên (gạch đầu dòng) Phải dùng index [0], [1]...
Nguy cơ lỗi cú pháp Cao (thụt lề, kiểu ngầm) Thấp, gần như không sai
Override qua env / command line Được, nhưng ánh xạ ít trực quan hơn Rất trực tiếp, dễ nhất
Nhiều profile trong 1 file Có (dùng ---) Không, phải tách file
Comment Dùng # Dùng # hoặc !
Độ phổ biến trong dự án lớn Rất cao Phổ biến ở dự án nhỏ / legacy

Khuyến nghị thực tế

Không có lựa chọn "đúng tuyệt đối", nhưng có thể dựa vào các tiêu chí sau:

  1. Chọn YAML khi: cấu hình có nhiều tầng lồng nhau, nhiều list/map (CORS origins, danh sách server, cấu hình message broker...), hoặc bạn muốn quản lý nhiều profile trong một file. YAML cũng là chuẩn de-facto trong hệ sinh thái Spring Boot hiện đại và các file Kubernetes/Docker Compose xung quanh.
  2. Chọn .properties khi: cấu hình đơn giản, ít cấp lồng nhau; team chưa quen YAML và muốn tránh lỗi thụt lề; hoặc khi bạn override cấu hình nhiều qua biến môi trường và command line (phổ biến trong môi trường container/CI).
  3. Nhất quán: dù chọn cái nào, hãy dùng thống nhất một định dạng trong toàn dự án. Tránh trộn lẫn khiến việc override khó lường.

Một chiến lược thực dụng nhiều team áp dụng: dùng YAML cho cấu hình gốc dễ đọc, nhưng override các giá trị nhạy cảm (mật khẩu, URL production) bằng biến môi trường ở tầng triển khai — tận dụng điểm mạnh của cả hai.

Kết luận

YAML và .properties cho ra kết quả tương đương trong Spring Boot; khác biệt nằm ở khả năng đọc và các cạm bẫy. YAML gọn và mạnh cho cấu hình phức tạp nhưng nhạy cảm với thụt lề và kiểu dữ liệu ngầm; .properties đơn giản, an toàn và dễ override nhưng cồng kềnh khi lồng sâu. Hãy chọn theo độ phức tạp cấu hình và thói quen của team, và luôn giữ sự nhất quán.

Đang phân vân hoặc cần migrate cấu hình cũ sang định dạng mới? Thử ngay công cụ YAML ⇄ Properties Converter của DevToolHub để chuyển đổi hai chiều nhanh chóng, chính xác và không lo sai thụt lề.