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 tệp dòng JSON không xác thực được ở dòng 2, cột 1
· Cách thức hoạt động
json developer-workflow xác nhận
Tệp .jsonl chứa nhiều tài liệu JSON chứ không phải một tài liệu, vì vậy trình xác thực nghiêm ngặt sẽ dừng chính xác ở vị trí bắt đầu của tài liệu thứ hai. Bài đăng này giải thích các quy ước JSON Dòng và NDJSON cũng như cách xác thực chúng từng bản ghi một.
Hợp lệ trên mọi dòng, không hợp lệ dưới dạng tệp
Hợp lệ trên mọi dòng, không hợp lệ dưới dạng tệp - bản xuất mà mọi công cụ xuôi dòng đều đọc vui vẻ nhưng trình xác thực sẽ từ chối ở dòng thứ hai. Người gửi nhật ký có thể sử dụng từng dòng mới làm ranh giới bản ghi, tuy nhiên trình phân tích cú pháp JSON nghiêm ngặt sẽ xem toàn bộ tệp là một đầu vào. Đối tượng đầu tiên đã hoàn thành JSON; dấu ngoặc nhọn mở tiếp theo là giá trị gốc thứ hai không hợp lệ.
ToolAcre xác thực một văn bản JSON chứ không phải dòng JSON. Sau khi máy quét hoàn thành giá trị gốc đầu tiên, mọi ký tự không phải khoảng trắng sau này sẽ được báo cáo là không mong muốn sau khi kết thúc giá trị JSON. Nó không cung cấp xác thực hoặc chuyển đổi NDJSON trên mỗi dòng dưới dạng dự phòng ẩn. Sự khác biệt đó ngăn kết quả màu xanh lá cây ngụ ý rằng mọi bản ghi trong luồng định hướng dòng đều đã được kiểm tra.
Một văn bản, một giá trị — những gì RFC 8259 định nghĩa là văn bản JSON và tại sao hai giá trị cấp cao nhất liên tiếp lại là lỗi ngữ pháp
Một văn bản, một giá trị — những gì RFC 8259 định nghĩa là văn bản JSON và tại sao hai giá trị cấp cao nhất liên tiếp lại là lỗi ngữ pháp. Văn bản JSON là một giá trị được tuần tự hóa, do đó, một đối tượng, mảng, chuỗi, số, boolean hoặc null có thể đứng ở gốc. Khoảng trắng có thể bao quanh giá trị đó, nhưng nó không thể tách nhiều gốc thành một tài liệu hợp lệ lớn hơn.
Ví dụ: `{"ok":true} {"ok":false}` chứa hai đối tượng hợp lệ riêng lẻ nhưng không phải là một văn bản JSON. Phân tích cú pháp đối tượng đầu tiên tiêu thụ một giá trị hoàn chỉnh; sau đó phân tích toàn bộ chuỗi phải từ chối `{` thứ hai. Để biểu thị cả hai giá trị trong JSON thông thường, hãy đặt chúng bên trong một mảng và thêm dấu phẩy bắt buộc giữa các thành phần mảng.
JSON Đường và NDJSON
JSON Dòng và NDJSON — các quy ước được phân tách bằng dòng mới, lý do chúng tồn tại để phát trực tuyến và nhật ký cũng như chúng khác với mảng JSON như thế nào. Mỗi dòng vật lý mang một giá trị JSON hoàn chỉnh, thường là một đối tượng và dòng mới đóng vai trò đóng khung bên ngoài ngữ pháp JSON. Nhà sản xuất có thể nối thêm các bản ghi và người tiêu dùng có thể xử lý chúng dần dần mà không cần tải toàn bộ bộ sưu tập.
Thay vào đó, một mảng có một dấu ngoặc mở, các phần tử được phân tách bằng dấu phẩy và một dấu ngoặc đóng, làm cho toàn bộ tệp có một giá trị JSON duy nhất. Điều này thuận tiện cho các API trả về một bộ sưu tập giới hạn nhưng lại bất tiện đối với luồng sự kiện phát triển vô tận. Tệp dòng JSON bị cắt ngắn có thể giữ lại tất cả các bản ghi hoàn chỉnh trước đó; một mảng bị cắt bớt thường để lại giá trị kèm theo chưa hoàn thành.
Tại sao lỗi luôn ở dòng 2, cột 1
Tại sao lỗi luôn ở dòng 2, cột 1 — trình phân tích cú pháp hoàn thành giá trị đầu tiên, dự kiến kết thúc dữ liệu nhập và đáp ứng ký tự đầu tiên của bản ghi thứ hai. Bản thân dòng mới là khoảng trắng ở cuối hợp pháp, vì vậy nó không gây ra lỗi. Dấu ngoặc mở của bản ghi tiếp theo là mã thông báo đầu tiên mâu thuẫn với trạng thái tài liệu đã hoàn thành.
Vị trí đó là bằng chứng chẩn đoán chứ không phải là tuyên bố rằng đối tượng thứ hai không đúng định dạng. Nếu báo cáo liên tục trỏ đến ký tự không phải khoảng trắng đầu tiên sau gốc hợp lệ, hãy kiểm tra hình dạng tệp trước khi chỉnh sửa dấu câu. Xóa dấu ngoặc nhọn sẽ làm hỏng bản ghi; việc chọn một trình đọc nhận biết dòng hoặc chuyển đổi các bản ghi thành một mảng sẽ giải quyết vấn đề khung hình thực tế không khớp.
Ví dụ đã hoạt động: xác thực ba bản ghi nhật ký
Ví dụ hoạt động: xác thực ba bản ghi nhật ký - tự kiểm tra từng dòng thay vì gói chúng trong một mảng bằng dấu phẩy. Giả sử các dòng chứa `{"level":"info"}`, `{"level":"warn"}` và `{"level":"error"}`. Trình xác thực định hướng dòng phân tích ba đầu vào riêng biệt và có thể xác định bản ghi chính xác nếu bản ghi bị thiếu dấu ngoặc kép hoặc dấu phẩy ở cuối.
Để kiểm tra toàn bộ tài liệu một cách nghiêm ngặt, hãy chuyển đổi mẫu thành `[{"level":"info"},{"level":"warn"},{"level":"error"}]`. Dấu ngoặc thiết lập một gốc và dấu phẩy phân cách các phần tử của nó. Không chỉ thay thế dòng mới bằng dấu phẩy: điều đó tạo ra ba gốc được phân tách bằng dấu chấm câu trừ khi mảng xung quanh được thêm vào và nó có thể xử lý sai các dòng trống mà quy ước nguồn có thể cấm hoặc bỏ qua.
Chuyển đổi giữa hai hình dạng
Chuyển đổi giữa hai hình dạng — khi nào mảng bao bọc phù hợp và khi nào mảng bao bọc sẽ không đạt được điểm đầu ra được phân cách bằng dòng. Việc xuất hữu hạn dành cho yêu cầu API, trình chỉnh sửa hoặc trình xác thực nghiêm ngặt thường có thể trở thành một mảng. Việc chuyển đổi phải phân tích cú pháp mọi bản ghi trước tiên vì phép nối văn bản không thể giải thích một cách an toàn các ký tự thoát được nhúng hoặc các dòng không hợp lệ.
Giữ JSON dòng khi bản ghi đến liên tục, tệp được nối thêm hoặc người dùng cần bộ nhớ giới hạn và khôi phục ở cấp bản ghi. Việc chuyển đổi luồng sự kiện nhiều gigabyte thành một mảng yêu cầu giữ lại trạng thái vùng chứa và trì hoãn quá trình phân tích cú pháp hoàn chỉnh cho đến khi dấu ngoặc đóng xuất hiện. Theo hướng khác, tuần tự hóa từng phần tử mảng một cách gọn gàng trên một dòng và xác định xem các dòng trống hay dòng mới cuối cùng có được phép hay khô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 nối JSON không có dòng mới và khung phân tách bản ghi (RFC 7464), cần có trình phân tích cú pháp chuyên dụng. Các giá trị được đặt trực tiếp với nhau không thể được phân chia một cách an toàn bằng thao tác dòng đơn giản, đặc biệt khi các gốc có thể là số hoặc chuỗi. RFC 7464 sử dụng ký tự phân tách bản ghi ASCII để đóng khung các chuỗi văn bản JSON thay vì chỉ dựa vào các dòng mới hiển thị.
Nó cũng không xác nhận các quy tắc ứng dụng được chia sẻ bởi các bản ghi. Phân tích cú pháp mọi dòng không thể chứng minh dấu thời gian được sắp xếp theo thứ tự, số nhận dạng là duy nhất hoặc tất cả các đối tượng sử dụng cùng một lược đồ. Những kiểm tra đó thuộc về việc đóng khung bản ghi và phân tích cú pháp. Tương tự như vậy, một dòng mới được nhúng dưới dạng chuỗi thoát ` ` bên trong một chuỗi là dữ liệu, không phải ranh giới vật lý và trình đọc dòng tuân thủ phải duy trì sự phân biệt đó.
Takeaway: biết bạn đang cầm hình dạng nào
Bài học rút ra: biết bạn đang giữ hình dạng nào — và cách vị trí của trình xác thực cho bạn biết ngay lập tức rằng tệp được phân cách bằng dòng. Lỗi ở mã thông báo đầu tiên của dòng thứ hai sau giá trị dòng một hoàn chỉnh cho biết rõ ràng rằng có nhiều bản ghi được đóng khung chứ không phải cú pháp bị hỏng trong bản ghi đầu tiên. Kiểm tra tiện ích mở rộng, tài liệu của nhà sản xuất và người tiêu dùng dự kiến trước khi thay đổi dữ liệu.
Sử dụng trình phân tích cú pháp JSON Dòng hoặc NDJSON để xác thực các bản ghi một cách độc lập khi dòng mới là có chủ ý. Sử dụng mảng khi đích yêu cầu một bộ sưu tập JSON hoàn chỉnh. ToolAcre từ chối chính xác tệp nhiều gốc vì hợp đồng của nó là xác thực văn bản đơn nghiêm ngặt; sự từ chối bảo vệ hợp đồng đó thay vì cho thấy rằng JSON được phân tách bằng dòng mới vốn đã bị lỗi. Khớp trình xác thực với định dạng khung.