Trình Chuyển Đổi JSON Sang YAML

Cách hoạt động

1. Dán JSON: nhập bất kỳ JSON hợp lệ nào, từ cặp khóa-giá trị phẳng đến đối tượng và mảng lồng sâu.
2. Chuyển đổi tức thì: công cụ chuyển JSON thành YAML với thụt lề đúng, loại bỏ dấu nháy khỏi khóa chuỗi và dịch các kiểu null, boolean và số.
3. Cấu hình đầu ra: đặt độ rộng thụt lề (2 hoặc 4 khoảng trắng) và chọn giữa kiểu khối hoặc kiểu luồng cho các tập hợp.
4. Sao chép YAML: kết quả sẵn sàng để dán vào tệp cấu hình, đường ống CI/CD hoặc tệp khai báo Kubernetes.

Tại sao chuyển JSON sang YAML?

YAML là định dạng cấu hình ưa thích cho các công cụ hạ tầng như Kubernetes, Docker Compose, GitHub Actions, Ansible và chart Helm, dễ đọc hơn JSON, hỗ trợ chú thích và không yêu cầu dấu nháy quanh mỗi chuỗi. Chuyển đổi phản hồi API, các phần của package.json hoặc cấu trúc dữ liệu từ JSON sang YAML là nhiệm vụ thường xuyên trong DevOps và phát triển back-end. Cấu trúc dựa trên thụt lề của YAML dễ đọc hơn cho con người, trong khi JSON được ưu tiên cho API và tạo theo chương trình, trình chuyển đổi này làm cầu nối giữa hai định dạng.

Ánh xạ kiểu

• Chuỗi → không có dấu nháy nếu có thể, có dấu nháy nếu chứa ký tự đặc biệt
• Số → giá trị số YAML giữ nguyên
• Boolean → true / false trong YAML
• null → null hoặc ~ trong YAML
• Mảng → chuỗi khối YAML với tiền tố -
• Đối tượng → ánh xạ YAML với các cặp khóa: giá trị

Chuyển đổi JSON sang YAML là gì?

Chuyển đổi JSON sang YAML dịch một cây các cặp khóa-giá trị từ một định dạng tuần tự hóa sang định dạng khác trong khi vẫn duy trì dữ liệu cơ bản. Cả hai định dạng đều mô tả cùng một hình dạng của dữ liệu (chuỗi, số, boolean, null, mảng, đối tượng), nhưng JSON sử dụng dấu ngoặc nhọn và dấu ngoặc vuông trong khi YAML sử dụng thụt lề và dấu gạch ngang. Cùng một cấu hình name: app, version: 1, ports: 80, 443 có thể được biểu thị trong cả hai, và các bộ chuyển đổi di chuyển giữa chúng mà không mất ý nghĩa.

JSON, được Douglas Crockford phát minh khoảng năm 2001 và được tiêu chuẩn hóa thành RFC 4627 vào năm 2006 và ECMA-404 vào năm 2013, là ngôn ngữ chung của các API web. YAML 1.0 (2001), 1.1 (2005) và 1.2 (2009) của Clark Evans, Ingy doet Net, và Oren Ben-Kiki được thiết kế như một superset của JSON được tối ưu hóa cho khả năng đọc của con người, với hỗ trợ cho bình luận, chuỗi nhiều dòng, neo và bí danh. Công cụ DevOps hiện đại (Kubernetes, Docker Compose, GitHub Actions, Ansible, Helm) mặc định là YAML vì các config được con người viết và xem xét.

Bộ chuyển đổi này ghép hai định dạng cạnh nhau. Dán JSON ở bên trái, nhấp JSON sang YAML, và ô bên phải cập nhật với YAML hợp lệ ở độ sâu thụt lề bạn đã chọn (2 hoặc 4 khoảng trắng). Nút ngược thực hiện cùng quá trình ngược lại. Chuyển đổi sử dụng thư viện js-yaml (Vitaly Puzrin, 2011) được tải từ jsDelivr, thực hiện đặc tả YAML 1.2 đủ chính xác để thực hiện chuyển đổi qua lại các manifest Kubernetes, các chart Helm, và các spec OpenAPI.

Bên trong bộ chuyển đổi có gì

Giao diện sử dụng bố cục lưới hai ô: JSON ở bên trái, YAML ở bên phải. Trên các màn hình hẹp hơn 768 pixel, bố cục xếp chồng theo chiều dọc. Phía trên các ô, một bộ chọn thụt lề cho phép bạn chọn 2 hoặc 4 khoảng trắng mỗi cấp độ. Lựa chọn hoạt động được làm nổi bật, và thụt lề áp dụng cho cả hai hướng chuyển đổi.

Mỗi ô có các nút hành động riêng. Ô JSON cung cấp JSON sang YAML (chuyển đổi) và Clear. Ô YAML cung cấp YAML sang JSON (ngược), Copy (clipboard), và Download .yaml (lưu dưới dạng tệp với phần mở rộng .yaml và mã hóa UTF-8). Biểu ngữ lỗi bên dưới bộ chuyển đổi hiển thị các lỗi phân tích cú pháp với số dòng và thông báo ngắn, vì vậy bạn có thể sửa các đầu vào không hợp lệ mà không rời công cụ.

Bên dưới, chuyển đổi JSON sang YAML sử dụng JSON.parse cộng với hàm dump của js-yaml. Hướng YAML sang JSON sử dụng hàm load của js-yaml cộng với JSON.stringify với thụt lề 2 khoảng trắng. Cả hai hướng đều là các hàm thuần túy của đầu vào, không có trạng thái nào được chuyển giữa các chuyển đổi, và làm mới trang đặt lại mọi thứ.

Lịch sử và bối cảnh

Douglas Crockford xác định JSON (2001)

Douglas Crockford đã ghi lại cú pháp JSON vào tháng 4 năm 2001 khi ở State Software, sau khi nhận ra cú pháp đối tượng nguyên văn của JavaScript có thể phục vụ như một định dạng dữ liệu độc lập với ngôn ngữ. Spec cố ý tối thiểu: sáu loại, hai bộ sưu tập, không có bình luận, không có schema. RFC 4627 theo sau vào năm 2006 và ECMA-404 vào năm 2013. Chủ nghĩa tối giản chính xác là điều khiến JSON trở nên phổ biến trên web.

YAML 1.0 được xuất bản (2001)

Clark Evans, Ingy doet Net, và Oren Ben-Kiki phát hành YAML 1.0 vào tháng 5 năm 2001, cùng năm với JSON. Từ viết tắt ban đầu là Yet Another Markup Language nhưng được sửa đổi thành YAML Ain't Markup Language để làm rõ rằng YAML nhắm mục tiêu dữ liệu cấu hình, không phải markup tài liệu. Spec 1.0 tham vọng, hỗ trợ neo, bí danh, luồng đa tài liệu, thẻ tùy chỉnh và bình luận.

YAML 1.1 và vấn đề Na Uy (2005)

YAML 1.1 (tháng 1 năm 2005) thắt chặt spec nhưng giữ hành vi ép buộc boolean nổi tiếng nơi các chuỗi yes, no, on, off, y, n, true, false, cộng với các biến thể viết hoa của chúng, tất cả đều trở thành boolean. Đây là Vấn đề Na Uy: mã quốc gia ISO không trích dẫn NO trở thành boolean false. Lỗi cắn người dùng Kubernetes ban đầu cho đến khi YAML 1.2 (2009) loại bỏ các cách viết boolean thay thế.

YAML 1.2 tuyên bố JSON là một subset (2009)

YAML 1.2 (tháng 10 năm 2009) đã rõ ràng làm cho JSON trở thành một subset nghiêm ngặt của YAML, vì vậy bất kỳ tài liệu JSON hợp lệ nào cũng là một tài liệu YAML hợp lệ. Đây là một thắng lợi thiết kế lớn: các công cụ xử lý YAML 1.2 có thể phân tích cú pháp JSON miễn phí, đơn giản hóa việc triển khai các bộ chuyển đổi và bộ xác thực. Phiên bản vẫn được sử dụng trên hầu hết các công cụ ngày nay là 1.2 hoặc một hồ sơ tương thích với 1.1.

Kubernetes phát hành manifest YAML (2015)

Kubernetes 1.0, được Google phát hành vào tháng 7 năm 2015, đã định nghĩa các tài nguyên cluster (Pod, Deployment, Service) bằng cách sử dụng manifest YAML. Lựa chọn được thúc đẩy bởi khả năng đọc cho các đội ops quen với trình chỉnh sửa văn bản và kiểm soát phiên bản. Helm (2016) thêm templating ở trên, GitHub Actions (2018) áp dụng YAML cho các workflow, và Ansible playbook (2012-2018) củng cố YAML là ngôn ngữ config DevOps thống trị.

js-yaml trở thành thư viện JavaScript thực tế (từ năm 2011)

Vitaly Puzrin xuất bản js-yaml vào năm 2011 dưới dạng port JavaScript thuần túy của PyYAML. Các phiên bản tiếp theo (2.0 vào 2014, 3.0 vào 2015, 4.0 vào 2021) theo dõi spec YAML 1.2, thêm các schema để chọn không tham gia các tính năng nguy hiểm, và đạt hơn 50 triệu lượt tải xuống npm hàng tuần. Thư viện được đóng gói bởi webpack, parcel và esbuild cho bất kỳ công việc YAML phía trình duyệt nào, và đây là điều bộ chuyển đổi này sử dụng bên dưới.

Quy trình thực tế

Viết manifest Kubernetes

Khi bạn tạo Pod hoặc Deployment qua kubectl run --dry-run=client -o json, bạn nhận được JSON. Dán vào đây, nhấp JSON sang YAML, và bạn có một manifest sẵn sàng commit vào git. Chuyển đổi bảo tồn các spec lồng nhau, các biến môi trường, và giới hạn tài nguyên chính xác như Kubernetes sẽ đọc chúng.

Định nghĩa dịch vụ Docker Compose

Một đồng đội gửi cho bạn một đoạn JSON cho một dịch vụ mới. Dán vào, chuyển đổi, và thả YAML vào docker-compose.yml của bạn. Thụt lề 2-khoảng trắng là mặc định Compose, vì vậy hãy để tùy chọn thụt lề ở 2.

Workflow GitHub Actions

Khi bạn tạo scaffold một workflow từ một trình tạo template dựa trên JSON hoặc sao chép một step từ một phản hồi API JSON, dán vào đây và chuyển đổi. Đầu ra trực tiếp đi vào .github/workflows/*.yml. Lưu ý rằng GitHub Actions cũng chấp nhận JSON ở một số trường, nhưng YAML là dạng chuẩn.

Playbook Ansible

Các kho lưu trữ Ansible thường bắt đầu cuộc sống dưới dạng JSON được xuất từ một CMDB hoặc cơ sở dữ liệu tài sản. Dán, chuyển đổi sang YAML, và bạn có một tệp hosts hoặc header playbook phù hợp với phong cách mong đợi của Ansible. Sử dụng thụt lề 2-khoảng trắng để phù hợp với hướng dẫn phong cách cộng đồng Ansible.

Giá trị chart Helm

Một nhà cung cấp gửi các cấu hình mẫu JSON cho chart Helm của họ. Chuyển đổi sang YAML và thả vào values.yaml. Chuyển đổi tôn trọng các khóa lồng nhau (image.repository, image.tag, resources.limits.memory) chính xác như Helm mong đợi chúng.

Spec OpenAPI 3

Swagger Editor xuất các spec OpenAPI dưới dạng cả JSON và YAML. Khi một công cụ phát ra JSON nhưng đội của bạn sử dụng YAML trong kiểm soát phiên bản (hoặc ngược lại), bộ chuyển đổi này là cách nhanh nhất để chuyển định dạng mà không cần khởi động Node, Python, hoặc yq.

Cạm bẫy phổ biến

Vấn đề Na Uy (yes, no, on, off như boolean)

Trong YAML 1.1, các chuỗi yes, no, on, off, y, n, true, false (và các biến thể viết hoa của chúng) đều là boolean. Vì vậy mã quốc gia ISO không trích dẫn NO trở thành boolean false. js-yaml 4.x mặc định là YAML 1.2 chỉ coi true và false là boolean, nhưng các trình phân tích YAML cũ vẫn có thể vấp ngã. Trích dẫn rõ ràng các chuỗi mơ hồ nếu bạn trộn các phiên bản công cụ.

Tab không phải là thụt lề YAML hợp lệ

YAML sử dụng khoảng trắng, không phải tab, cho thụt lề. Nếu trình chỉnh sửa của bạn chèn tab theo mặc định, YAML đã chuyển đổi sẽ thất bại phân tích cú pháp trong Kubernetes, Helm, hoặc bất kỳ trình tải YAML nghiêm ngặt nào. Cấu hình trình chỉnh sửa của bạn để sử dụng 2 hoặc 4 khoảng trắng cho các tệp .yaml và .yml, hoặc chạy một linter (yamllint) trước khi commit.

Neo và bí danh không tồn tại sau chuyển đổi JSON

YAML hỗ trợ neo (&name) và bí danh (*name) để tái sử dụng các giá trị. Khi bạn chuyển đổi YAML sang JSON, các neo được mở rộng nội tuyến vì JSON không có tính năng tương đương. Chuyển đổi JSON sang YAML ngược không tự động giới thiệu lại các neo. Nếu bạn cần neo, hãy viết chúng bằng tay sau khi chuyển đổi.

Chuỗi nhiều dòng cần các chỉ báo rõ ràng

Một chuỗi JSON với các dòng mới được nhúng (Hello\nWorld) chuyển sang YAML bằng cách sử dụng scalar khối nguyên văn (|) hoặc scalar khối gấp lại (>). js-yaml chọn dạng phù hợp, nhưng nếu bạn chỉnh sửa thủ công kết quả, hãy nhớ rằng | bảo tồn dòng mới và > gấp chúng thành khoảng trắng.

Số lớn mất độ chính xác

Các số JavaScript là số dấu chấm động IEEE 754 64-bit, vì vậy các số nguyên vượt quá 2 lũy thừa 53 (khoảng 9 nghìn tỷ) mất độ chính xác khi được phân tích cú pháp bởi JSON.parse. Chuyển đổi sang YAML bảo tồn giá trị bị mất, không phải bản gốc. Nếu dữ liệu của bạn có các định danh kiểu BigInt, mã hóa chúng dưới dạng chuỗi trong JSON trước khi chuyển đổi.

Bình luận bị mất trong YAML sang JSON

YAML hỗ trợ bình luận #, JSON thì không. Khi bạn chuyển đổi YAML với bình luận trở lại JSON, các bình luận bị lột bỏ vì JSON không có cú pháp cho chúng. Nếu bạn thực hiện chuyển đổi qua lại YAML qua JSON để xử lý, hãy mong đợi mất mọi dòng #. Các công cụ như yq hoặc ruamel.yaml có thể bảo tồn các bình luận, nhưng js-yaml tuân thủ spec loại bỏ chúng.

Quyền riêng tư và xử lý dữ liệu

Tất cả việc chuyển đổi chạy trong trình duyệt của bạn thông qua thư viện js-yaml được đóng gói vào trang. Chúng tôi không gửi JSON hoặc YAML của bạn đến máy chủ, không ghi log các đầu vào, và không chạy phân tích trên nội dung chuyển đổi của bạn. Nút Sao chép sử dụng API Clipboard yêu cầu một cử chỉ người dùng, và nút Download .yaml sử dụng URL blob trong bộ nhớ, vì vậy tệp không bao giờ thực hiện chuyển đổi qua lại qua bất kỳ mạng nào.

Sau khi trang được tải (bao gồm tệp CDN js-yaml), công cụ hoạt động ngoại tuyến. Bạn có thể ngắt kết nối khỏi mạng và chuyển đổi cấu hình nhạy cảm (khóa API, URL cơ sở dữ liệu, tên dịch vụ nội bộ) mà không có bất kỳ điều nào rời thiết bị của bạn. Tệp js-yaml được phục vụ từ jsDelivr với hash Subresource Integrity, vì vậy gói không thể bị tráo đổi âm thầm.

Khi không sử dụng bộ chuyển đổi này

Streaming megabyte dữ liệu

Bộ chuyển đổi tải toàn bộ đầu vào vào bộ nhớ, phân tích cú pháp, và phát ra kết quả trong một lần. Đối với các tệp JSON hoặc YAML nhiều megabyte, hãy sử dụng yq hoặc jq trong một pipeline shell, hoặc một bộ phân tích cú pháp streaming trong ngôn ngữ ưa thích của bạn. Trình duyệt không phải là công cụ phù hợp trên 5 đến 10 megabyte.

Dữ liệu nhị phân trong JSON

Nếu JSON của bạn có các blob nhị phân được mã hóa Base64 phải được kiểm tra hoặc sửa đổi, chuyển đổi sang YAML sẽ không giải nén chúng. YAML hỗ trợ binary có tag (!!binary) mà js-yaml xử lý, nhưng các byte vẫn là Base64. Sử dụng một trình chỉnh sửa nhị phân chuyên dụng cho công việc cấp byte thực tế.

Xác thực schema

Bộ chuyển đổi này kiểm tra rằng đầu vào là JSON hoặc YAML hợp lệ, nhưng nó không xác thực chống lại một schema (JSON Schema, OpenAPI, Kubernetes CRD, Helm values). Nếu bạn cần biết liệu một manifest Kubernetes có chính xác về cấu trúc cho một cluster 1.28 hay không, hãy chạy kubectl --dry-run=server hoặc một công cụ như kubeval, kubeconform.

Refactoring nhận biết schema

Nếu bạn cần đổi tên một trường trên hàng trăm tệp YAML, hoặc nâng cấp một phiên bản API (apps/v1beta1 sang apps/v1), hãy sử dụng sed, ast-grep, hoặc yq với các truy vấn đường dẫn rõ ràng. Bộ chuyển đổi chỉ chuyển đổi giữa các định dạng, nó không chỉnh sửa nội dung ngữ nghĩa.

Thêm câu hỏi

JSON có an toàn hơn YAML không?

Để bảo mật, có. yaml.load của PyYAML (trước 5.1) và các trình phân tích cú pháp dễ dãi tương tự có thể thực thi mã tùy ý từ các đầu vào YAML không đáng tin cậy thông qua các đối tượng Python có tag. JSON không có tính năng như vậy, mọi trình phân tích cú pháp JSON đều an toàn theo thiết kế. Các trình phân tích cú pháp YAML hiện đại (PyYAML 5.1+, js-yaml kể từ 4.0) mặc định là safe-load, vì vậy khoảng cách đã thu hẹp, nhưng JSON vẫn là mặc định an toàn hơn cho đầu vào không đáng tin cậy.

Tại sao YAML chọn thụt lề thay vì dấu ngoặc?

Các tác giả YAML muốn các config đọc giống như các đại cương, vì vậy họ đã sử dụng cùng quy ước với khoảng trắng có ý nghĩa của Python. Dấu ngoặc nhọn và dấu ngoặc vuông là YAML hợp lệ (phong cách flow), nhưng phong cách block với thụt lề là mặc định vì nó quét tự nhiên hơn cho con người chỉnh sửa trong văn bản thuần. Trade-off là khoảng trắng trở nên có ý nghĩa, điều này bắt các trình chỉnh sửa tự động cắt các khoảng trắng cuối.

YAML có luôn là một superset nghiêm ngặt của JSON không?

Kể từ YAML 1.2 (2009), có. Bất kỳ tài liệu JSON hợp lệ nào cũng là tài liệu YAML 1.2 hợp lệ. YAML 1.1 có một vài trường hợp đặc biệt (các số sexagesimal, vấn đề Na Uy) nơi mối quan hệ lỏng lẻo hơn. js-yaml hiện đại sử dụng 1.2 theo mặc định, vì vậy thuộc tính superset đúng cho công cụ này.

Tại sao YAML Kubernetes lại dài dòng như vậy?

Các manifest Kubernetes có một hình dạng top-level cố định (apiVersion, kind, metadata, spec) và spec chứa các đối tượng lồng nhau phản ánh các struct Go nội bộ của API. Tính chi tiết là một tác dụng phụ của việc ánh xạ một API hướng đối tượng sang một định dạng văn bản phẳng. Các công cụ như Kustomize, Helm, và Pulumi giảm tính chi tiết, nhưng YAML cơ bản là những gì kubectl thực sự gửi đến cluster.

Tôi có thể thực hiện chuyển đổi qua lại JSON qua YAML mà không mất dữ liệu không?

Đối với hầu hết JSON, có. Chuỗi, số, boolean, null, mảng, đối tượng đều tồn tại. Các trường hợp đặc biệt bao gồm các số nguyên rất lớn (mất độ chính xác), các cặp surrogate Unicode (phụ thuộc vào trình phân tích cú pháp), và thứ tự khóa (YAML có thể sắp xếp lại). Nếu các khóa JSON của bạn phải giữ thứ tự ban đầu, hãy sử dụng một công cụ tôn trọng thứ tự chèn (OrderedDict của Python, json-stable-stringify trong JavaScript).

Còn TOML và HCL thì sao?

TOML (Tom's Obvious Minimal Language, 2013 bởi Tom Preston-Werner) được sử dụng bởi Cargo (Rust), pyproject.toml (Python), và các công cụ khác. HCL (HashiCorp Configuration Language, 2014) được sử dụng bởi Terraform. Cả hai đều nhắm đến trường hợp sử dụng cấu hình nhưng sử dụng cú pháp khác nhau. Bộ chuyển đổi này chỉ xử lý JSON và YAML. Đối với TOML hoặc HCL, hãy sử dụng các bộ chuyển đổi chuyên dụng hoặc yq với plugin phù hợp.