Công cụ dành cho nhà phát triển · JSON trình định dạng và xác thực
Tại sao JSON không có nhận xét nào: quyết định thiết kế và cách giải quyết
· Lý lịch
json tiêu chuẩn xác nhận
Nhận xét đã bị xóa khỏi JSON một cách có chủ ý. Bài đăng này giải thích lý do, tại sao mọi nỗ lực thêm lại chúng đều tạo ra một định dạng mới và các tùy chọn của bạn là gì khi tệp cấu hình thực sự cần ghi chú.
Nhận xét đã phá vỡ bản dựng
Nhận xét đã phá vỡ bản dựng — một ghi chú hữu ích được thêm vào cấu hình JSON và trình phân tích cú pháp dừng ở dấu gạch chéo đầu tiên. Tác giả có thể đã sao chép mẫu từ JavaScript hoặc trình chỉnh sửa nhận biết JSONC, trong khi công cụ triển khai sử dụng JSON nghiêm ngặt. Làm nổi bật cú pháp có thể làm cho ghi chú trông có vẻ hợp lệ ngay cả khi người dùng từ chối điểm đánh dấu nhận xét đầu tiên.
Nhận xét bị từ chối vì dấu gạch chéo không phải là mã thông báo JSON mà máy quét mong đợi một giá trị hoặc thành viên. ToolAcre không âm thầm loại bỏ cú pháp JSONC hoặc JSON5. Thuộc tính hình nhận xét thông thường là dữ liệu thông thường và có thể vi phạm lược đồ ứng dụng ngay cả khi cú pháp JSON nghiêm ngặt chấp nhận nó. Các tuyên bố lịch sử không được chứng minh về thiết kế của JSON bị bỏ qua hoặc sửa chữa thay vì được trình bày dưới dạng dữ kiện đã được chứng minh mà không có bằng chứng chính hoặc nguồn tiêu chuẩn có thể truy nguyên để xác minh.
Lý do Crockford xóa bình luận
Lý do xóa nhận xét của Crockford - lời giải thích sau đó cho biết nhận xét đã được sử dụng để thực hiện các chỉ thị phân tích cú pháp, làm suy yếu khả năng tương tác giữa các quá trình triển khai. Hậu quả của thiết kế có liên quan là tiêu chuẩn JSON không có mã thông báo nhận xét. Các tuyên bố về động cơ riêng tư, trình tự thời gian chính xác hoặc phản hồi toàn cầu của ngành yêu cầu các nguồn lịch sử không được kho lưu trữ này cung cấp.
Theo đó, những tuyên bố lịch sử không được hỗ trợ sẽ bị bỏ qua hoặc sửa chữa ở đây. Tiêu chuẩn có thể quan sát và hành vi của trình phân tích cú pháp là đủ: JSON nghiêm ngặt trao đổi dữ liệu thông qua sáu loại giá trị và hai vùng chứa mà không cần kênh chú thích. Ràng buộc đó ngăn không cho người nhận gán ý nghĩa thao tác cho văn bản mà người nhận khác bỏ qua, nhưng nó cũng khiến JSON trở nên kém thoải mái hơn đối với cấu hình được duy trì bằng tay.
Trình xác thực báo cáo gì về một nhận xét
Nội dung mà trình xác thực báo cáo về một nhận xét — `//` và `/* */` không có trong ngữ pháp, do đó lỗi xảy ra ở dấu gạch chéo đầu tiên có một dòng và cột. Máy quét không phản đối các từ trong ghi chú. Nó không thể bắt đầu bất kỳ giá trị JSON hợp lệ nào, tên thành viên hoặc dấu phân cách bằng `/` tại vị trí đó.
Đối với `{"port":8080, // local only "secure":false}`, dấu phẩy hợp lệ và mã thông báo hợp pháp tiếp theo phải là tên thuộc tính được trích dẫn hoặc dấu ngoặc nhọn đóng. Dấu gạch chéo vi phạm sự mong đợi đó. Chỉ xóa ghi chú để lại dấu phân cách hợp lệ và thành viên tiếp theo; xóa dấu câu gần đó có thể tạo ra lỗi thứ hai. Xác nhận lại đầu ra nghiêm ngặt chính xác sau mỗi lần chỉnh sửa.
Các định dạng đã thêm nhận xét trở lại
Các định dạng đã thêm lại nhận xét — JSONC cho phép nhận xét xung quanh cú pháp JSON quen thuộc, trong khi JSON5 thêm các tiện ích như khóa định danh không có dấu ngoặc kép và dấu phẩy ở cuối. Hjson nhấn mạnh việc chỉnh sửa của con người bằng cú pháp bổ sung thoải mái. YAML có ngữ pháp riêng, bao gồm cả nhận xét và không chỉ đơn thuần là JSON có thêm chú thích.
Việc chấp nhận tùy thuộc vào người tiêu dùng: cài đặt trình chỉnh sửa và cấu hình TypeScript có thể sử dụng trình phân tích cú pháp cho phép nhận xét, trong khi tệp kê khai gói hoặc nội dung API có thể yêu cầu JSON nghiêm ngặt. Kubernetes thường tiêu thụ YAML hoặc JSON tùy theo công cụ của nó. Đặt tên cho định dạng thực tế trong việc xử lý tài liệu và tệp; việc loại bỏ các tiện ích mở rộng hoặc gọi mọi ký hiệu đối tượng là “JSON” sẽ ẩn các ranh giới tương thích.
Cách giải quyết bên trong nghiêm ngặt JSON
Cách giải quyết bên trong JSON nghiêm ngặt — khóa `_comment` hoặc `//` thông thường lưu trữ lời giải thích như một thành viên chuỗi thông thường. Nó tồn tại trong quá trình phân tích cú pháp nghiêm ngặt vì cả khóa và giá trị đều sử dụng mã thông báo tiêu chuẩn. Nhiều ghi chú cần có khóa duy nhất hoặc một mảng vì tên thành viên trùng lặp không đáng tin cậy và có thể bị trình phân tích cú pháp thu gọn.
Giải pháp thay đổi mô hình dữ liệu. Lược đồ có `additionalProperties: false` có thể từ chối chú thích và ứng dụng có thể tồn tại hoặc truyền chú thích đó dưới dạng cấu hình thực. Tài liệu bên ngoài, README lân cận hoặc lược đồ `description` thường cung cấp kênh giải thích an toàn hơn. Chỉ sử dụng các thành viên có hình nhận xét khi mọi người tiêu dùng cho phép rõ ràng và bỏ qua chúng.
Ví dụ đã hoạt động: tệp cài đặt có chú thích
Ví dụ đã hoạt động: tệp cài đặt có chú thích — bắt đầu bằng nguồn JSONC chứa `// seconds before retry` ở trên `"timeout":30`. Nếu đích chỉ chấp nhận JSON, hãy sử dụng trình phân tích cú pháp hiểu JSONC để tạo dữ liệu rồi tuần tự hóa dữ liệu đó ở mức nghiêm ngặt JSON. Cấu phần phần mềm được triển khai trở thành `{"timeout":30}` trong khi nguồn được duy trì vẫn giữ nguyên phần giải thích.
Không xóa nhận xét bằng biểu thức chính quy. Chuỗi dấu gạch chéo có thể xuất hiện hợp pháp bên trong các chuỗi chẳng hạn như URL và các mẫu nhận xét khối có thể kéo dài các dòng theo cách xử lý sai thay thế văn bản. Giữ cho nguồn và tạo phẩm được tạo riêng biệt, xác thực kết quả nghiêm ngặt và sắp xếp quá trình tái tạo trong bản dựng. Điều này bảo tồn các ghi chú của tác giả mà không giả vờ rằng trình phân tích cú pháp nhận hỗ trợ chúng.
Điều này không bao gồm những gì
Điều này không bao gồm những gì - cách định cấu hình các trình phân tích cú pháp riêng lẻ để chấp nhận nhận xét, dành riêng cho từng công cụ và thay đổi thường xuyên. Tùy chọn cho phép trong một thư viện không làm thay đổi ngữ pháp JSON hoặc đảm bảo rằng dịch vụ khác sẽ chấp nhận cùng một văn bản. Kiểm tra trình phân tích cú pháp, phiên bản và đích thay vì dựa vào màn hình của trình soạn thảo.
Bài viết này cũng tránh những tuyên bố không được hỗ trợ về thời điểm chính xác các nhận xét bị xóa, ai áp dụng từng cách giải quyết trước hoặc liệu chỉ một quyết định thiết kế có gây ra sự phổ biến của JSON hay không. Những khẳng định mang tính lịch sử như vậy cần có những nguồn sơ cấp độc lập. Ở đây chúng được bỏ qua hoặc sửa chữa; kết luận được hỗ trợ được giới hạn ở cú pháp nghiêm ngặt hiện tại, hành vi của kho lưu trữ và sự khác biệt về hoạt động giữa các định dạng được đặt tên.
Bài học rút ra: JSON là định dạng trao đổi dữ liệu, không phải ngôn ngữ cấu hình
Bài học rút ra: JSON là định dạng trao đổi dữ liệu, không phải ngôn ngữ cấu hình có nhiều nhận xét — và trình xác thực hiển thị chính xác vị trí ghi chú vi phạm ngữ pháp nghiêm ngặt. Khi con người cần chú thích, hãy chọn định dạng mà công cụ sử dụng chính thức hỗ trợ hoặc duy trì nguồn có chú thích để tạo ra một tạo phẩm nghiêm ngặt riêng biệt. Đừng cho rằng bình luận sẽ bị bỏ qua một cách vô hại.
Nếu bắt buộc phải có JSON nghiêm ngặt, hãy chuyển phần giải thích sang tài liệu hoặc sử dụng siêu dữ liệu được lược đồ phê duyệt, sau đó xác thực tài liệu cuối cùng. ToolAcre cố tình báo cáo dấu gạch chéo đầu tiên thay vì âm thầm xóa tài liệu vì chuyển đổi im lặng có thể thay đổi chuỗi hoặc che giấu định dạng không khớp. Bối cảnh lịch sử phải được giữ nguyên theo nguyên tắc như nhau: những tuyên bố không được hỗ trợ sẽ được bỏ qua hoặc sửa chữa, trong khi cú pháp có thể quan sát được và hành vi của trình phân tích cú pháp sẽ đưa ra kết luận.