YAML là gì? Cú pháp, kiểu dữ liệu, ứng dụng và cạm bẫy

API thu thập dữ liệu không rác trả về dữ liệu web có cấu trúc ở định dạng JSON hoặc CSV, mà một quy trình được kiểm soát có thể chuyển đổi thành YAML khi cần phải có ranh giới cấu hình đã chỉnh sửa bởi con người.

YAML có nghĩa là gì?

YAML có nghĩa là “YAML không phải là ngôn ngữ định dạng.” Đây là một ngôn ngữ tuần tự hóa dữ liệu dựa trên Unicode được thiết kế để ánh xạ rõ ràng đến các cấu trúc lập trình thông thường. Một tài liệu YAML được xây dựng từ ba loại nút chính: bản đồ cho các liên kết khóa-giá trị, chuỗi cho các bộ sưu tập có thứ tự và số cho các giá trị cá nhân.

Cái đặc tả YAML 1.2.2 mô tả mô hình biểu diễn, cây tuần tự hóa, luồng trình bày, cú pháp, thẻ và lược đồ. Lớp trình bày của YAML cung cấp nhiều cách để viết dữ liệu tương đương, điều này giúp cho các tác giả con người nhưng cung cấp cho người thực hiện nhiều lựa chọn hơn so với ngữ pháp nhỏ hơn của JSON.

YAML là dữ liệu, không phải ngôn ngữ hướng dẫn theo định nghĩa. Các ứng dụng thường sử dụng nó để cấu hình các triển khai, hệ thống xây dựng, công việc tự động hóa, siêu dữ liệu trang tĩnh và công cụ phát triển cục bộ. Ứng dụng quyết định khóa nào là hợp lệ và khóa đó làm gì.

Cú pháp YAML cơ bản

Một cấu hình YAML có thể kết hợp các bản đồ, chuỗi, số, boolean và giá trị lồng nhau:

service:
  name: catalog-worker
  enabled: true
  workers: 4
  regions:
    - us-east
    - eu-west
  output:
    format: json
    include_metadata: true

Dấu hai chấm tách một khóa bản đồ ra khỏi giá trị của nó. Một dấu gạch ngang giới thiệu một mục chuỗi theo kiểu khối. Thụt đầu dòng đặt name, enabled, và các cài đặt còn lại dưới service. Tài liệu này không cần dấu ngoặt hoặc dấu phẩy ở kiểu này.

Bản đồ

Một bản đồ liên kết các khóa với các giá trị. Các khóa thường là chuỗi đơn giản, mặc dù mô hình ngôn ngữ cho phép các khóa phức tạp hơn. Các tác giả cấu hình nên ưa thích các khóa chuỗi đơn giản, duy nhất vì các thư viện ứng dụng và công cụ xác thực xử lý chúng một cách dự đoán được.

Các khóa bản đồ trùng lặp là một vấn đề về tính di động. Các thư viện có thể từ chối chúng, giữ một giá trị, hoặc tiết lộ hành vi được kiểm soát bởi một tùy chọn. Một bộ nạp cấu hình sản xuất nên từ chối các bản sao để người xem và ứng dụng đang chạy thấy cùng một cài đặt hiệu quả.

Chuỗi

Một chuỗi là có thứ tự. Kiểu khối sử dụng một dấu gạch ngang cho mỗi mục, trong khi kiểu luồng sử dụng dấu ngoặc:

regions: [us-east, eu-west]

checks:
  - name: schema
    required: true
  - name: links
    required: true

Mỗi mục có thể là một số, bản đồ hoặc một chuỗi khác. Thứ tự nên chỉ được sử dụng khi hợp đồng ứng dụng phân bổ ý nghĩa cho nó.

Số và trích dẫn

Số bao gồm chuỗi, số, boolean, null, dấu thời gian dưới một số lược đồ, và các giá trị có thẻ rõ ràng. Các số đơn giản bỏ qua dấu ngoặt, nhưng dấu câu và một số từ nhất định có thể được diễn giải theo những cách bất ngờ qua các phiên bản YAML hoặc lược đồ phân tích. Trích dẫn các giá trị khi hình thức văn bản của chúng phải giữ nguyên, bao gồm số phiên bản, định danh có số không đứng đầu và chuỗi giống như boolean hoặc null.

Các chuỗi được trích dẫn đơn xem hầu hết các ký tự theo nghĩa đen. Các chuỗi được trích dẫn kép hỗ trợ các chuỗi thoát. Các số khối sử dụng | để bảo tồn ngắt dòng hoặc > để gập dòng thành khoảng trắng, với các chỉ số bổ sung kiểm soát thụt đầu dòng và ngắt dòng cuối.

Chú thích, Điểm tựa, Tương đương và Thẻ

Một ký tự thăng bắt đầu một chú thích bên ngoài một số được trích dẫn. Các chú thích làm cho YAML hấp dẫn cho cấu hình vì người duy trì có thể giải thích lý do tại sao một cài đặt tồn tại. Các chú thích là phần của trình bày hơn là mô hình dữ liệu cốt lõi, vì vậy nhiều bộ phân tích bỏ qua chúng khi nạp và viết tài liệu.

Một điểm tựa gán một nút, và một tương đương tham chiếu đến nút đó ở nơi khác. Điều này có thể giảm thiểu việc cấu hình lặp lại:

defaults: &defaults
  timeout_seconds: 30
  output: json

jobs:
  catalog:
    <<: *defaults
    region: us-east

Khóa hợp nhất được hiển thị ở đây rất phổ biến, nhưng hành vi hợp nhất không phải là một tính năng đơn giản của mọi con đường xử lý YAML. Xác nhận những gì thư viện và ứng dụng đã chọn hỗ trợ. Các đồ thị điểm tựa quá mức cũng làm cho việc xem xét cấu hình khó khăn hơn vì giá trị hiệu quả không còn rõ ràng ở một nơi.

Thẻ xác định loại hoặc diễn giải của một nút. Các thẻ tiêu chuẩn bao gồm chuỗi, số nguyên, bản đồ, chuỗi và các giá trị cốt lõi khác. Một số thư viện hỗ trợ các thẻ cụ thể cho ứng dụng hình thành các đối tượng ngôn ngữ. Tải các thẻ không đáng tin cậy vào các bộ xây dựng đối tượng có thể nguy hiểm; hãy sử dụng một bộ nạp an toàn giới hạn xây dựng với các loại dữ liệu mong đợi.

Lược đồ YAML và Sự khác biệt phiên bản

Một lược đồ YAML xác định cách văn bản số được chuyển đổi thành thẻ. Sự khác biệt về phiên bản và lược đồ giải thích nhiều ví dụ bất ngờ được tìm thấy trong các kho cấu hình. Một từ được diễn giải như một boolean bởi một chế độ xử lý có thể vẫn là một chuỗi dưới một chế độ khác. Cú pháp số và xử lý dấu thời gian cũng có thể khác nhau.

YAML 1.2 đã căn chỉnh lược đồ JSON của nó để các tài liệu JSON trở thành YAML hợp lệ trong mô hình tương thích dự định. Điều này không có nghĩa là mọi tệp YAML là JSON hợp lệ: các chú thích, khóa không được trích dẫn, các bộ sưu tập khối, điểm tựa, tương đương và thẻ là các tính năng YAML bên ngoài cú pháp JSON.

Cái đặc tả kiểu phương tiện YAML đăng ký application/yaml và +yaml hậu tố cú pháp có cấu trúc. Một phần mở rộng tệp đơn lẻ không chỉ ra lược đồ phân tích cú pháp hoặc hợp đồng ứng dụng. Các dự án nên ghim thư viện phân tích cú pháp, tài liệu phiên bản hoặc tập con YAML được hỗ trợ, và xác thực dữ liệu đã tải vào một lược đồ ứng dụng.

YAML so với JSON

Các trường hợp sử dụng YAML phổ biến

Bảo mật và độ tin cậy của YAML

YAML không đáng tin cậy nên được coi là đầu vào có cấu trúc không đáng tin cậy. Sử dụng chế độ tải an toàn chỉ tạo ra các giá trị dữ liệu bình thường, không phải là đối tượng hoặc lớp ứng dụng cụ thể về ngôn ngữ. Rủi ro chung thuộc về thể loại rộng hơn được mô tả bởi CWE-502: Giải mã dữ liệu không đáng tin cậy.

Đặt giới hạn cho kích thước đầu vào, độ sâu lồng nhau, bí danh và mở rộng tổng hợp. Một tài liệu nhỏ có thể tham chiếu đến các giá trị được neo nhiều lần, khiến bộ tải tạo ra một cấu trúc lớn hơn nhiều trong bộ nhớ. Các thư viện cung cấp các điều khiển khác nhau, vì vậy các bài kiểm tra nên kiểm tra bộ phân tích đã triển khai với các giới hạn đại diện.

Xác thực dữ liệu đã tải sau khi phân tích cú pháp. Loại bỏ các khóa cấp trên không rõ khi các lỗi cấu hình có thể gây nguy hiểm. Kiểm tra các trường bắt buộc, các giá trị enum được phép, phạm vi số, các hạn chế đường dẫn và các mối quan hệ giữa các cài đặt. Đừng ghi lại bí mật hoặc toàn bộ cấu hình khi có lỗi xác thực.

Những sai lầm phổ biến của YAML

• Sử dụng tab để thụt lề. Ưu tiên khoảng trắng và thực thi một chiều rộng thụt lề thông qua các cài đặt biên tập và một định dạng.
• Để lại các số vô hướng không trích dẫn. Trích dẫn các định danh và văn bản giống như boolean, null, số hoặc dấu thời gian.
• Cho phép các khóa trùng lặp. Cấu hình trình tải hoặc kiểm tra để từ chối chúng.
• Giả sử các nhận xét tồn tại qua vòng lặp. Nhiều trình tải dựa trên đối tượng loại bỏ các nhận xét và định dạng gốc.
• Sử dụng quá nhiều các điểm neo và gộp. Tái sử dụng có thể giảm sự lặp lại, nhưng các giá trị hiệu quả ẩn làm cho việc xem xét và ghi đè trở nên khó khăn.
• Bỏ qua xác thực schema. Một tài liệu có cấu trúc tốt vẫn có thể chứa các khóa viết sai hoặc các giá trị không an toàn.

Cách Sử dụng YAML Đúng

1. Định nghĩa một tập hợp con hỗ trợ nhỏ. Quyết định xem dự án có cho phép các điểm neo, khóa gộp, thẻ tùy chỉnh, luồng nhiều tài liệu và kiểu dòng hay không.
2. Ghim phân tích cú pháp và hành vi. Ghi lại thư viện, phiên bản YAML được hỗ trợ, chính sách khóa trùng lặp và chế độ tải an toàn.
3. Thêm kiểm tra linting và schema. Chạy chúng trước khi triển khai để lỗi lùi dòng và các khóa không xác định thất bại sớm.
4. Giữ bí mật ngoài YAML đã cam kết. Tham khảo các giá trị được cung cấp bởi môi trường hoặc trình quản lý bí mật theo cơ chế đã được tài liệu của ứng dụng.
5. Xem xét cấu hình hiệu quả. Khi có sự kế thừa hoặc gộp, cung cấp một lệnh kết xuất các cài đặt cuối cùng mà không tiết lộ các giá trị bí mật.
6. Sử dụng định dạng khác khi ranh giới thay đổi. Ưu tiên JSON cho các API công cộng và định dạng phân tích kiểu cho các tập dữ liệu lớn.

Kết luận

YAML là một ngôn ngữ tuần tự hóa linh hoạt có kiểu khối dễ đọc, làm cho nó đặc biệt hữu ích cho cấu hình. Sự tiện lợi của nó đi kèm với một bề mặt diễn giải lớn hơn: thụt lề, schema, thẻ, điểm neo, bí danh, khóa trùng lặp và tùy chọn phân tích cú pháp đều có thể ảnh hưởng đến các giá trị đã tải. Một quy trình làm việc YAML đáng tin cậy thu hẹp tập hợp các tính năng được hỗ trợ, sử dụng tải an toàn, xác thực dữ liệu kết quả và giữ cấu hình thân thiện với con người tách biệt khỏi trao đổi máy với khối lượng lớn.