Công cụ dành cho nhà phát triển · Trình chuyển đổi cú pháp
Cách chuyển đổi JSON sang YAML hoạt động: trích dẫn, thụt lề và kiểu luồng
· Cách thức hoạt động
json yaml developer-workflow
JSON đến YAML trông giống như việc xóa dấu ngoặc nhọn, nhưng trình chuyển đổi sẽ đưa ra quyết định thực sự về chuỗi nào cần dấu ngoặc kép và khi nào nên sử dụng kiểu khối so với kiểu luồng. Bài đăng này đi qua những quyết định đó.
Dấu ngoặc nhọn biến mất, nhưng dấu ngoặc kép sẽ đi đâu? — tải trọng JSON được chuyển đổi thành YAML và kết quả là hỗn hợp các chuỗi được trích dẫn và chuỗi trần
Việc xóa dấu ngoặc nhọn và dấu ngoặc kép không biến đối tượng JSON thành tệp YAML đáng tin cậy. Trình chuyển đổi phải quyết định cách trình bày ánh xạ lồng nhau, mảng, chuỗi và dòng mới và liệu một giá trị trông giống như số hay Boolean có giữ nguyên văn bản hay không. Kỹ sư DevOps chuyển định nghĩa dịch vụ API sang Compose cần có thể dự đoán được những quyết định đó trước khi sao chép kết quả vào thư mục triển khai. Cú pháp chuyển đổi thay đổi chứ không phải cấu hình thực tế của dịch vụ.
JSON đã (gần như) YAML — tại sao dữ liệu đầu vào hợp lệ YAML 1.2 kiểu luồng trước khi quá trình chuyển đổi bắt đầu
YAML 1.2 coi cú pháp JSON là tập hợp con kiểu luồng được phép cho dữ liệu có hình dạng JSON thông thường, điều này giải thích tại sao đối tượng JSON đã gần với YAML. Tuy nhiên, một chuyển đổi hữu ích thường chuyển sang thụt lề kiểu khối mà con người có thể đọc được. Đầu vào được phân tích cú pháp dưới dạng JSON trước tiên; các lệnh shell tùy ý không bao giờ được thực thi. ToolAcre tải YAML thông qua một lược đồ bị hạn chế trên đường dẫn ngược, từ chối các thẻ không an toàn và mở rộng bí danh giới hạn, do đó, không thể sử dụng trình chuyển đổi để khởi tạo các đối tượng tùy ý từ thẻ !!js/function không đáng tin cậy.
Kiểu khối so với kiểu luồng — cách trình chuyển đổi chọn các ánh xạ và trình tự dựa trên thụt lề trên dấu ngoặc nhọn và dấu ngoặc nhọn cũng như ý nghĩa của độ sâu thụt lề
Kiểu khối sử dụng các cặp khóa/value thụt lề và dòng bắt đầu bằng dấu gạch ngang cho các mục trong mảng: chuỗi hình ảnh bên dưới services.web được thụt lề bên dưới web, trong khi các cổng trở thành một chuỗi. Kiểu luồng giữ các dấu ngoặc và dấu ngoặc nhọn giống JSON. ToolAcre sử dụng kết xuất js-yaml với thụt lề hai dấu cách theo mặc định, không có tham chiếu và cài đặt độ rộng dòng không giới hạn, thay vì chỉ thay thế dấu câu bằng biểu thức chính quy. Việc thay đổi độ rộng thụt lề sẽ ảnh hưởng đến khả năng đọc chứ không ảnh hưởng đến các phím hoặc thứ tự mảng thực tế.
Những chuỗi nào phải được giữ nguyên trong dấu ngoặc kép - các giá trị lẽ ra sẽ trở thành giá trị boolean, số, null hoặc ngày tháng và các chuỗi có dấu hai chấm, dấu băm hoặc dấu cách ở đầu
Một số chuỗi phải được trích dẫn để tồn tại trong một trình phân tích cú pháp khác: "false" phải giữ nguyên là văn bản thay vì Boolean false, "2026-09-28" không được âm thầm trở thành một ngày trong đối tượng tiêu dùng YAML 1.1 và dấu hai chấm theo sau là dấu cách có thể bị nhầm lẫn với cú pháp ánh xạ. Trình kết xuất của ToolAcre chọn các trích dẫn bảo vệ, bao gồm các lựa chọn về khả năng tương thích dành cho độc giả YAML cũ hơn. Việc trích dẫn một tham chiếu hình ảnh thông thường bằng dấu hai chấm không phải lúc nào cũng được yêu cầu và việc loại bỏ một cách vô cớ các trích dẫn hiện có có thể làm hỏng một chuyến đi khứ hồi. Xác minh các loại cũng như hình thức trực quan.
Chuỗi nhiều dòng - cách một dòng mới bên trong chuỗi JSON có thể trở thành khối vô hướng bằng chữ (|) hoặc gấp (>)
Chuỗi JSON chứa dòng mới thực tế có thể được hiển thị dưới dạng khối vô hướng YAML với |. Biểu mẫu |- loại bỏ dòng mới cuối cùng, trong khi | bảo tồn nó; > sẽ gấp một số ngắt dòng thành dấu cách. Những chỉ báo đó mô tả dữ liệu chứ không phải cách trang trí định dạng. Trình kết xuất của ToolAcre chọn một biểu diễn có thể đọc lại chuỗi gốc thay vì luôn ép buộc một kiểu. Sau khi chuyển đổi, hãy kiểm tra cẩn thận giá trị hoặc chứng chỉ môi trường nhiều dòng: lỗi thụt lề ở đây có thể thay đổi những gì ứng dụng nhận được.
Ví dụ đã thực hiện: chuyển đổi định nghĩa dịch vụ — một đối tượng JSON lồng nhau thành YAML, với mỗi trích dẫn và quyết định kiểu được chú thích
Đối với đối tượng JSON cụ thể, hãy sử dụng services.web với hình ảnh "example/web:1", cổng ["8080:80"] và các khóa môi trường DEBUG="false", RELEASE="2026-09-28" và MESSAGE="line one\nline hai". ToolAcre phát ra hình ảnh: example/web:1 và danh sách cổng; DEBUG được trích dẫn là 'false', RELEASE được trích dẫn là '2026-09-28' và MESSAGE sử dụng khối |- có hai dòng thụt vào. Mỗi lựa chọn đều bảo vệ các loại ban đầu. Chạy kiểm tra khứ hồi của bảng điều khiển trước khi lưu dưới dạng compose.yaml; trình chuyển đổi không thể biết liệu hình ảnh có tồn tại hay dịch vụ sẽ bắt đầu.
Điều này không bao gồm những gì - thêm nhận xét, liên kết hoặc thứ tự khóa tùy chỉnh, không cái nào trong số đó tồn tại trong nguồn JSON để được chuyển tiếp
JSON không có nhận xét, liên kết hoặc bí danh nào cần giữ lại: trình chuyển đổi không thể khôi phục chúng từ đầu vào không bao giờ chứa chúng. Nó cũng không thể suy ra khả năng quản lý bí mật dành riêng cho Compose, thứ tự khóa tùy chỉnh hoặc tính hợp lệ của phiên bản Kubernetes API. Hai tệp YAML có thể tuần tự hóa cùng một dữ liệu nhưng sử dụng các kiểu trích dẫn và khoảng trắng khác nhau. Xem lại kết quả trong chương trình mục tiêu và tránh dán mã thông báo API thực vào các dịch vụ chuyển đổi bên ngoài.
Bài học rút ra: chuyển đổi là quá trình tuần tự hóa lại với các quy tắc — và cách bảng điều khiển Trình chuyển đổi cú pháp tạo ra YAML trong trình duyệt của bạn
Chuyển đổi là phân tích cú pháp và tuần tự hóa lại theo một bộ quy tắc, không phải xóa dấu câu. Bộ chuyển đổi cú pháp thực hiện các thao tác đó trong trình duyệt của bạn; kiểm tra cục bộ một cấu hình nhạy cảm và chạy một vòng trên một đối tượng thử nghiệm nhỏ trước khi áp dụng phương pháp này cho một tệp lớn hơn. Nếu giá trị được trích dẫn thay đổi loại trên đường quay lại, định dạng không chỉ mang tính thẩm mỹ và cần được điều tra.