𝟵 𝗔𝗣𝗜 𝗖𝗵𝗮𝗻𝗴𝗲𝘀 𝗧𝗵𝗮𝘁 𝗕𝗿𝗲𝗮𝗸 𝗬𝗼𝘂𝗿 𝗔𝗽𝗽

𝟵 𝗔𝗣𝗜 𝗖𝗵𝗮𝗻𝗴𝗲𝘀 𝗧𝗵𝗮𝘁 𝗕𝗿𝗲𝗮𝗸 𝗬𝗼𝘂𝗿 𝗔𝗽𝗽

"Chúng tôi không làm hỏng gì cả. Chúng tôi chỉ dọn dẹp lại phản hồi thôi."

Những lời nói đó thường dẫn đến sự cố. Một ứng dụng di động bị lỗi. Một tích hợp đối tác trả về dữ liệu rác. Bạn đã thay đổi cấu trúc dữ liệu mà những người khác đang phụ thuộc vào.

Những thay đổi nguy hiểm thường trông giống như việc dọn dẹp cho gọn gàng. Chúng vượt qua các bước kiểm duyệt mã (code review) và kiểm thử. Sự cố xảy ra ở những đoạn mã mà bạn không thể nhìn thấy.

Dưới đây là chín thay đổi mang lại cảm giác an toàn nhưng thực tế thì không.

• Đổi tên các trường (fields) Việc đổi userId thành user_id để đảm bảo tính nhất quán sẽ làm hỏng các client. Đổi tên thực chất là một thao tác xóa và một thao tác thêm. Phần xóa chính là thứ gây lỗi cho người dùng. Cách xử lý an toàn: Thêm trường mới. Giữ lại trường cũ. Đánh dấu nó là lỗi thời (deprecate). Xóa nó sau một thời gian dài.

• Biến một trường thành tùy chọn (optional) Một trường trước đây luôn tồn tại. Giờ đây đôi khi nó lại là null. Mã nguồn phía client sẽ bị crash khi cố gắng xử lý nó. Cách xử lý an toàn: Hãy coi việc "luôn luôn hiện diện" là một lời cam kết. Nếu một trường trở thành tùy chọn, hãy sử dụng một phiên bản mới.

• Xóa các trường không sử dụng Bạn không thể biết được người tiêu dùng (consumers) sử dụng dữ liệu của bạn như thế nào. "Không sử dụng" chỉ có nghĩa là "không được bạn sử dụng". Cách xử lý an toàn: Hãy đo lường mức độ sử dụng trường trong môi trường production trước khi xóa bất cứ thứ gì.

• Thu hẹp kiểu dữ liệu đầu vào Thay đổi một string thành một enum hoặc một number thành integer sẽ làm hỏng các yêu cầu (requests). Mở rộng đầu vào là an toàn. Thu hẹp nó là một thay đổi gây lỗi (breaking change). Cách xử lý an toàn: Chỉ nên nới lỏng các đầu vào mà bạn chấp nhận. Việc thắt chặt yêu cầu đòi hỏi một phiên bản mới.

• Thay đổi giá trị mặc định Thay đổi giá trị mặc định từ false sang true sẽ làm thay đổi hành vi mà không gây ra lỗi. Điều này làm hỏng logic một cách âm thầm. Cách xử lý an toàn: Hãy coi việc thay đổi giá trị mặc định là một thay đổi gây lỗi.

• Thêm các trường bắt buộc Thêm tenantId và đặt nó thành bắt buộc sẽ làm hỏng mọi client hiện có. Họ sẽ nhận được lỗi 400. Cách xử lý an toàn: Các trường mới phải là tùy chọn hoặc sử dụng một phiên bản mới.

• Thay đổi định dạng lỗi Thay đổi từ mã 400 sang 422 hoặc thay đổi nội dung (body) của lỗi sẽ làm hỏng mã xử lý lỗi. Cách xử lý an toàn: Định dạng lỗi là các hợp đồng (contracts). Hãy đánh phiên bản cho chúng giống như bất kỳ thứ gì khác.

• Sửa đổi các giá trị enum Đổi tên "active" thành "ACTIVE" sẽ làm hỏng các client. Xóa một giá trị sẽ làm hỏng các client có logic nghiêm ngặt. Cách xử lý an toàn: Các giá trị enum là vĩnh viễn. Hãy thêm chúng một cách cẩn thận. Đừng bao giờ đổi tên hoặc xóa chúng mà không có một phiên bản lớn (major version).

• Thay đổi ý nghĩa dữ liệu Thay đổi định dạng ngày từ Unix seconds sang ISO-8601 hoặc thay đổi phân trang (pagination) từ offset sang cursor sẽ làm hỏng mọi thứ. Một bản so sánh schema (schema diff) thậm chí có thể không phát hiện ra những thay đổi này. Cách xử lý an toàn: Hãy cố định các định dạng một cách rõ ràng. Hãy so sánh các payload thực tế, chứ không chỉ là bản đặc tả (spec).

Đừng chỉ dựa vào cảm giác. Hãy so sánh mọi thay đổi với contract production trong CI của bạn. Con người có thể bỏ sót một trường bị đổi tên, nhưng công cụ diff thì không.

Nguồn: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0