Công cụ dành cho nhà phát triển · JSON trình định dạng và xác thực
Hợp lệ JSON so với hợp lệ đối với lược đồ: hai ý nghĩa của 'hợp lệ'
· Lý lịch
json tiêu chuẩn xác nhận
Trình xác thực cho biết JSON của bạn hợp lệ chỉ có nghĩa là nó phân tích cú pháp. Bài đăng này giải thích mức độ hợp lệ (cú pháp, cấu trúc, ngữ nghĩa) và lý do JSON Lược đồ tồn tại cho mọi thứ ngoài ngữ pháp.
Hợp lệ và vẫn bị từ chối
Một yêu cầu có thể hoàn hảo JSON và vẫn không được API chấp nhận. `{"username":"nori","plan":"gold"}` có các dấu phân cách cân bằng, tên được trích dẫn và giá trị pháp lý, tuy nhiên, dịch vụ có thể yêu cầu email, từ chối tên gói hoặc cấm tạo tài khoản ở trạng thái hiện tại. Trình phân tích cú pháp và ứng dụng đang trả lời các câu hỏi khác nhau nên cả hai kết quả đều có thể đúng.
ToolAcre chỉ trả lời câu hỏi đầu tiên: văn bản này có thể được phân tích cú pháp ở mức nghiêm ngặt JSON trong giới hạn đầu vào của nó không? Nó không tải lược đồ, kiểm tra các thuộc tính bắt buộc, xác minh định dạng, liên hệ với cơ sở dữ liệu hoặc đánh giá các quy tắc kinh doanh. Khi công cụ cho biết Hợp lệ, hãy đọc đó là “cú pháp JSON đúng định dạng”, chứ không phải là sự phê duyệt từ hệ thống sẽ sử dụng giá trị.
Cấp độ một: cú pháp đúng ngữ pháp
Xác thực cú pháp kiểm tra ngữ pháp JSON: một giá trị cấp cao nhất, vùng chứa được ghép nối chính xác, tên đối tượng được trích dẫn, dấu phẩy và dấu hai chấm hợp lệ, chuỗi pháp lý, số pháp lý và chữ chính xác. Nó từ chối `NaN` và `Infinity`, nhận xét, dấu phẩy ở cuối và chuỗi trích dẫn đơn. Nó chấp nhận mọi hình dạng hợp lệ về mặt ngữ pháp, bao gồm một số đơn độc hoặc một đối tượng có các trường không quen thuộc.
Nguồn không đúng định dạng có điểm lỗi văn bản, vì vậy ToolAcre có thể báo cáo một dòng và cột cho ký tự không thể đọc được đầu tiên. Thiếu dấu phẩy có thể khiến trích dẫn tiếp theo được báo cáo; dấu phẩy ở cuối có thể khiến dấu phân cách đóng được báo cáo. Cú pháp sửa sẽ tạo ra một giá trị có thể phân tích cú pháp nhưng không xác định rằng giá trị đó có hình dạng hoặc ý nghĩa mà chương trình khác mong đợi.
Cấp độ 2: hình dạng
Xác thực hình dạng hỏi xem giá trị được phân tích có khớp với hợp đồng đã khai báo hay không. Lược đồ người dùng có thể yêu cầu `email`, giới hạn `age` ở một số nguyên ít nhất là 18, giới hạn `tier` ở `free` hoặc `pro` và không cho phép các thuộc tính không xác định. `{"email":false,"tier":"gold"}` là cú pháp JSON hợp lệ nhưng không thực hiện được các quy tắc cấu trúc đó vì loại giá trị và các lựa chọn được phép sai.
JSON Lược đồ là một cách để thể hiện những ràng buộc như vậy nhưng ToolAcre không thực thi nó. Trình xác thực lược đồ thường báo cáo một đường dẫn phiên bản, chẳng hạn như `/tier`, một từ khóa như `enum` và một thông báo giải thích thay vì dấu mũ của trình phân tích cú pháp. Giữ phiên bản lược đồ và hợp đồng API bên cạnh tải trọng khi chẩn đoán cấp độ này; thay đổi dấu câu sẽ không sửa được giá trị được phân tích cú pháp chính xác của hình dạng sai.
Cấp độ 3: ý nghĩa
Ý nghĩa phụ thuộc vào các sự kiện và quy tắc ngoài hình dạng tĩnh của tài liệu. `accountId` có thể có mẫu chuỗi chính xác trong khi không đặt tên tài khoản. Ngày bắt đầu có thể khớp với định dạng kiểu ISO trong khi rơi vào sau ngày kết thúc. Một số lượng có thể dương nhưng vẫn vượt quá lượng tồn kho hiện tại. Những lỗi này yêu cầu bối cảnh ứng dụng, trạng thái được lưu trữ hoặc mối quan hệ giữa các trường.
Một số ràng buộc ngữ nghĩa có thể được tính gần đúng trong một lược đồ, nhưng nhiều ràng buộc thuộc về logic dịch vụ nơi có sẵn dữ liệu xác thực và trạng thái giao dịch. Phản hồi lỗi ở cấp độ này phải xác định trường hoặc quy tắc có liên quan mà không coi văn bản JSON không đúng định dạng. ToolAcre không thể tái tạo các quyết định đó vì nó không biết hợp đồng cũng như không gửi thông tin đầu vào tới ứng dụng sở hữu quy tắc kinh doanh.
Ví dụ hoạt động: một tải trọng thông qua ba lần kiểm tra
Bắt đầu với `{"sku":"A-19","quantity":3,"warehouse":"north"}`. ToolAcre chấp nhận nó: tất cả tên và giá trị đều tuân theo ngữ pháp JSON. Sau đó, một lược đồ có thể yêu cầu một đối tượng, một chuỗi không trống SKU, một số nguyên dương và một trong các mã kho được ghi lại. Giả sử tải trọng này cũng vượt qua những ràng buộc đó. Cả hai cuộc kiểm tra đều không xác nhận rằng SKU A-19 tồn tại hoặc phía bắc có ba đơn vị.
Dịch vụ kiểm kê thực hiện lần kiểm tra thứ ba đối với các bản ghi hiện tại và có thể từ chối yêu cầu vì không có sẵn. Thay đổi thụt đầu dòng không thể thay đổi kết quả đó. Nếu `quantity` được viết là `03`, trước tiên cú pháp sẽ không thành công; nếu là `"3"`, việc phân tích cú pháp sẽ thành công nhưng việc kiểm tra loại lược đồ sẽ thất bại; với số `3`, chỉ còn lại quy tắc tồn kho trực tiếp. Do đó, cùng một trường có thể thất bại ở ba lớp riêng biệt vì ba lý do riêng biệt.
Nơi mỗi séc thuộc về
Chạy xác thực cú pháp càng sớm càng tốt trong khi chỉnh sửa, vì các lần kiểm tra sau này không thể hoạt động đáng tin cậy trên văn bản không phân tích cú pháp. Thực thi hình dạng đã khai báo tại mỗi ranh giới ứng dụng không đáng tin cậy thay vì cho rằng khách hàng đã làm như vậy. Đánh giá các bất biến nghiệp vụ trong thành phần sở hữu trạng thái bắt buộc, đặc biệt khi câu trả lời có thể thay đổi giữa các yêu cầu.
Kiểm tra phía máy khách cải thiện phản hồi nhưng không thay thế việc thực thi phía máy chủ. Ngược lại, phản hồi của máy chủ cho biết “JSON không hợp lệ” nên được dành riêng cho lỗi phân tích cú pháp thay vì sử dụng cho mọi yêu cầu bị từ chối. Sự phân tách rõ ràng tạo ra các chẩn đoán hữu ích: dòng và cột cho cú pháp, các đường dẫn phiên bản cho các ràng buộc về cấu trúc và các mã hoặc thông báo theo miền cụ thể cho các xung đột ngữ nghĩa. ToolAcre chỉ cung cấp danh mục đầu tiên.
Điều này không bao gồm những gì
Trình định dạng này không tạo ra hoặc đánh giá JSON Lược đồ, chọn bản nháp lược đồ, giải quyết các tham chiếu lược đồ, chèn giá trị mặc định hoặc ép buộc các chuỗi thành số. Nó cũng không biết tài liệu OpenAPI của API hoặc các quy ước xác thực tùy chỉnh. Việc cung cấp lược đồ cùng với thông tin đầu vào sẽ không thay đổi kết quả của ToolAcre vì không có bước xử lý lược đồ trong công cụ này.
Xác thực cú pháp cũng không phát hiện tên đối tượng trùng lặp ở đây; `JSON.parse` giữ lần xuất hiện cuối cùng trước khi định dạng. Nó cũng không đảm bảo độ chính xác về số, byte chuẩn, hiển thị hoặc ủy quyền an toàn. Mỗi mối quan tâm đó cần có hợp đồng và cách thực hiện riêng. Tránh nén chúng vào một huy hiệu “hợp lệ” màu xanh lá cây duy nhất, vì làm như vậy sẽ che giấu những bằng chứng nào đã được thu thập và những câu hỏi nào chưa bao giờ được hỏi.
Takeaway: 'hợp lệ' cần một vòng loại
Đủ điều kiện cho mọi yêu cầu xác nhận. “Hợp lệ JSON” có nghĩa là văn bản tuân theo ngữ pháp. “Hợp lệ đối với lược đồ này” có nghĩa là giá trị được phân tích cú pháp đáp ứng hợp đồng cấu trúc được đặt tên. “Được dịch vụ chấp nhận” có nghĩa là các quy tắc ứng dụng hiện tại cho phép hoạt động. Việc vượt qua một lớp là cần thiết cho lớp tiếp theo trong nhiều quy trình công việc, nhưng không bao giờ có bằng chứng cho thấy tất cả các lớp sau đều đã vượt qua.
Sử dụng ToolAcre để định dạng và kiểm tra cú pháp nghiêm ngặt, bao gồm cả việc từ chối các ký tự không phải JSON chẳng hạn như `NaN` và `Infinity`. Sau đó sử dụng lược đồ và ứng dụng thực sự chi phối tải trọng. Khi một yêu cầu vẫn không thành công, hãy đọc lỗi ở lớp của chính nó thay vì định dạng lại chính xác JSON nhiều lần. Công cụ này không có kiểm tra lược đồ và ranh giới rõ ràng đó hữu ích hơn lời hứa về tính hợp lệ quá mức.