Công cụ dành cho nhà phát triển · JSON trình định dạng và xác thực
Sửa package.json bị hỏng trước khi CI thực hiện: đọc vị trí lỗi
· Tại sao nó quan trọng
json developer-workflow xác nhận
package.json, composer.json hoặc launch.json được chỉnh sửa thủ công không thành công rất lâu sau khi bạn lưu nó, thường là ở CI. Bài đăng này cho thấy cách xác thực trước khi bạn cam kết và đọc vị trí lỗi một cách nhanh chóng.
Quy trình dài 12 phút để tìm hiểu về một dấu phẩy
Quy trình kéo dài 12 phút để tìm hiểu về một dấu phẩy — xung đột hợp nhất được giải quyết bằng tay, trình soạn thảo màu xanh lá cây và bản dựng màu đỏ. Việc kiểm tra kho lưu trữ có thể trông bình thường vì Git ghi lại byte chứ không phải liệu tệp kê khai có phân tích cú pháp hay không. Sau đó CI sẽ cài đặt các phần phụ thuộc, tiếp cận tệp bị hỏng và dừng trước khi các cuộc kiểm tra cung cấp bất kỳ tín hiệu hữu ích nào.
Công cụ này chỉ kiểm tra cú pháp JSON nghiêm ngặt và chấp nhận các tài liệu có tối đa 8,000,000 JavaScript ký tự. package.json và composer.json là những ví dụ nghiêm ngặt phù hợp. Các tệp như tsconfig.json có thể sử dụng trình phân tích cú pháp chấp nhận nhận xét, do đó việc từ chối nhận xét của chúng dưới dạng JSON không chứng minh được rằng công cụ sở hữu sẽ từ chối chúng. Xác thực dựa trên ngữ pháp mà chương trình tiêu thụ thực sự khai báo.
Tệp cấu hình JSON nào bị hỏng thường xuyên nhất
Tệp cấu hình JSON nào bị hỏng thường xuyên nhất — package.json, composer.json, launch.json và khóa tệp cũng như lý do tsconfig.json, cho phép nhận xét, cần được chăm sóc riêng. Các tệp kê khai do con người chỉnh sửa có xu hướng không thành công xung quanh các khối phụ thuộc, tập lệnh và cài đặt công cụ lồng nhau. Các tệp khóa được tạo không thành công theo cách khác: giải quyết xung đột thủ công có thể làm hỏng dấu phân cách hoặc các phần cấu trúc trùng lặp.
Đừng cho rằng mọi tệp có phần mở rộng giống JSON đều sử dụng JSON nghiêm ngặt. Cài đặt Mã VS và cấu hình TypeScript thường cho phép nhận xét hoặc dấu phẩy thông qua các trình phân tích cú pháp chuyên dụng, trong khi các tệp kê khai gói thường không. Xác thực tệp khóa được tạo bằng trình quản lý gói của nó khi có thể, vì chỉ riêng cú pháp hợp lệ không thể khôi phục hàm băm, quy tắc đặt hàng hoặc tính nhất quán nội bộ mà trình tạo đó mong đợi.
Tại sao các công cụ bị lỗi muộn — trình quản lý gói và trình biên dịch phân tích cú pháp theo yêu cầu, do đó, lỗi cú pháp sẽ xuất hiện tại thời điểm cài đặt hoặc xây dựng thay vì khi lưu
Tại sao các công cụ bị lỗi muộn — trình quản lý gói và trình biên dịch phân tích cú pháp theo yêu cầu, do đó, lỗi cú pháp sẽ xuất hiện tại thời điểm cài đặt hoặc xây dựng thay vì khi lưu. Trình soạn thảo văn bản có thể tô màu các dấu ngoặc nhọn mà không chạy trình phân tích cú pháp chính thức và không thể đọc được tệp kê khai đã thay đổi trong một tác vụ cục bộ hẹp. CI bắt đầu từ một môi trường sạch sẽ và thực hiện các đường dẫn thiết lập mà các máy trạm đã lưu vào bộ nhớ đệm bỏ qua.
Sự chậm trễ dẫn đến bao gồm thời gian xếp hàng, thanh toán, thiết lập phụ thuộc và các công việc sơ bộ không liên quan. Tệ hơn nữa, thông báo cuối cùng có thể chỉ nêu tên một tệp gói không hợp lệ trong khi ẩn dòng gốc đằng sau đầu ra lệnh. Một phân tích cú pháp cục bộ ngay sau khi chỉnh sửa sẽ thu gọn vòng phản hồi đó. Nó cũng phân biệt lỗi ngữ pháp với lỗi lược đồ hoặc lỗi giải quyết phụ thuộc sau này cần được điều tra khác.
Đọc vị trí lỗi dưới áp lực
Đọc vị trí lỗi dưới áp lực - dòng và cột, mã thông báo trước đó và ba mẫu xung đột hợp nhất tạo ra JSON không hợp lệ. Ký tự được đánh dấu là nơi không thể tiếp tục, không phải lúc nào cũng bắt đầu sai sót. Một trích dẫn kết thúc có thể hiển thị một trích dẫn không thoát trước đó; dấu ngoặc nhọn có thể để lộ dấu phẩy bị thiếu ngay trước thuộc tính tiếp theo.
Sau khi hợp nhất, hãy tìm các điểm đánh dấu xung đột còn lại dưới dạng văn bản thuần túy, các khối thành viên trùng lặp được nối mà không có dấu phẩy và các dấu phân cách đã bị xóa khi chọn một bên. Kiểm tra mã thông báo trước vị trí được báo cáo và đếm ranh giới vùng chứa xung quanh. Thực hiện một lần sửa chữa, chạy lại xác thực và giữ nguyên sự khác biệt ban đầu, bởi vì trình phân tích cú pháp thường chỉ báo cáo trở ngại đầu tiên và xung đột độc lập thứ hai có thể vẫn còn ở xa hơn.
Ví dụ đã hoạt động: package.json sau khi hợp nhất không tốt
Ví dụ đã hoạt động: package.json sau khi hợp nhất không tốt — khối phụ thuộc trùng lặp, thiếu dấu phẩy, báo cáo trình xác thực và bản sửa lỗi. Hãy tưởng tượng `"scripts":{"test":"vitest"}` ngay sau đó là `"dependencies":{"vite":"7.3.6"}`. Tên thuộc tính thứ hai là nơi trình phân tích cú pháp phát hiện ra rằng đối tượng thiếu dấu phân cách, mặc dù dấu phẩy chính xác nằm sau đối tượng tập lệnh.
Chèn dấu phẩy đó và xác nhận lại trước khi định dạng. Nếu việc hợp nhất cũng tạo ra hai khóa `dependencies` thì việc phân tích cú pháp nghiêm ngặt vẫn có thể thành công vì các tên trùng lặp được cho phép về mặt cú pháp, tuy nhiên việc phân tích cú pháp JavaScript chỉ giữ lại giá trị sau này. So sánh cả hai nhánh và kết hợp các thành viên dự định thay vì xóa một khối một cách máy móc. Sửa chữa cú pháp và giải quyết hợp nhất ngữ nghĩa là các nhiệm vụ liên tiếp, riêng biệt.
Biến việc xác nhận thành thói quen
Tạo thói quen xác thực — dán trước khi xác nhận hoặc xác thực bất kỳ JSON nào bạn đã chỉnh sửa bên ngoài IDE mà không cần tài khoản hoặc plugin. Trình kích hoạt tốt nhất là hành vi: bất cứ khi nào các điểm đánh dấu xung đột được giải quyết, một khối lớn được di chuyển hoặc dấu câu được nhập theo cách thủ công, chạy kiểm tra của công cụ sở hữu hoặc trình phân tích cú pháp nghiêm ngặt trước khi sắp xếp tệp.
Các kho lưu trữ có thể tự động hóa quy tắc tương tự bằng tính năng kiểm tra trước khi cam kết và công việc CI nằm trong phạm vi các tệp kê khai, nhưng tính năng tự động hóa sẽ bổ sung cho phản hồi ngay lập tức thay vì trở thành trình phân tích cú pháp đầu tiên. Giữ định dạng tách biệt với sửa chữa để phần khác biệt hiển thị ký tự có ý nghĩa. Đối với các tệp được tạo, hãy tạo lại từ tệp kê khai nguồn thay vì chuẩn hóa đầu ra được chỉnh sửa bằng tay, sau đó để trình tạo chứng minh các bất biến của chính nó.
Điều này không bao gồm những gì
Điều này không bao gồm những lỗi ngữ nghĩa như phạm vi phiên bản sai hoặc trường không xác định mà JSON hợp lệ không thể bảo vệ bạn khỏi. Tệp kê khai gói có thể phân tích cú pháp trong khi đặt tên cho tập lệnh không tồn tại, đặt phần phụ thuộc vào sai phần hoặc sử dụng biểu thức phiên bản được giải quyết ngoài dự kiến. Các khóa trùng lặp cũng có thể vượt qua quá trình kiểm tra ngữ pháp trong khi âm thầm thay thế các giá trị trước đó.
Sử dụng xác thực trình quản lý gói, lược đồ, kiểm tra cài đặt và đánh giá cho các lớp đó. Việc kiểm tra này cũng không chứng minh được tệp khóa khớp với bảng kê khai của nó hoặc cấu hình khởi chạy đặt tên cho trình gỡ lỗi đã cài đặt. Nếu định dạng thực tế là JSONC hoặc một phương ngữ khác, hãy sử dụng trình phân tích cú pháp của nó thay vì xóa cú pháp được hỗ trợ chỉ để đáp ứng JSON nghiêm ngặt. Ngữ pháp là cánh cổng sớm nhất chứ không phải là bản hợp đồng cấu hình hoàn chỉnh.
Bài học rút ra: kiểm tra cú pháp tốn vài giây, đường dẫn bị lỗi tốn vài phút
Bài học rút ra: kiểm tra cú pháp tốn vài giây, quy trình bị lỗi tốn vài phút — và báo cáo chính xác của người xác nhận sẽ rút ngắn thời gian khắc phục. Chạy nó trên các byte được chỉnh sửa cuối cùng, bắt đầu ở dòng và cột được báo cáo, sau đó kiểm tra mã thông báo trước đó để tìm dấu phân cách hoặc dấu phân cách bị thiếu. Xác nhận lại sau mỗi lần sửa vì ban đầu các lỗi sau này có thể bị ẩn.
Sau khi cú pháp nghiêm ngặt được thông qua, hãy quay lại người dùng: chạy trình quản lý gói, trình biên dịch hoặc xác thực dành riêng cho trình soạn thảo để hiểu các trường và giá trị được phép. Giữ khoảng cách sửa chữa ở mức hẹp, đặc biệt là sau khi hợp nhất, để người đánh giá có thể phân biệt dấu câu với các quyết định phụ thuộc. Trình tự này phát hiện lỗi cục bộ rẻ nhất và dành thời gian xử lý tốn kém cho hành vi mà chỉ có môi trường đầy đủ mới có thể đánh giá được.