Hướng dẫn công cụ

Về Công cụ chuyển JSON sang YAML

Công cụ này chuyển JSON sang YAML và chuyển YAML trở lại JSON, nhờ đó cùng một cấu hình có thể di chuyển giữa một payload API và một manifest Kubernetes, một file Docker Compose, một workflow GitHub Actions hay một tài liệu OpenAPI mà không phải gõ lại.

Việc chuyển đổi chạy ngay khi bạn gõ, thứ tự khóa được giữ nguyên đúng như bạn viết, và mức thụt lề có thể đặt là 2 hoặc 4 khoảng trắng. Lỗi cú pháp sẽ báo chính xác dòng và cột.

Cách chuyển JSON to YAML

Dán JSON của bạn vào ô nhập. Kết quả YAML hiện ra ngay lập tức, không cần bấm nút nào.
Dùng nút đổi chiều để chuyển sang YAML sang JSON, ví dụ để đưa một manifest vào một script chỉ đọc được JSON.
Chọn mức thụt lề 2 hoặc 4 khoảng trắng cho khớp với quy ước của kho mã. File Kubernetes và GitHub Actions thường dùng 2.
Nếu đầu vào không hợp lệ, hãy đọc dòng và cột được báo, sửa đúng chỗ đó, và kết quả sẽ tự làm mới.

Khi nào bạn cần dùng

Biến một tài nguyên JSON do kubectl xuất ra thành một manifest YAML dễ đọc để đưa vào kho mã.
Chuyển đổi một khối dịch vụ của Docker Compose trong lúc thử nghiệm cấu hình được sinh tự động.
Chuyển một đặc tả OpenAPI qua lại giữa dạng JSON và YAML, vì công cụ ở mỗi phía lại ưa một dạng.
Viết lại một đoạn workflow GitHub Actions vốn được sinh ra dưới dạng JSON thành YAML mà trình chạy mong đợi.

Những quy tắc YAML làm hỏng phép chuyển đổi

YAML 1.2 gần như là một tập cha của JSON, nên JSON hợp lệ thường cũng là YAML hợp lệ. Vấn đề xuất hiện ở chiều ngược lại, nơi YAML tự đoán kiểu dữ liệu mà JSON không bao giờ đoán.

Norway problem: NO, no, yes, on và off bị các bộ phân tích YAML 1.1 đọc thành giá trị boolean, nên mã quốc gia NO trở thành false. Hãy đặt các giá trị như vậy trong dấu nháy.
Số 0 ở đầu: một giá trị như 010 có thể bị đọc thành số bát phân thay vì chuỗi. Hãy đặt nháy cho mã định danh, mã bưu chính và mã linh kiện.
Số phiên bản: giá trị 1.10 không có nháy sẽ thành số thực 1.1 và số 0 ở cuối biến mất.
Thụt lề phải dùng khoảng trắng, tuyệt đối không dùng tab, và mọi dấu hai chấm mở đầu một giá trị đều cần một khoảng trắng phía sau.

Câu hỏi thường gặp về JSON sang YAML

Công cụ có sắp xếp lại các khóa của tôi không?: Không. Các khóa đi ra đúng theo thứ tự bạn đưa vào, nhờ đó phần khác biệt trong quản lý phiên bản luôn nhỏ gọn.
Chú thích của tôi thì sao?: JSON không có cú pháp chú thích, nên chiều JSON sang YAML không thể tự tạo ra chú thích, còn chiều YAML sang JSON sẽ bỏ đi những chú thích mà nguồn vốn có. Hãy giữ lại bản gốc nếu chú thích quan trọng.
Kết quả có chứa anchor và alias không?: Không. Các cấu trúc lặp lại được viết đầy đủ ra, nên mọi bộ phân tích đều đọc được kết quả mà không cần hỗ trợ alias.
Cấu hình của tôi có được tải lên đâu không?: Không. Việc phân tích và chuyển đổi diễn ra trong trình duyệt của bạn bằng js-yaml, nên những gì bạn dán không rời khỏi máy và cũng không được wetool.site lưu lại.
Vì sao một giá trị YAML đổi kiểu sau khi chuyển đổi?: YAML tự đoán kiểu cho các giá trị vô hướng không có nháy. Hãy đặt giá trị đó trong dấu nháy ở nguồn YAML và nó sẽ chuyển thành chuỗi JSON.

So sánh JSON với YAML

JSON nghiêm ngặt và không mơ hồ, điều đó khiến nó là một định dạng truyền tải tốt, nhưng nó không có chú thích và trở nên rối rắm khi lồng sâu. YAML dễ đọc hơn khi review, đổi lại là việc tự đoán kiểu và sự nhạy cảm với thụt lề. Phần lớn đội ngũ giữ cấu hình ở dạng YAML và trao đổi JSON ở các ranh giới hệ thống, đó chính là mục đích của phép chuyển đổi hai chiều này.

Danh sách kiểm tra dấu nháy trước khi commit

Phần lớn các lần triển khai hỏng vì chuyển đổi đều bắt nguồn từ một giá trị bị mất kiểu. Hãy rà kết quả YAML để tìm những trường hợp sau.

Mã quốc gia và mã ngôn ngữ, đặc biệt là NO, và mọi giá trị hai chữ cái đọc lên giống một từ.
Những con số thực chất là mã định danh: số tài khoản, số cổng có đệm số 0, và bất cứ giá trị nào bắt đầu bằng số 0.
Số phiên bản và thẻ image như 1.10 hay 3.20, vốn mất số 0 ở cuối khi bị coi là số thực.