Ngăn chặn các cảnh báo lỗi thời (Deprecation Warnings) trở thành những cảnh báo giả

Khi PHPStan đánh dấu một phương thức là lỗi thời (deprecated), thông thường bạn sẽ tìm kiếm một phương thức thay thế. Nhưng nếu không có phương thức nào thay thế thì sao?

Shopware từng sử dụng thẻ @deprecated để thông báo về các thay đổi đã được lên kế hoạch—chẳng hạn như việc thêm một tham số tùy chọn mới. Các công cụ phân tích tĩnh lại coi những thẻ đó là các lỗi thời thực sự và đưa ra cảnh báo cho mọi lời gọi hàm. Sự nhiễu loạn ngày càng tăng, các nhà phát triển bắt đầu phớt lờ các cảnh báo, và các thông báo này dần mất đi giá trị. Đó chính là tình trạng "báo động giả" điển hình.

Trong phiên bản Shopware 6.7.14.0, chúng tôi đã tách biệt các tín hiệu này.

  • @deprecated – hãy dành thẻ này cho các API sẽ biến mất hoặc bị thay thế. Bạn bắt buộc phải di chuyển (migrate) mã nguồn của mình.
  • BC-change attributes – hãy sử dụng chúng cho các tinh chỉnh đã được lên kế hoạch nhưng vẫn giữ cho API hoạt động, chẳng hạn như các tham số tùy chọn mới hoặc các kiểu trả về được thay đổi.

Các thuộc tính (attributes) mới nằm trong Shopware\Core\Framework\Deprecation\BCChange. Chúng cho bạn biết chính xác điều gì sẽ thay đổi và những thành phần nào bị ảnh hưởng.

Chúng tôi chia chúng thành hai nhóm:

  • CallSiteCompatibilityChange – ảnh hưởng đến mã nguồn thực hiện lời gọi một phương thức.
  • ExtenderCompatibilityChange – ảnh hưởng đến các lớp thực hiện kế thừa (extend) hoặc ghi đè (override) một phương thức.

Giờ đây, bạn có thể chuẩn bị sẵn sàng cho phần mở rộng (extension) của mình để tương thích với Shopware 6.8 trước khi bản phát hành lớn tiếp theo ra mắt.

Ví dụ: một phương thức sẽ được thêm một tham số tùy chọn mới. Hãy thêm tham số đó vào các phần ghi đè (overrides) của bạn ngay hôm nay; mã nguồn sẽ chạy được trên cả phiên bản hiện tại và tương lai.

Sự thay đổi này giúp khôi phục niềm tin vào các cảnh báo lỗi thời.

Ba bước dành cho các nhà phát triển

  1. Coi @deprecated là một lỗi bắt buộc phải sửa; API đó sẽ biến mất.
  2. Loại bỏ các mẫu bỏ qua (ignore patterns) quá rộng có thể che giấu các vấn đề thực sự.
  3. Theo dõi các thuộc tính BC-change và thực hiện các cập nhật nhỏ, an toàn ngay bây giờ thay vì phải thực hiện một cuộc di chuyển mã nguồn khổng lồ sau này.

Nguồn: https://dev.to/shopware/when-deprecated-cries-wolf-making-shopwares-next-major-upgrades-easier-983