Phiên bản tài nguyên REST dễ dàng trong triển khai dựa trên JAX-RS?

Question

Thực tiễn tốt nhất cho phiên bản tài nguyên REST là đưa thông tin phiên bản vào tiêu đề Chấp nhận/Loại nội dung của yêu cầu HTTP để nguyên URI.

Đây là yêu cầu mẫu/đối phó với REST API để lấy thông tin hệ thống: sự chú ý

==> 
GET /api/system-info HTTP/1.1 
Accept: application/vnd.COMPANY.systeminfo-v1+json 

<== 
HTTP/1.1 200 OK 
Content-Type: application/vnd.COMPANY.systeminfo-v1+json 
{ 
    “session-count”: 19 
} 

Pay rằng phiên bản được quy định trong định dạng MIME.

Dưới đây là một yêu cầu/đáp ứng cho phiên bản 2:

==> 
GET /api/system-info HTTP/1.1 
Accept: application/vnd.COMPANY.systeminfo-v2+json 

<== 
HTTP/1.1 200 OK 
Content-Type: application/vnd.COMPANY.systeminfo-v2+json 
{ 
    “uptime”: 234564300, 
    “session-count”: 19 
} 

Xem http://barelyenough.org/blog/tag/rest-versioning/ để biết thêm lời giải thích và ví dụ.

Có thể thực hiện phương pháp này dễ dàng trong các triển khai dựa trên JAX-RS được nhắm mục tiêu Java, chẳng hạn như Jersey hoặc Apache CXF không?

Mục tiêu là có một số lớp @Resource có cùng giá trị @Path nhưng phân phát yêu cầu dựa trên phiên bản thực tế được chỉ định trong loại MIME?

Tôi đã xem xét JAX-RS nói chung và Jersey trong phân khúc và không tìm thấy hỗ trợ cho điều đó. Jersey không có cơ hội đăng ký hai tài nguyên với cùng một đường dẫn. Thay thế cho lớp WebApplicationImpl cần phải được triển khai để hỗ trợ điều đó.

Bạn có thể đề xuất điều gì đó không?

LƯU Ý: Cần có nhiều phiên bản của cùng một tài nguyên cùng một lúc. Các phiên bản mới có thể đưa ra những thay đổi không tương thích.

Answer 1

JAX-RS gửi đến các phương thức được chú thích bằng @Produces thông qua tiêu đề Chấp nhận. Vì vậy, nếu bạn muốn JAX-RS thực hiện công việc của bạn, bạn sẽ cần tận dụng cơ chế này. Nếu không có thêm bất kỳ công việc nào, bạn sẽ phải tạo một phương thức (và Nhà cung cấp) cho mọi loại phương tiện mà bạn muốn hỗ trợ.

Không có gì ngăn bạn có một số phương pháp dựa trên loại phương tiện truyền thông mà tất cả gọi một phương pháp phổ biến để làm việc đó, nhưng bạn phải cập nhật và thêm mã mỗi lần bạn thêm loại phương tiện mới.

Một ý tưởng là thêm bộ lọc "chuẩn hóa" tiêu đề Chấp nhận của bạn một cách cụ thể để gửi đi. Đó là, có lẽ, lấy của bạn:

Accept: application/vnd.COMPANY.systeminfo-v1+json 

Và chuyển đổi đó để, chỉ cần:

Accept: application/vnd.COMPANY.systeminfo+json 

Đồng thời, bạn trích xuất các thông tin phiên bản để sử dụng sau (có lẽ trong yêu cầu, hoặc một số cơ chế đặc biệt khác).

Sau đó, JAX-RS sẽ gửi đến phương thức duy nhất xử lý "application/vnd.COMPANY.systeminfo + json".

Phương thức sau đó lấy thông tin phiên bản "ngoài băng" để xử lý chi tiết trong quá trình xử lý (chẳng hạn như chọn lớp thích hợp để tải qua OSGi).

Tiếp theo, sau đó bạn tạo Nhà cung cấp có MessageBodyWriter thích hợp. Nhà cung cấp sẽ được JAX-RS chọn cho kiểu ứng dụng/vnd.COMPANY.systeminfo + json. Nó sẽ được lên đến MBW của bạn để tìm ra các loại phương tiện truyền thông thực tế (dựa trên một lần nữa về thông tin phiên bản) và để tạo ra định dạng đầu ra thích hợp (một lần nữa, có lẽ gửi đến đúng lớp tải OSGi).

Tôi không biết liệu MBW có thể ghi đè tiêu đề Loại nội dung hay không. Nếu không, sau đó bạn có thể ủy nhiệm bộ lọc trước đó để viết lại phần đó cho bạn trên đường ra.

Đó là một chút phức tạp, nhưng nếu bạn muốn tận dụng công văn JAX-RS, và không tạo phương thức cho mọi phiên bản của loại phương tiện, thì đây là một cách có thể để thực hiện điều đó.

Chỉnh sửa để đáp ứng với bình luận:

Yea, về cơ bản, bạn muốn JAX-RS để gửi đến lớp đúng đắn dựa trên cả hai con đường và chấp nhận loại. Không chắc rằng JAX-RS sẽ thực hiện việc này ra khỏi hộp, vì nó là một chút của một trường hợp cạnh. Tôi đã không xem xét bất kỳ triển khai JAX-RS nào, nhưng bạn có thể thực hiện những gì bạn muốn bằng cách tinh chỉnh một trong các cấp độ cơ sở hạ tầng.

Có thể một tùy chọn ít xâm lấn khác là sử dụng mẹo cũ từ thế giới Apache và chỉ cần tạo bộ lọc viết lại đường dẫn của bạn dựa trên tiêu đề Chấp nhận.

Vì vậy, khi hệ thống được:

GET /resource 
Accept: application/vnd.COMPANY.systeminfo-v1+json 

Bạn viết lại nó để:

GET /resource-v1 
Accept: application/vnd.COMPANY.systeminfo-v1+json 

Sau đó, trong lớp JAX-RS của bạn:

@Path("resource-v1") 
@Produces("application/vnd.COMPANY.systeminfo-v1+json") 
public class ResourceV1 { 
    ... 
} 

Vì vậy, khách hàng của bạn có được cái nhìn chính xác, nhưng các lớp của bạn được JAX-RS gửi đi đúng cách. Vấn đề khác duy nhất là các lớp học của bạn, nếu họ nhìn, sẽ thấy Path đã sửa đổi, không phải đường dẫn ban đầu (nhưng bộ lọc của bạn có thể chứa nội dung đó trong yêu cầu dưới dạng tham chiếu nếu bạn muốn).

Nó không lý tưởng, nhưng hầu hết là miễn phí.

This là một bộ lọc hiện tại có thể làm những gì bạn muốn làm, nếu không nó có lẽ có thể hoạt động như một nguồn cảm hứng để bạn tự làm điều đó.

Answer 2

Một giải pháp khả thi là sử dụng một @Path với

Content-Type: application/vnd.COMPANY.systeminfo- {version} + json

Sau đó, bên trong phương pháp của @Path cho trước, bạn có thể gọi phiên bản của WebService

Answer 3

Nếu bạn đang sử dụng CXF, bạn có thể use the technique specified here để xây dựng nhà cung cấp serialization mới (xây dựng cơ sở hạ tầng hiện có) tạo dữ liệu theo định dạng cụ thể mong muốn. Khai báo một vài cái, một cho mỗi định dạng cụ thể mà bạn muốn và sử dụng chú thích @Produces để cho phép máy móc xử lý phần còn lại của thương lượng cho bạn, mặc dù cũng có thể là ý tưởng hỗ trợ loại nội dung JSON chuẩn để khách hàng bình thường có thể xử lý nó mà không cần phải bẻ khóa sự đặc biệt của bạn.Câu hỏi thực sự duy nhất sau đó trở thành cách tốt nhất để thực hiện tuần tự hóa là gì; Tôi đoán bạn có thể con số đó ra cho chính mình ...

---

[EDIT]: đào sâu hơn trong CXF documentation dẫn đến sự mặc khải rằng cả @Consumes và @Produces chú thích được coi là trục để thực hiện lựa chọn. Nếu bạn muốn có hai phương pháp xử lý việc sản xuất phản hồi cho các loại phương tiện khác nhau, bạn chắc chắn nhất có thể. (Bạn sẽ phải thêm các nhà cung cấp tuần tự hóa và/hoặc deserialization nếu bạn đang sử dụng các loại tùy chỉnh, nhưng bạn có thể làm đại biểu của phần lớn công việc cho các nhà cung cấp tiêu chuẩn.) Tôi vẫn muốn thận trọng rằng bạn nên vẫn đảm bảo rằng tài nguyên được chỉ ra bởi đường dẫn phải giống nhau trong cả hai trường hợp; để làm khác không phải là RESTful.