1. Общ преглед
Парадигмата REST съществува от доста години и все още привлича много внимание.
API RESTful може да бъде реализиран в Java по няколко начина: можете да използвате Spring, JAX-RS или просто да напишете собствените си голи сървлети, ако сте достатъчно добри и смели. Всичко, от което се нуждаете, е възможността за излагане на HTTP методи - останалото е свързано с това как ги организирате и как насочвате клиента при извършване на обаждания към вашия API.
Както можете да разберете от заглавието, тази статия ще обхване JAX-RS. Но какво означава „просто API“? Това означава, че фокусът тук е върху изясняването на объркването между JAX-RS и неговите внедрения и върху предлагането на пример за това как изглежда подходящият уеб сайт на JAX-RS.
2. Включване в Java EE
JAX-RS не е нищо повече от спецификация, набор от интерфейси и анотации, предлагани от Java EE. И тогава, разбира се, имаме внедряванията; някои от по-известните са RESTEasy и Jersey.
Също така, ако някога решите да изградите JEE-съвместим сървър за приложения, момчетата от Oracle ще ви кажат, че наред с много други неща, вашият сървър трябва да осигури внедряване на JAX-RS за използваните приложения. Ето защо се нарича Java Enterprise Edition Platform .
Друг добър пример за спецификация и изпълнение е JPA и Hibernate.
2.1. Леки войни
И така, как всичко това ни помага на разработчиците? Помощта е в това, че нашите разполагаеми програми могат и трябва да бъдат много тънки, позволявайки на сървъра за приложения да предоставя необходимите библиотеки. Това важи и при разработването на RESTful API: окончателният артефакт не трябва да съдържа информация за използваната реализация на JAX-RS.
Разбира се, можем да осигурим изпълнението (ето урок за RESTeasy). Но тогава вече не можем да наричаме нашето приложение „Java EE app“. Ако утре някой дойде и каже „ Добре, време е да преминем към Glassfish или Payara, JBoss стана твърде скъп! “, Може да сме в състояние да го направим, но това няма да е лесна работа.
Ако предоставим собствена реализация, трябва да се уверим, че сървърът знае да изключи собствената си - това обикновено се случва, като има собствен XML файл в разгръщаемото. Излишно е да казвам, че такъв файл трябва да съдържа всякакви тагове и инструкции, за които никой не знае нищо, освен разработчиците, напуснали компанията преди три години.
2.2. Винаги знайте вашия сървър
Досега казахме, че трябва да се възползваме от платформата, която ни се предлага.
Преди да вземем решение за сървър, който да използваме, трябва да видим какво изпълнение на JAX-RS (име, доставчик, версия и известни грешки) предоставя, поне за производствени среди. Например Glassfish идва с Джърси, докато Wildfly или Jboss идват с RESTEasy.
Това, разбира се, означава малко време, отделено за проучване, но се предполага, че трябва да се направи само веднъж, в началото на проекта или при мигрирането му към друг сървър.
3. Пример
Ако искате да започнете да играете с JAX-RS, най-краткият път е: имайте проект на Maven webapp със следната зависимост в pom.xml :
javax javaee-api 7.0 provided Използваме JavaEE 7, тъй като вече има много сървъри за приложения, които го прилагат. Този буркан на API съдържа поясненията, които трябва да използвате, намиращи се в пакета javax.ws.rs . Защо обхватът е "предоставен"? Тъй като и този буркан не трябва да е в окончателното изграждане - той ни е необходим по време на компилиране и той се предоставя от сървъра за времето на изпълнение.
След добавяне на зависимостта, първо трябва да напишем клас на въвеждане: празен клас, който разширява javax.ws.rs.core.Application и се коментира с javax.ws.rs.ApplicationPath:
@ApplicationPath("/api") public class RestApplication extends Application { } Определихме пътя за влизане като / api. Каквито и други пътища да декларираме за нашите ресурси, те ще имат префикс с / api .
След това нека видим ресурс:
@Path("/notifications") public class NotificationsResource { @GET @Path("/ping") public Response ping() { return Response.ok().entity("Service online").build(); } @GET @Path("/get/{id}") @Produces(MediaType.APPLICATION_JSON) public Response getNotification(@PathParam("id") int id) { return Response.ok() .entity(new Notification(id, "john", "test notification")) .build(); } @POST @Path("/post/") @Consumes(MediaType.APPLICATION_JSON) @Produces(MediaType.APPLICATION_JSON) public Response postNotification(Notification notification) { return Response.status(201).entity(notification).build(); } }Имаме проста ping крайна точка, която да извикаме и да проверим дали приложението ни работи, GET и POST за известие (това е просто POJO с атрибути плюс гетери и сетери).
Разгърнете тази война на всеки сървър на приложения, изпълняващ JEE7, и следните команди ще работят:
curl //localhost:8080/simple-jaxrs-ex/api/notifications/ping/ curl //localhost:8080/simple-jaxrs-ex/api/notifications/get/1 curl -X POST -d '{"id":23,"text":"lorem ipsum","username":"johana"}' //localhost:8080/simple-jaxrs-ex/api/notifications/post/ --header "Content-Type:application/json"Където simple-jaxrs-ex е контекстният корен на уеб приложението.
Това беше тествано с Glassfish 4.1.0 и Wildfly 9.0.1.Final. Моля, обърнете внимание, че последните две команди няма да работят с Glassfish 4.1.1, поради тази грешка. Очевидно е известен проблем в тази версия на Glassfish по отношение на сериализацията на JSON (ако трябва да използвате тази версия на сървъра, ще трябва да управлявате JSON марширането сами)
4. Заключение
В края на тази статия просто имайте предвид, че JAX-RS е мощен API и повечето (ако не всички) неща, от които се нуждаете, вече са внедрени от вашия уеб сървър. Няма нужда да превръщате вашата разполагаема в неуправляема купчина библиотеки.
Това описание представлява прост пример и нещата може да се усложнят. Например, може да искате да напишете свои собствени маршалери. Когато е необходимо, потърсете уроци, които решават проблема ви с JAX-RS, а не с Джърси, Resteasy или друго конкретно изпълнение. Много е вероятно проблемът ви да бъде разрешен с една или две анотации.