Trình Định Dạng & Xác Thực YAML

Dán YAML để định dạng và xác thực nó. Xem lỗi tức thì, sửa thụt lề và chuyển đổi sang JSON.

Được xử lý cục bộ · không có gì được gửi đến máy chủ
Dán YAML để xác thực

YAML là gì?

YAML (YAML Ain't Markup Language) là một định dạng tuần tự hóa dữ liệu dễ đọc bởi con người, được sử dụng cho các tệp cấu hình (Docker, Kubernetes, GitHub Actions, Ansible), trao đổi dữ liệu và hơn thế nữa. Nó sử dụng thụt lề thay vì dấu ngoặc nhọn và là một tập cha của JSON.

Câu hỏi thường gặp

Trình xác thực phát hiện những lỗi nào?

Lỗi thụt lề, thiếu dấu hai chấm, khóa trùng lặp, ký tự không hợp lệ, chuỗi không đóng, lồng nhau sai và các vấn đề cú pháp YAML khác. Thông báo lỗi bao gồm số dòng.

Tôi có thể chuyển đổi YAML sang JSON không?

Có! Nhấp nút « → JSON » để chuyển đổi YAML của bạn sang JSON được định dạng tốt. Cho chuyển đổi ngược lại, sử dụng Trình Chuyển Đổi JSON Sang YAML của chúng tôi.

Giới Thiệu Nhanh Về YAML

YAML 1.0 được xuất bản năm 2001 bởi Clark Evans, Ingy döt Net và Oren Ben-Kiki; YAML 1.1 ra mắt năm 2005, và phiên bản hiện tại là YAML 1.2.2, đã khắc phục một số vấn đề lịch sử (đặc biệt là «vấn đề Na Uy», xem bên dưới) và được thiết kế là superset nghiêm ngặt của JSON. Spec chính thức tại yaml.org/spec/1.2.2. Formatter này dùng thư viện mã nguồn mở js-yaml, phân tích theo schema YAML 1.2 theo mặc định, vì vậy hầu hết các quirk kế thừa từ 1.1 không áp dụng cho văn bản được định dạng ở đây, nhưng chúng áp dụng cho hầu hết YAML tooling phía máy chủ mà bạn sẽ gửi đầu ra đến.

YAML Xuất Hiện Ở Đâu

YAML đã trở thành định dạng cấu hình tiêu chuẩn cho cơ sở hạ tầng cloud-native. Những nơi bạn gặp nó nhiều nhất:

Bẫy Khoảng Trắng (Chỉ Dùng Dấu Cách)

YAML dùng thụt lề để biểu thị cấu trúc, và spec quy định rõ ràng rằng tab không được phép dùng cho thụt lề. Chỉ dùng dấu cách. Đây là nguồn lỗi phổ biến nhất trong YAML viết tay, đặc biệt vì nhiều trình soạn thảo âm thầm trộn tab và dấu cách tùy theo cài đặt của chúng. Thông báo lỗi bạn nhận được từ parser nghiêm ngặt sẽ kiểu như «found character '\t' that cannot start any token», tức là «bạn đã dùng tab ở đâu đó.» Cách sửa là phổ quát: bật «show whitespace» trong trình soạn thảo và chuyển đổi mọi tab thành hai hoặc bốn dấu cách.

Kích thước thụt lề là quy ước hơn là spec. 2 dấu cách là tiêu chuẩn thực tế cho manifest Kubernetes, GitHub Actions và hầu hết YAML bạn sẽ đọc trên web hiện đại. 4 dấu cách phổ biến hơn trong Ansible. Quy tắc quan trọng: nhất quán trong một tệp. Việc trộn 2 và 4 dấu cách giữa các key cùng cấp mới khiến parser bị nhầm, không phải kích thước bạn chọn.

Vấn Đề Na Uy (và Lý Do Nên Đặt Dấu Ngoặc Kép Cho Chuỗi Mơ Hồ)

YAML 1.1 (vẫn là mặc định trong PyYAML, snakeyaml và nhiều parser phía máy chủ khác) giải thích một danh sách dài các chuỗi boolean không có dấu ngoặc kép như là boolean thực sự: true, True, TRUE, false, False, FALSE, yes, Yes, YES, no, No, NO, y, n, on, off. Bẫy nổi tiếng: mã quốc gia ISO của Na Uy là NO. Một cấu hình YAML liệt kê các quốc gia dưới dạng chuỗi không có dấu ngoặc kép sẽ âm thầm phân tích Na Uy là boolean false, và code downstream đọc countries[0] == 'NO' sẽ thất bại khó hiểu.

YAML 1.2 (và schema mặc định của js-yaml) giới hạn boolean chỉ còn true / false, điều này khắc phục vấn đề Na Uy ở cấp độ parser. Nhưng nhiều công cụ thực tế vẫn mặc định schema YAML 1.1 vì tương thích ngược. Thói quen phòng thủ: đặt dấu ngoặc kép cho bất kỳ chuỗi nào trông giống boolean, số, ngày tháng, hoặc phiên bản. country: "NO", postal_code: "01234", version: "1.10", time: "10:30". Dấu ngoặc kép là cách phân biệt chung.

Các Bẫy Ép Kiểu Khác

Kiểu Block Và Kiểu Flow

YAML hỗ trợ hai ký hiệu cho cùng một dữ liệu:

# Block style (the standard, indentation-based)
person:
  name: Alice
  tags:
    - admin
    - billing

# Flow style (JSON-like inline)
person: { name: Alice, tags: [admin, billing] }

Kiểu block là thứ bạn sẽ thấy trong 99% YAML viết tay, đó là thứ làm cho định dạng có thể đọc được. Kiểu flow là lối thoát hữu ích cho các giá trị ngắn một dòng hoặc để tạo YAML theo chương trình khi bạn không muốn theo dõi thụt lề. Formatter chuẩn hóa về kiểu block cho đầu ra (dạng dễ đọc hơn) bất kể style đầu vào của bạn là gì.

Anchor và Alias (Thủ Thuật DRY)

Tính năng tái sử dụng của YAML: định nghĩa một giá trị một lần với anchor &name, tham chiếu nó ở nơi khác bằng alias *name. Tiện lợi cho các tệp cấu hình dài nơi cùng một block giá trị xuất hiện nhiều lần.

defaults: &defaults
  region: us-east-1
  log_level: info

production:
  <<: *defaults
  log_level: warn   # override

staging:
  <<: *defaults

Một vài lưu ý: không phải mọi YAML processor đều hỗ trợ anchor và alias (đặc biệt là một số công cụ manifest Kubernetes cũ hơn và một số ngữ cảnh Helm nhất định). Cú pháp <<: «merge key» được hiển thị ở trên là phần mở rộng YAML 1.1 và chính thức bị deprecated trong 1.2, js-yaml hỗ trợ nó, nhưng các parser 1.2 thuần có thể không.

Tệp Đa Tài Liệu

Một tệp YAML có thể chứa nhiều tài liệu, được phân tách bằng ---. Phổ biến trong Kubernetes, một tệp với Deployment, Service và ConfigMap, được phân tách bằng ---, áp dụng bằng một lần kubectl apply -f:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app
---
apiVersion: v1
kind: Service
metadata:
  name: app-svc

YAML so với JSON so với TOML

Nếu bạn có lựa chọn cho cấu hình mới: TOML cho cấu hình phẳng, YAML nếu bạn cần lồng sâu và hệ sinh thái đã chuẩn hóa trên nó (Kubernetes, Ansible), JSON nếu máy tính viết nó. YAML là định dạng phù hợp khi con người cần đọc cấu hình lồng sâu và viết comment có ý nghĩa inline.

Quyền Riêng Tư

Cấu hình YAML thường chứa bí mật không nên đi qua máy chủ của người khác: blob base64 Kubernetes Secret, mật khẩu database trong application.yml, API key trong CI workflow, hostname nội bộ trong cấu hình deployment. Formatter chạy hoàn toàn trong trình duyệt của bạn thông qua thư viện js-yaml mã nguồn mở, nội dung dán được phân tích và phát lại cục bộ, không có fetch / không tải lên / không ghi log. Đóng tab xóa sạch tất cả.

Các Lỗi Phổ Biến

  1. Trộn tab và dấu cách trong thụt lề. Lỗi phổ biến nhất. Tab bị cấm bởi spec; một số trình soạn thảo chèn chúng âm thầm. Hiển thị khoảng trắng trong trình soạn thảo của bạn.
  2. Thụt lề không nhất quán giữa các key cùng cấp. Các key cùng cấp phải được căn chỉnh cùng cột. Thụt lề hỗn hợp 2/4 dấu cách làm hỏng quá trình phân tích.
  3. Giá trị không có dấu ngoặc kép trông giống boolean, số, ngày tháng, hoặc thời gian. NO, 012, 1.10, 10:30, yes: đặt dấu ngoặc kép cho chúng.
  4. Thiếu dấu cách sau dấu hai chấm. key: value hoạt động; key:value không hợp lệ (được phân tích là chuỗi đơn).
  5. Khoảng trắng cuối dòng. Một số parser coi khoảng trắng cuối dòng là có nghĩa; một số thì không. Thói quen an toàn qua nhiều công cụ là xóa khoảng trắng cuối dòng.
  6. Chuỗi nhiều dòng không có block scalar phù hợp. Chuỗi dài cần | (literal, giữ nguyên xuống dòng) hoặc > (folded, nối các dòng). Văn bản nhiều dòng thuần túy không có dấu ngoặc kép hiếm khi hoạt động theo cách bạn mong đợi.
  7. Giả định anchor / alias ở khắp nơi. Helm và một số ngữ cảnh Kubernetes không hỗ trợ đầy đủ &/*. Kiểm tra trong pipeline thực tế trước khi phụ thuộc vào chúng.
  8. Không khớp mã hóa. Tệp YAML nên dùng UTF-8. Trình soạn thảo Windows lưu dưới dạng UTF-16 với BOM tạo ra tệp mà một số parser không thể đọc.

Câu Hỏi Thường Gặp Thêm

Formatter có giữ lại comment của tôi không?

Không. Thư viện js-yaml phân tích YAML thành giá trị JavaScript và phát lại từ giá trị đó, có nghĩa là comment (# like this) bị loại bỏ, chúng tồn tại trong văn bản nguồn, không phải trong cấu trúc đã phân tích. Nếu việc giữ lại comment quan trọng (thường là vậy với các tệp cấu hình được chỉnh tay), hãy dùng phương án thay thế giữ comment như eemeli/yaml thông qua CST API của nó, hoặc thực hiện các chỉnh sửa nhỏ bằng tay thay vì round-trip qua formatter này.

Tại sao NO của tôi bị parser YAML của máy chủ coi là boolean?

Vì parser đó đang dùng YAML 1.1 (mặc định cho PyYAML, snakeyaml và nhiều parser khác), giải thích NO là boolean false. Formatter này dùng YAML 1.2 theo mặc định (thông qua js-yaml) nên không kích hoạt lỗi ở đây, nhưng ngay khi bạn gửi tệp đến môi trường YAML 1.1, bẫy sẽ kích hoạt. Luôn đặt dấu ngoặc kép cho chuỗi mơ hồ: country: "NO".

Tôi có thể chuyển YAML sang JSON không?

Có, nhấp vào «→ JSON». Chuyển đổi không mất dữ liệu cho mọi thứ có thể biểu diễn trong JSON (chuỗi, số, boolean, null, mảng, đối tượng). Những thứ không sống sót được: comment (JSON không có cú pháp cho chúng), anchor và alias (JSON không có tương đương), và các kiểu ngày / dấu thời gian của YAML (trở thành chuỗi trong JSON). Để đi chiều ngược lại, dùng công cụ JSON to YAML chuyên dụng.

Có gì được gửi lên máy chủ không?

Không. Toàn bộ quá trình phân tích, định dạng và chuyển đổi JSON chạy trong trình duyệt của bạn thông qua js-yaml. YAML đã dán không bao giờ được truyền đến bất kỳ máy chủ nào. Điều này quan trọng vì cấu hình YAML thường chứa bí mật (giá trị Kubernetes Secret, mật khẩu database, API key, endpoint nội bộ) không nên được tải lên dịch vụ bên thứ ba.

Giới hạn kích thước là bao nhiêu?

Không có giới hạn cứng, formatter chạy trong bộ nhớ trình duyệt của bạn. Manifest Kubernetes điển hình (vài KB) và Helm chart (hàng chục KB) định dạng ngay lập tức. Các tệp đa tài liệu rất lớn (nhiều MB) có thể chậm nhưng thường hoạt động; nếu bạn có Helm chart 10 MB, hãy định dạng nó cục bộ bằng công cụ CLI thay thế.

Tại sao YAML dễ gây lỗi vậy?

Ba lý do cộng hưởng: (1) khoảng trắng có ý nghĩa nghĩa là lỗi đánh máy gây ra thay đổi ngữ nghĩa âm thầm; (2) ép kiểu linh hoạt của YAML 1.1 biến các chuỗi mơ hồ thành boolean / số ngoài ý muốn; (3) định dạng có quá nhiều cách viết cùng một thứ (block so với flow, ngoặc đơn so với ngoặc kép, ba kiểu chuỗi nhiều dòng). Các thói quen phòng thủ: luôn đặt dấu ngoặc kép, luôn nhất quán với thụt lề, kiểm tra trước khi triển khai, khắc phục hầu hết bề mặt vấn đề.

Công cụ liên quan

Trình chuyển đổi JSON → YAML

Chuyển đổi giữa các định dạng JSON và YAML.

Trình định dạng JSON

Định dạng, xác thực và làm đẹp dữ liệu JSON.

Trình định dạng XML

Định dạng, làm đẹp hoặc nén XML.