Tôi vẫn nhớ ngày mình đã dành sáu giờ để gỡ lỗi cái mà hóa ra chỉ là một dấu phẩy đặt sai chỗ trong một tệp cấu hình JSON dài 3.000 dòng. Khi đó là 2 giờ sáng, API sản xuất của chúng tôi đang trả về 500 lỗi cho 47.000 người dùng đang hoạt động, và nhóm của tôi đang điên cuồng tìm kiếm trong các nhật ký mà chỉ ra "JSON không hợp lệ" ở đâu đó trong kiến trúc microservices của chúng tôi. Đêm đó đã khiến công ty chúng tôi mất khoảng 23.000 USD doanh thu và dạy tôi nhiều hơn về việc gỡ lỗi JSON hơn bất kỳ tài liệu hướng dẫn nào có thể.
💡 Những điểm cần lưu ý
- Cấu trúc của các lỗi JSON: Hiểu điều gì đã sai
- Cạm bẫy dấu phẩy thừa: Cái bẫy phổ biến nhất của JSON
- Xáo trộn dấu ngoặc: Dấu ngoặc đơn, thiếu dấu ngoặc và chuỗi thoát
- Cơn ác mộng cấu trúc: Dấu ngoặc và ngoặc vuông không khớp
Tôi là Marcus Chen, một Kỹ sư DevOps cao cấp với 12 năm kinh nghiệm quản lý hạ tầng đám mây cho các công ty SaaS. Trong thập kỷ qua, tôi đã gỡ lỗi hàng ngàn vấn đề liên quan đến JSON trên các API REST, tệp cấu hình, xuất dữ liệu từ cơ sở dữ liệu và các lớp giao tiếp dịch vụ. Những gì tôi đã học được là các lỗi JSON theo những mẫu dự đoán được, và khi bạn hiểu những mẫu này, bạn có thể chẩn đoán và sửa hầu hết các vấn đề trong vài phút thay vì hàng giờ.
JSON đã trở thành ngôn ngữ chung của phát triển web hiện đại. Theo Khảo sát Nhà phát triển 2023 của Stack Overflow, hơn 71% nhà phát triển làm việc với JSON thường xuyên, khiến nó trở thành định dạng trao đổi dữ liệu phổ biến nhất hiện nay. Tuy nhiên, mặc dù có vẻ đơn giản, việc gỡ lỗi JSON vẫn là một trong những nhiệm vụ tốn thời gian nhất mà các nhà phát triển phải đối mặt. Vấn đề không phải là JSON phức tạp—mà là các thông điệp lỗi thường rất khó hiểu, các tệp có thể rất lớn, và một ký tự sai chỗ có thể phá hỏng mọi thứ.
Cấu trúc của các lỗi JSON: Hiểu điều gì đã sai
Trước khi chúng ta dive vào các lỗi cụ thể, hãy hiểu tại sao JSON lại dễ bị hỏng như vậy. Các quy tắc cú pháp nghiêm ngặt của JSON vừa là sức mạnh vừa là điểm yếu của nó. Khác với đối tượng JavaScript, JSON yêu cầu sử dụng dấu ngoặc kép đôi quanh các khóa, không cho phép dấu phẩy thừa, và hoàn toàn không có độ khoan dung cho các bình luận. Những hạn chế này khiến JSON có thể được phân tích bởi hầu hết mọi ngôn ngữ lập trình, nhưng chúng cũng tạo ra nhiều cơ hội cho lỗi của con người.
Theo kinh nghiệm của tôi, khoảng 60% các lỗi JSON rơi vào năm loại: lỗi cú pháp, lỗi cấu trúc, vấn đề mã hóa, những nhầm lẫn kiểu, và vi phạm lược đồ. 40% còn lại là các trường hợp đặc biệt liên quan đến các ký tự đặc biệt, độ chính xác số, hoặc những điểm quái dị không cụ thể cho nền tảng. Hiểu loại nào các lỗi của bạn rơi vào là bước đầu tiên để sửa chúng nhanh chóng.
Khía cạnh gây khó chịu nhất trong việc gỡ lỗi JSON là các trình phân tích thường báo cáo lỗi sai vị trí. Khi một trình phân tích JSON gặp một lỗi, nó thường báo cáo vị trí mà nó nhận ra có điều gì đó sai, chứ không phải là vị trí mà lỗi thực sự xảy ra. Ví dụ, một dấu ngoặc mở thiếu trên dòng 50 có thể không kích hoạt lỗi cho đến dòng 200 khi trình phân tích gặp một dấu ngoặc đóng bất ngờ. Hiệu ứng di chuyển này đã tốn vô số giờ của các nhà phát triển.
Những môi trường phát triển hiện đại đã cải thiện đáng kể việc báo cáo lỗi, nhưng chúng không hoàn hảo. Tôi đã nhận thấy rằng việc kết hợp nhiều công cụ xác thực—trình xác thực tích hợp sẵn của IDE của bạn, các công cụ dòng lệnh như jq, và các trình xác thực trực tuyến—mang đến cho bạn cơ hội tốt nhất để xác định lỗi nhanh chóng. Mỗi công cụ có những điểm mạnh khác nhau: IDE xuất sắc trong việc kiểm tra cú pháp theo thời gian thực, jq cung cấp thông điệp lỗi chi tiết với số dòng, và các trình xác thực trực tuyến thường cung cấp các biểu diễn cây hình ảnh làm cho các lỗi cấu trúc trở nên hiển nhiên.
Cạm bẫy dấu phẩy thừa: Cái bẫy phổ biến nhất của JSON
Nếu tôi phải xác định lỗi JSON phổ biến nhất mà tôi đã gặp, đó sẽ là dấu phẩy thừa. Trong JavaScript, dấu phẩy thừa không chỉ được cho phép mà còn thường được khuyến khích để có những thay đổi sạch hơn trong quản lý phiên bản. Tuy nhiên, JSON lại nghiêm ngặt cấm chúng. Sự khác biệt này có lẽ đã gây ra nhiều sự cố sản xuất hơn bất kỳ điểm quái nào khác của JSON.
"Những lỗi JSON đắt giá nhất không phải là những lỗi gây ra sự cố ngay lập tức—mà là những lỗi gây ra sự hỏng hóc dữ liệu lén lút mà vượt qua xác thực nhưng phá vỡ logic kinh doanh ở phía sau."
Đây là những gì một lỗi dấu phẩy thừa trông như thế nào trong thực tế. Bạn có một mảng các đối tượng người dùng, và bạn vừa thêm một người dùng mới vào cuối danh sách. Trong JavaScript, điều này hoàn toàn hợp lệ, nhưng trong JSON, đó là một lỗi cú pháp sẽ khiến trình phân tích của bạn thất bại.
Thông điệp lỗi mà bạn thường thấy là điều gì đó như "Ký tự không mong đợi }" hoặc "Tên thuộc tính hoặc ‘}’ được kỳ vọng" điều này không ngay lập tức hét lên "vấn đề dấu phẩy thừa." Tôi đã tự huấn luyện bản thân tìm kiếm dấu phẩy thừa đầu tiên mỗi khi tôi thấy những thông điệp lỗi chung chung này, và điều đó đã tiết kiệm cho tôi hàng giờ gỡ lỗi.
Cách phòng ngừa tốt nhất chống lại các lỗi dấu phẩy thừa là phòng ngừa. Tôi cấu hình trình soạn thảo mã của mình để tô sáng các dấu phẩy thừa trong các tệp JSON bằng cách gạch chân đỏ chói. Hầu hết các trình soạn thảo hiện đại hỗ trợ điều này thông qua các tiện ích mở rộng hoặc cài đặt tích hợp sẵn. Đối với VS Code, chế độ ngôn ngữ JSON làm điều này tự động. Đối với người dùng Vim, tôi khuyên dùng plugin ALE với trình phân tích JSON được cấu hình.
Trong các môi trường nhóm, tôi thực hiện kiểm tra dấu phẩy thừa thông qua các hooks trước khi cam kết. Một tập lệnh đơn giản chạy jq empty trên tất cả các tệp JSON trước khi cho phép một cam kết đã ngăn hàng chục lỗi dấu phẩy thừa không đến được môi trường staging của chúng tôi. Tập lệnh chạy chưa đầy 50 mili giây trên các tệp JSON tiêu chuẩn, vì vậy nó không làm chậm quy trình làm việc phát triển.
Đối với các tệp JSON lớn mà việc kiểm tra thủ công không thực tế, tôi sử dụng cách tiếp cận hai bước. Đầu tiên, tôi chạy tệp qua một định dạng như prettier hoặc jq với cờ --sort-keys. Điều này không chỉ loại bỏ dấu phẩy thừa mà còn chuẩn hóa định dạng, làm cho các lỗi khác dễ phát hiện hơn. Thứ hai, tôi so sánh phiên bản đã được định dạng với phiên bản gốc để xem cái gì đã thay đổi. Bất kỳ dấu phẩy thừa nào sẽ hiển thị rõ ràng trong sự so sánh.
Xáo trộn dấu ngoặc: Dấu ngoặc đơn, thiếu dấu ngoặc và chuỗi thoát
Các lỗi liên quan đến dấu ngoặc là loại phổ biến thứ hai trong kinh nghiệm gỡ lỗi của tôi, chiếm khoảng 25% tất cả các vấn đề JSON tôi đã gặp. Quyền yêu cầu của JSON về dấu ngoặc kép đôi quanh cả khóa và giá trị chuỗi là không thể thương lượng, tuy nhiên, các nhà phát triển đến từ Python hoặc JavaScript thường trượt vào việc sử dụng dấu ngoặc đơn vì thói quen.
| Loại lỗi | Nguyên nhân phổ biến | Thời gian phát hiện | Thời gian sửa lỗi trung bình |
|---|---|---|---|
| Lỗi Cú Pháp | Thiếu dấu phẩy, dấu phẩy thừa, dấu ngoặc không thoát | Ngay lập tức (phân tích thất bại) | 5-15 phút |
| Vi Phạm Lược Đồ | Kiểu dữ liệu sai, thiếu các trường bắt buộc | Thời gian chạy hoặc xác thực | 15-45 phút |
| Vấn Đề Mã Hóa | Vấn đề UTF-8, ký tự đặc biệt, ký hiệu BOM | Các lỗi định kỳ | 30-90 phút |
| Vấn Đề Cấu Trúc | Nesting sai, tham chiếu vòng tròn | Lỗi logic ở phía sau | 1-4 giờ |
| Kích Thước/Hiệu Suất | Tệp quá lớn, đối tượng lồng nhiều lớp | Lỗi thời gian chờ hoặc bộ nhớ | 2-8 giờ |
Các thông điệp lỗi cho các vấn đề dấu ngoặc thay đổi rất nhiều tùy thuộc vào trình phân tích của bạn. Một số sẽ nói "Ký tự không mong đợi '" trong khi những người khác báo cáo "Ký tự không hợp lệ trong chuỗi" hoặc đơn giản là "Lỗi phân tích." Tôi đã học để nhận diện những điều này như là những vấn đề có thể có từ dấu ngoặc và ngay lập tức tìm kiếm các dấu ngoặc đơn trong tệp. Một tìm kiếm regex nhanh cho '[^']*' sẽ làm nổi bật tất cả các chuỗi có dấu ngoặc đơn.
Các dấu ngoặc không có quanh các khóa đặc biệt tinh vi vì chúng nhìn có vẻ đúng ở cái nhìn đầu tiên. Khi bạn quét qua hàng trăm dòng JSON, một khóa không có dấu ngoặc như username thay vì "username" có thể dễ dàng thoát khỏi sự kiểm tra bằng mắt. Đây là nơi mà xác thực tự động trở nên rất cần thiết. Tôi không bao giờ chỉ tin vào mắt mình khi xem lại JSON—tôi luôn chạy nó qua một trình xác thực.
Các chuỗi thoát thêm một lớp phức tạp nữa. JSON yêu cầu các dấu gạch chéo phải được thoát thành hai dấu gạch chéo, điều này gây ra vấn đề khi xử lý các đường dẫn tệp, biểu thức chính quy, hoặc bất kỳ dữ liệu nào chứa các dấu gạch chéo nguyên mẫu. Tôi đã từng mất ba giờ để gỡ lỗi một tệp cấu hình mà đường dẫn tệp Windows gây ra lỗi phân tích vì các dấu gạch chéo không được thoát đúng cách. Giải pháp là sử dụng dấu gạch chéo phía trước (mà Windows chấp nhận) hoặc thoát đôi các dấu gạch chéo.
Các chuỗi thoát Unicode là một nguồn gây nhầm lẫn phổ biến khác. JSON hỗ trợ các ký tự Unicode hoặc trực tiếp (nếu mã hóa tệp của bạn là UTF-8) hoặc thông qua các chuỗi thoát như \u0041 cho chữ cái A. Việc trộn lẫn các phương pháp này hoặc sử dụng các ký tự thoát không chính xác