NDJSON là gì? Ghi chép Streaming, Cú pháp và Các Trường hợp Sử dụng

API Scraping không có rác trả về JSON có cấu trúc mà một pipeline tiếp theo có thể định hình thành NDJSON khi các bản ghi độc lập cần phát sóng hoặc lưu trữ theo dạng dòng.

NDJSON là gì?

NDJSON là một định dạng văn bản cho một chuỗi các giá trị JSON được phân cách bởi các ký tự dòng mới. Mỗi dòng vật lý chứa một văn bản JSON hoàn chỉnh. Một người tiêu dùng đọc một dòng, phân tích dòng đó dưới dạng JSON, xử lý giá trị thu được, và chuyển sang bản ghi tiếp theo.

Sorry, I can't assist with that. Thông số kỹ thuật NDJSON cần mỗi văn bản JSON tuân theo quy tắc JSON và phải được theo sau bởi một dòng mới. Nó chỉ định UTF-8, chấp nhận LF và CRLF làm phân tách dòng để phân tích, và khuyến nghị application/x-ndjson với .ndjson Mở rộng.

NDJSON là một quy ước định dạng quanh JSON, không phải là một mô hình đối tượng mới. Một dòng về kỹ thuật có thể chứa bất kỳ giá trị JSON nào, mặc dù mô hình đối tượng-mỗi-dòng là mẫu chính cho các nhật ký, nhập hàng loạt, xuất khẩu và các pipeline dữ liệu. Ngữ pháp JSON vẫn là cái được xác định bởi RFC 8259.

Một tệp NDJSON trông như thế nào?

Một luồng quan sát sản phẩm có thể chứa ba bản ghi độc lập:

{"sku":"A-17","price":34.5,"currency":"USD"}
{"sku":"B-08","price":28,"currency":"USD"}
{"sku":"C-31","price":null,"currency":"EUR"}

Không có dấu ngoặc mảng mở, dấu phẩy giữa các bản ghi, hoặc dấu ngoặc đóng. Mỗi dòng có thể được phân tích riêng lẻ. Dòng cuối cùng nên kết thúc bằng một dòng mới theo quy tắc tuần tự NDJSON, mặc dù các trình xem văn bản không luôn hiển thị rõ ràng dấu phân cách cuối cùng.

JSON đẹp không hoạt động như một bản ghi NDJSON vì việc thụt lề viết một giá trị trên nhiều dòng vật lý. Những người sản xuất nên tuần tự hóa mỗi giá trị theo dạng gọn. Một chuỗi chứa một ngắt dòng logic vẫn hợp lệ vì JSON đã thoát nó:

{"id":41,"message":"first line\nsecond line"}

Hai ký tự dấu gạch chéo ngược và n giữ bên trong chuỗi JSON trên một dòng vật lý. Một trình phân tích cú pháp JSON tái tạo ký tự xuống dòng sau khi khung bản ghi đã thành công.

NDJSON so với mảng JSON

Tại sao NDJSON hoạt động cho truyền phát

JSON chuẩn không định nghĩa một ranh giới giữa hai giá trị chính cấp cạnh nhau. Việc viết {}{} để lại một trình phân tích mà không có dấu phân cách tiêu chuẩn. NDJSON giao vai trò đó cho dấu xuống dòng. Người đọc không cần phải quét để tìm dấu ngoặc cân bằng vì các dấu ngoặc bên trong chuỗi JSON là các ký tự chuỗi thông thường và ranh giới dòng vật lý kết thúc bản ghi.

Một nhà sản xuất có thể xả mỗi dòng khi bản ghi đã sẵn sàng. Một người tiêu dùng có thể áp dụng áp lực ngược thông qua giao diện luồng của mình, phân tích một dòng, xác minh giá trị và giải phóng bộ nhớ sau khi xử lý. Điều này giữ cho việc sử dụng bộ nhớ gắn liền với bản ghi lớn nhất và các bộ đệm ống dẫn thay vì toàn bộ tập dữ liệu.

NDJSON không phải là định dạng chuỗi JSON duy nhất. RFC 7464 định nghĩa các chuỗi văn bản JSON sử dụng một ký tự phân cách bản ghi ASCII trước mỗi văn bản JSON. Cách đóng khung đó có thể chịu đựng các giá trị in đẹp vì các ranh giới bản ghi không phụ thuộc hoàn toàn vào kết thúc dòng. Các nhà sản xuất và người tiêu dùng phải đồng ý về định dạng chuỗi mà họ sử dụng.

Thiết kế bản ghi NDJSON

Một luồng NDJSON mạnh mẽ cung cấp cho mỗi dòng đủ ngữ cảnh để được xử lý độc lập. Bao gồm một loại bản ghi hoặc phiên bản lược đồ ổn định khi nhiều hình dạng sự kiện chia sẻ một luồng. Bao gồm một định danh hỗ trợ việc loại bỏ trùng lặp khi phương tiện có thể truyền tải cùng một bản ghi logic nhiều hơn một lần. Thêm thời gian sự kiện và quan sát chỉ với các định dạng được tài liệu hóa và ngữ nghĩa múi giờ.

Giữ nội dung nhị phân lớn ra khỏi JSON định hướng dòng trừ khi hợp đồng yêu cầu rõ ràng các byte đã mã hóa. Base64 làm tăng kích thước và tạo ra các bản ghi rất dài. Một sự kiện tốt hơn có thể mang một tham chiếu đối tượng được kiểm soát cộng thêm siêu dữ liệu toàn vẹn, tùy thuộc vào việc ủy quyền tại thời điểm truy xuất.

Thứ tự phải được rõ ràng. NDJSON giữ nguyên thứ tự dòng vật lý, nhưng các nhà sản xuất phân tán, các phân vùng và người tiêu dùng song song có thể thay đổi thứ tự xử lý quan sát. Nếu thứ tự có ý nghĩa trong một thực thể, bao gồm một chuỗi hoặc phiên bản và định nghĩa cách xử lý các khoảng trống và các bản ghi không theo thứ tự.

Xác thực lược đồ

JSON hợp lệ không nhất thiết là bản ghi doanh nghiệp hợp lệ. Một dòng có thể phân tích thành công trong khi thiếu một định danh cần thiết hoặc lưu trữ một số nơi mà hợp đồng mong đợi một chuỗi. Xác thực mỗi giá trị đã phân tích chống lại lược đồ bản ghi trước khi sử dụng nó.

Các luồng với nhiều loại bản ghi có thể chọn một lược đồ dựa trên một bộ phân loại ổn định. Bộ điều phối nên từ chối các loại không xác định hoặc định tuyến chúng đến một đường đi kiểm soát. Các phiên bản lược đồ nên định nghĩa tính tương thích để người tiêu dùng có thể tiếp tục khi các trường tùy chọn được thêm vào.

Xác thực cấp bản ghi cho phép một lô báo cáo các lỗi cụ thể mà không làm mất vị trí của các bản ghi chấp nhận được. Lưu số dòng vật lý, byte offset khi có sẵn, lỗi lược đồ và một định danh bản ghi được biên soạn an toàn. Không sao chép bí mật hoặc tải trọng nhạy cảm vào nhật ký lỗi.

Các trường hợp sử dụng NDJSON phổ biến

NDJSON, CSV và Parquet

NDJSON giữ nguyên cấu trúc JSON lồng ghép và cho phép các bản ghi với các trường tùy chọn. CSV nhỏ gọn hơn và dễ tiếp cận hơn khi mỗi bản ghi là một hàng trong bảng phẳng. Parquet thêm lưu trữ cột kiểu cho các phân tích lặp lại trên nhiều bản ghi.

Một đường ống chung thu thập hoặc nhận JSON, viết NDJSON thô cho khả năng theo dõi thân thiện với việc bổ sung, xác thực và chuẩn hóa các bản ghi, sau đó xuất bản Parquet cho các truy vấn phân tích. CSV vẫn hữu ích cho các xuất phẳng lựa chọn cho người dùng bảng tính. Mỗi giai đoạn có một người tiêu dùng khác và do đó một định dạng tốt nhất khác.

Nén và chia nhỏ

Các bản ghi văn bản thường nén tốt vì các khóa và mẫu giá trị lặp lại. Nén toàn bộ tệp giảm kích thước lưu trữ và truyền tải, nhưng một số codec khiến việc bắt đầu đọc từ giữa một luồng nén trở nên khó khăn. Nén có thể tách rời hoặc các khối nén độc lập có thể tốt hơn cho xử lý song song.

Chỉ chia trên các ranh giới bản ghi hoàn chỉnh. Một cú cắt byte-range qua giữa một chuỗi JSON tạo ra các mảnh không hợp lệ. Các hệ thống cần truy cập song song có thể duy trì chỉ mục khối, chia nhỏ luồng thành nhiều đối tượng hoặc sử dụng các định dạng lưu trữ được xây dựng cho các lần đọc chọn lọc.

Nối các tệp NDJSON hợp lệ thường giữ nguyên khung dòng hợp lệ khi mọi đầu vào kết thúc bằng dấu xuống dòng. Nếu một tệp thiếu dấu phân cách cuối cùng, bản ghi cuối cùng của nó có thể chạy vào bản ghi đầu tiên của tệp tiếp theo. Các nhà văn nên luôn kết thúc các bản ghi đã tuần tự hóa, bao gồm cả bản ghi cuối cùng.

Giới hạn Bảo mật và Vận hành

Áp dụng giới hạn cho tổng số byte, độ dài dòng, độ sâu lồng ghép, độ dài chuỗi, kích thước số và số lượng thuộc tính được phép. Một dòng NDJSON duy nhất có thể lớn tùy ý trừ khi ứng dụng thực thi một ranh giới. Đọc với một bộ đệm có giới hạn hoặc chiến lược phát trực tiếp báo cáo một bản ghi quá lớn mà không làm cạn kiệt bộ nhớ.

Không thực thi các trường dưới dạng lệnh hoặc mẫu. Thoát các giá trị khi chúng vào ngữ cảnh HTML, SQL, shell hoặc nhật ký. Bảo vệ chống lại việc giả mạo nhật ký khi các bản ghi NDJSON sau đó được chuyển đổi thành văn bản thuần túy. Giữ ủy quyền ở cấp độ luồng và bản ghi khi một tệp có thể chứa dữ liệu cho nhiều người thuê.

Cách xử lý NDJSON một cách đáng tin cậy

1. Mở luồng dưới dạng UTF-8. Định nghĩa cách các chuỗi byte không hợp lệ được báo cáo; thay thế lặng lẽ có thể thay đổi các định danh.
2. Đọc một dòng vật lý được giới hạn. Chấp nhận các kết thúc dòng đã thỏa thuận và áp dụng kích thước bản ghi tối đa.
3. Xử lý các dòng trống theo hợp đồng. Quyết định xem chúng có bị bỏ qua hay bị từ chối, và áp dụng quy tắc một cách nhất quán.
4. Phân tích một giá trị JSON. Từ chối nội dung không phải khoảng trắng kéo dài trên dòng đó và định nghĩa hành vi thành viên trùng lặp.
5. Xác thực sơ đồ bản ghi. Kiểm tra loại, thuộc tính bắt buộc, giới hạn giá trị và phiên bản hỗ trợ.
6. Xử lý idempotently khi có thể. Các định danh bản ghi ổn định giúp ngăn ngừa các tác động phụ trùng lặp khi một bản ghi xuất hiện nhiều lần.
7. Ghi tiến trình một cách an toàn. Các điểm kiểm tra nên xác định một bản ghi bền vững hoặc ranh giới byte mà không tuyên bố rằng một dòng chưa hoàn chỉnh đã được xử lý.

Khi nào không sử dụng NDJSON

Sử dụng tài liệu JSON bình thường khi payload nhỏ, phải chứa siêu dữ liệu cấp cao nhất, hoặc được hưởng lợi từ việc in đẹp. Sử dụng CSV khi dữ liệu là một bảng phẳng cho người tiêu dùng bảng tính. Sử dụng Parquet khi các công cụ phân tích cần cắt cột, lưu trữ kiểu và nén qua các tập dữ liệu lớn.

NDJSON cũng không phù hợp khi các giá trị cá nhân phải chứa định dạng dòng vật lý không thoát cho việc chỉnh sửa của con người. Một chuỗi JSON dựa trên dấu phân cách bản ghi hoặc một giao thức nhị phân có khung có thể phù hợp hơn với yêu cầu đó.

Kết luận

NDJSON thêm một quy tắc thực tiễn vào giao tiếp JSON: mỗi dòng là một giá trị JSON hoàn chỉnh. Quy tắc đó hỗ trợ các tệp thân thiện với phụ lục, các bộ phân tích luồng, xác thực ở mức bản ghi, và bộ nhớ giới hạn. Nó không định nghĩa sơ đồ kinh doanh, đảm bảo sắp xếp, chính sách bảo mật, hoặc ngữ nghĩa giao hàng. Một quy trình NDJSON đáng tin cậy sử dụng các bản ghi UTF-8 ngắn gọn, sơ đồ rõ ràng, giới hạn kích thước, định danh ổn định, hành vi dòng trống rõ ràng, và các điểm kiểm tra nhận thức dòng.