API phiên bản

Giả sử rằng bạn có một dự án lớn được hỗ trợ bởi cơ sở API. Dự án cũng gửi một API công khai mà người dùng cuối (ish) có thể sử dụng.

Đôi khi bạn cần thay đổi cơ sở API hỗ trợ dự án của bạn. Ví dụ: bạn cần thêm một tính năng cần thay đổi API, phương thức mới hoặc yêu cầu thay đổi một trong các đối tượng hoặc định dạng của một trong các đối tượng đó, được chuyển đến hoặc từ API.

Giả sử rằng bạn cũng đang sử dụng các đối tượng này trong API công khai của mình, các đối tượng công khai cũng sẽ thay đổi bất cứ khi nào bạn thực hiện việc này, điều không mong muốn vì khách hàng của bạn có thể dựa vào các đối tượng API giống hệt nhau để mã phân tích cú pháp của họ hoạt động. (ho khách hàng C ++ WSDL ...)

Vì vậy, một giải pháp tiềm năng là phiên bản API. Nhưng khi chúng ta nói "phiên bản" API, có vẻ như điều này cũng có nghĩa là phải phiên bản các đối tượng API cũng như cung cấp các lệnh gọi phương thức trùng lặp cho mỗi chữ ký phương thức đã thay đổi. Vì vậy, sau đó tôi sẽ có một đối tượng clr cũ đơn giản cho mỗi phiên bản api của tôi, một lần nữa dường như không mong muốn. Và ngay cả khi tôi làm điều này, tôi chắc chắn sẽ không xây dựng từng đối tượng từ đầu vì điều đó sẽ kết thúc với số lượng lớn mã trùng lặp. Thay vào đó, API có khả năng mở rộng các đối tượng riêng mà chúng tôi đang sử dụng cho API cơ sở của chúng tôi, nhưng sau đó chúng tôi gặp vấn đề tương tự vì các thuộc tính được thêm vào cũng sẽ có sẵn trong API công khai khi chúng không được phép.

Vì vậy, một số sự tỉnh táo thường được áp dụng cho tình huống này là gì? Tôi biết nhiều dịch vụ công cộng như Git cho Windows duy trì API được phiên bản, nhưng tôi gặp khó khăn khi tưởng tượng một kiến ​​trúc hỗ trợ điều này mà không có số lượng lớn mã trùng lặp bao gồm các phương thức được nhập và các đối tượng đầu vào / phiên bản khác nhau.

Tôi biết rằng các quy trình như phiên bản ngữ nghĩa cố gắng đặt sự tỉnh táo khi xảy ra sự cố vỡ API công khai. Vấn đề là nhiều hơn có vẻ như nhiều hoặc hầu hết các thay đổi đều yêu cầu phá vỡ API công khai nếu các đối tượng không tách biệt hơn, nhưng tôi không thấy cách nào tốt để làm điều đó mà không cần sao chép mã.

Khi duy trì API được sử dụng bởi các bên thứ ba, bạn không cần phải thay đổi. Mức độ phức tạp sẽ phụ thuộc vào loại thay đổi đang xảy ra. Đây là những kịch bản chính xuất hiện:

1. Chức năng mới được thêm vào API hiện có
2. Chức năng cũ không dùng nữa từ API
3. Chức năng hiện có trong API thay đổi theo một cách nào đó

Chức năng mới Thêm vào API hiện có

Đây là kịch bản dễ nhất để hỗ trợ. Việc thêm các phương thức mới vào API sẽ không yêu cầu bất kỳ thay đổi nào đối với các máy khách hiện tại. Điều này là an toàn để triển khai cho các khách hàng cần chức năng mới vì nó không có bản cập nhật cho bất kỳ khách hàng hiện tại nào.

Chức năng cũ không dùng nữa từ API

Trong trường hợp này, bạn phải liên lạc với người tiêu dùng hiện tại về API của mình rằng chức năng sẽ không được hỗ trợ lâu dài. Cho đến khi bạn bỏ hỗ trợ cho chức năng cũ (hoặc cho đến khi tất cả khách hàng đã nâng cấp lên chức năng mới), bạn phải giữ chức năng API cũ và mới cùng một lúc. Nếu đó là một thư viện được cung cấp, hầu hết các ngôn ngữ đều có cách đánh dấu các phương thức cũ là lỗi thời / không dùng nữa. Nếu đó là dịch vụ của bên thứ ba thuộc loại nào đó, tốt nhất là thường có các điểm cuối khác nhau cho chức năng cũ / mới.

Chức năng hiện có trong API thay đổi theo một cách nào đó

Kịch bản này sẽ phụ thuộc vào loại thay đổi. Nếu các tham số đầu vào không còn cần phải được sử dụng thì bạn chỉ cần cập nhật dịch vụ / thư viện để bỏ qua dữ liệu bổ sung. Trong một thư viện, sẽ có phương thức quá tải bên trong gọi phương thức mới yêu cầu ít tham số hơn. Trong một dịch vụ lưu trữ, bạn có điểm cuối bỏ qua dữ liệu bổ sung và nó có thể phục vụ cả hai loại máy khách và chạy cùng một logic.

Nếu chức năng hiện có cần thêm các yếu tố cần thiết mới thì bạn phải có hai điểm cuối / phương thức cho dịch vụ / thư viện của mình. Cho đến khi khách hàng cập nhật, bạn cần hỗ trợ cả hai phiên bản.

Những suy nghĩ khác

Rather, the API is likely to extend the private objects we are using for our base API, but then we run into the same problem because added properties would also be available in the public API when they are not supposed to be.

Không để lộ các đối tượng riêng tư nội bộ thông qua thư viện / dịch vụ của bạn. Tạo các loại của riêng bạn và lập bản đồ thực hiện nội bộ. Điều này sẽ cho phép bạn thực hiện các thay đổi nội bộ và giảm thiểu số lượng cập nhật mà khách hàng bên ngoài cần thực hiện.

The problem is more that it seems like many or most changes require breaking the public API if the objects aren't more separated, but I don't see a good way to do that without duplicating code.

API cho dù đó là dịch vụ hay thư viện cần ổn định tại điểm tích hợp với máy khách. Bạn càng mất nhiều thời gian để xác định đầu vào và đầu ra nên là gì và giữ chúng như những thực thể riêng biệt sẽ giúp bạn tiết kiệm rất nhiều vấn đề đau đầu. Tạo API hợp đồng thực thể riêng của nó và ánh xạ tới các lớp cung cấp công việc thực sự. Thời gian được lưu khi triển khai nội bộ thay đổi sẽ bù đắp thêm thời gian cần thiết để xác định giao diện bổ sung.

Đừng xem bước này là "mã trùng lặp". Mặc dù tương tự, chúng là các thực thể riêng biệt đáng để tạo ra. Mặc dù các thay đổi API bên ngoài hầu như luôn yêu cầu thay đổi tương ứng với triển khai nội bộ, các thay đổi triển khai nội bộ không nên luôn thay đổi API bên ngoài.

Thí dụ

Giả sử bạn đang cung cấp một giải pháp xử lý thanh toán. Bạn đang sử dụng PaymentProviderA để thực hiện các giao dịch thẻ tín dụng. Sau này, bạn nhận được mức giá tốt hơn thông qua bộ xử lý thanh toán của PaymentProviderB. Nếu API của bạn tiếp xúc với các trường Thẻ tín dụng / Địa chỉ hóa đơn thuộc loại của bạn thay vì đại diện của PaymentProviderA thì thay đổi API là 0 vì giao diện vẫn như cũ (dù sao, nếu PaymentProviderB yêu cầu dữ liệu không được PaymentProviderA yêu cầu thì bạn cần phải chọn hỗ trợ cả hai hoặc giữ tỷ lệ tồi tệ hơn với PaymentProviderA).