Взаимодействие с RESTful Web-сервисом

Этот урок освещает процесс создания приложения, которое взаимодействует с RESTful web-сервисом.

Что вы создадите

Вы создадите приложение, которое использует Spring RestTemplate для получения информации о компании из Facebook’s Graph API:

http://graph.facebook.com/pivotalsoftware

Что вам потребуется

• Примерно 15 минут свободного времени
• Любимый текстовый редактор или IDE
• JDK 6 и выше
• Gradle 1.11+ или Maven 3.0+
• Вы также можете импортировать код этого урока, а также просматривать web-страницы прямо из Spring Tool Suite (STS), собственно как и работать дальше из него.

Как проходить этот урок

Как и большинство уроков по Spring, вы можете начать с нуля и выполнять каждый шаг, либо пропустить базовые шаги, которые вам уже знакомы. В любом случае, вы в конечном итоге получите рабочий код.

Чтобы начать с нуля, перейдите в Настройка проекта.

Чтобы пропустить базовые шаги, выполните следующее:

• Загрузите и распакуйте архив с кодом этого урока, либо кнонируйте из репозитория с помощью Git: git clone https://github.com/spring-guides/gs-consuming-rest.git
• Перейдите в каталог gs-consuming-rest/initial
• Забегая вперед, получите REST ресурс

Когда вы закончите, можете сравнить получившийся результат с образцом в gs-consuming-rest/complete.

Настройка проекта

Для начала вам необходимо настроить базовый скрипт сборки. Вы можете использовать любую систему сборки, которая вам нравится для сборки проетов Spring, но в этом уроке рассмотрим код для работы с Gradle и Maven. Если вы не знакомы ни с одним из них, ознакомьтесь с соответсвующими уроками Сборка Java-проекта с использованием Gradle или Сборка Java-проекта с использованием Maven.

Создание структуры каталогов

В выбранном вами каталоге проекта создайте следующую структуру каталогов; к примеру, командой mkdir -p src/main/java/hello для *nix систем:

└── src
    └── main
        └── java
            └── hello

Создание файла сборки Gradle

Ниже представлен начальный файл сборки Gradle. Файл pom.xml находится здесь. Если вы используете Spring Tool Suite (STS), то можете импортировать урок прямо из него.

build.gradle

buildscript {
    repositories {
        maven { url "http://repo.spring.io/libs-release" }
        mavenLocal()
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:1.1.6.RELEASE")
    }
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'spring-boot'

jar {
    baseName = 'gs-consuming-rest'
    version =  '0.1.0'
}

repositories {
    mavenLocal()
    mavenCentral()
    maven { url "http://repo.spring.io/libs-release" }
}

dependencies {
    compile("org.springframework.boot:spring-boot-starter")
    compile("org.springframework:spring-web")
    compile("com.fasterxml.jackson.core:jackson-databind")
    testCompile("junit:junit")
}

task wrapper(type: Wrapper) {
    gradleVersion = '1.11'
}

Spring Boot gradle plugin предоставляет множество удобных возможностей:

• Он собирает все jar'ы в classpath и собирает единое, исполняемое "über-jar", что делает более удобным выполнение и доставку вашего сервиса
• Он ищет public static void main() метод, как признак исполняемого класса
• Он предоставляет встроенное разрешение зависимостей, с определенными номерами версий для соответсвующих Spring Boot зависимостей. Вы можете переопределить на любые версии, какие захотите, но он будет по умолчанию для Boot выбранным набором версий

Получение REST ресурса

После того, как вы настроили проект, вы можете создать простое приложение, которое будет взаимодействовать с RESTful web-сервисом.

Предположим, что вы хотите найти что-нибудь, что известно Facebook о Pivotal. Зная, что Pivotal имеет страницу на Facebook c ID "pivotalsoftware", вы должны будете выполнить запрос к Facebook’s Graph API по URL:

http://graph.facebook.com/pivotalsoftware

Если выполните запрос из вашего браузера или curl, то получите JSON документ с примерно такими данными:

{
   "id": "161112704050757",
   "about": "Pivotal is enabling the creation of modern software applications that leverage big & fast data \u2013 on a single, cloud independent platform.",
   "can_post": false,
   "category": "Internet/software",
   "category_list": [
      {
         "id": "108472109230615",
         "name": "Computer Services"
      }
   ],
   "checkins": 42,
   "cover": {
      "cover_id": 163344023827625,
      "offset_x": 0,
      "offset_y": 0,
      "source": "https://fbcdn-sphotos-d-a.akamaihd.net/hphotos-ak-xaf1/t1.0-9/s720x720/554668_163344023827625_839302172_n.png"
   },
   "description": "Pivotal, the company at the intersection of big data, PaaS, and agile development, helps companies transform into great software companies. It starts with Pivotal One, a comprehensive solution that includes a set of application and data services that run on top of Pivotal CF, a turnkey platform-as-a-service (PaaS) solution for agile development teams to rapidly update and scale applications on a private cloud that can be instantly expanded and upgraded with no downtime, allowing enterprises to innovate with disruptive speed.\n\nREVOLUTIONARY COMPREHENSIVE PAAS\nPivotal One is a next generation PaaS that can be deployed on multiple cloud environments to deliver a turnkey experience for scaling and updating PaaS with no downtime. Pivotal One Services helps create a PaaS that no other vendor can offer in the industry by integrating differentiated data services such as Hadoop and visual analytics.\n\nSPEED TIME TO MARKET\nDriving the demand for PaaS is the trend of software being the competitive edge across all industries. This trend has unleashed a new generation of developers driving a deep shift in platforms and processes. These developers work in agile teams and demand a platform that allows them to continuously deliver updates to and horizontally scale their applications with no downtime. They seek standardized ways to plug in leading data services and perform deep user analytics on top of massive datasets to drive rapid iteration based on customer needs.\n\nABOUT PIVOTAL\nPivotal, committed to open source and open standards, is a leading provider of application and data infrastructure software, agile development services, and data science consulting. Follow Pivotal on Twitter \u0040gopivotal.",
   "founded": "2013",
   "has_added_app": false,
   "is_community_page": false,
   "is_published": true,
   "likes": 1022,
   "link": "https://www.facebook.com/pivotalsoftware",
   "location": {
      "city": "San Francisco",
      "country": "United States",
      "latitude": 37.78199,
      "longitude": -122.40406,
      "state": "CA",
      "street": "875 Howard St",
      "zip": "94103"
   },
   "mission": "Pivotal, the company at the intersection of big data, PaaS, and agile development, helps companies transform into great software companies. ",
   "name": "Pivotal",
   "parking": {
      "lot": 0,
      "street": 0,
      "valet": 0
   },
   "phone": "(650) 286-8012",
   "products": "PaaS:\nPivotal One, Pivotal CF, Cloud Foundry\n\nDATA: Pivotal HD, Pivotal HD with GemFire XD, Pivotal Greenplum DB, Pivotal Data Dispatch,  Pivotal GemFire, Pivotal SQLFire, Redis\nPaaS: Pivotal One, Pivotal CF, Pivotal Web Services, Cloud Foundry\nDATA TOOLS: Pivotal VRP, Pivotal Command Center\nANALYTICS: MADlib, Pivotal GPText\nAPPLICATIONS: Pivotal tc Server, Pivotal Web Server, Pivotal RabbitMQ, Spring, vFabric Suite",
   "talking_about_count": 77,
   "username": "pivotalsoftware",
   "website": "http://www.gopivotal.com",
   "were_here_count": 42
}

Это достаточно просто сделать, но не особо полезно, когда данные получаются через браузер или curl.

Более полезный способ взаимодействия с REST web-сервисом является программный. Для решения этой задачи, Spring предоставляет удобный шаблонный класс RestTemplate. RestTemplate осуществляет взаимодействие с большинством RESTful сервисами однострочным заклинанием. И он может даже привести данные к пользовательским типам.

Для начала, вы создаете класс, который содержит необходимую вам информацию. Если вам нужно знать название Pivotal, номер телефона, URL web-сайта и информацию о pivotalsoftware, то ниже представленный класс как раз то, что вам нужно:

src/main/java/hello/Page.java

package hello;

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;

@JsonIgnoreProperties(ignoreUnknown = true)
public class Page {

    private String name;
    private String about;
    private String phone;
    private String website;

    public String getName() {
        return name;
    }

    public String getAbout() {
        return about;
    }

    public String getPhone() {
        return phone;
    }

    public String getWebsite() {
        return website;
    }

}

Как видите, это простой Java класс с горсткой полей и соответствующими методами их получения. Он содержит аннотацию @JsonIgnoreProperties библиотеки обработки JSON Jackson, которая показывает, что любые поля, не связанные с полями класса, должны быть проигнорированы.

Создание приложения исполняемым

Несмотря на то, что пакет этого сервиса может быть в составе web-приложения и WAR файлов, более простой подход, продемонстрированный ниже создает отдельное самостоятельное приложение. Вы упаковываете все в единый, исполняемый JAR-файл, который запускается через хорошо знакомый старый main() Java-метод. Попутно, вы используете поддержку Spring для встроенного Tomcat контейнера сервлетов как HTTP среду выполнения вместо развертывания на сторонний экземпляр.

Теперь вы можете создать Application класс, который использует RestTemplate для получения данных со страницы Pivotal на Facebook и преобразует в Page объект.

src/main/java/hello/Application.java

package hello;

import org.springframework.web.client.RestTemplate;

public class Application {

    public static void main(String args[]) {
        RestTemplate restTemplate = new RestTemplate();
        Page page = restTemplate.getForObject("http://graph.facebook.com/pivotalsoftware", Page.class);
        System.out.println("Name:    " + page.getName());
        System.out.println("About:   " + page.getAbout());
        System.out.println("Phone:   " + page.getPhone());
        System.out.println("Website: " + page.getWebsite());
    }

}

Т.к. библиотека обработки JSON Jackson доступна из classpath, RestTemplate будет использовать её(через message converter) для конвертации входящих JSON данных в Page объект. Затем, содержимое Page объекта будет напечатано на консоли.

В этом примере вы использовали RestTemplate для создания только HTTP GET запроса. Но RestTemplate также поддерживает и другие виды HTTP запросов, такие как POST, PUT и DELETE.

Сборка исполняемого JAR

Вы можете собрать единый исполняемый JAR-файл, который содержит все необходимые зависимости, классы и ресурсы. Это делает его легким в загрузке, версионировании и развертывании сервиса как приложения на протяжении всего периода разработки, на различных средах и так далее.

./gradlew build

Затем вы можете запустить JAR-файл:

java -jar build/libs/gs-consuming-rest-0.1.0.jar

Если вы используете Maven, вы можете запустить приложение, используя mvn spring-boot:run, либо вы можете собрать приложение с mvn clean package и запустить JAR примерно так:

java -jar target/gs-consuming-rest-0.1.0.jar

Запуск сервиса

Если вы используете Gradle, вы можете запустить ваш сервис из командной строки:

./gradlew clean build && java -jar build/libs/gs-consuming-rest-0.1.0.jar

Как вариант, вы можете запустить ваш сервис напрямую из Gradle примерно так:

./gradlew bootRun

Вы должны увидеть следующее:

Name:    Pivotal
About:   At Pivotal, our mission is to enable customers to build a new class of applications, leveraging big and fast data, and do all of this with the power of cloud independence.
Phone:   650-286-8012
Website: http://www.gopivotal.com

Итог

Поздравляем! Вы только что разработали простой REST-клиент, используя Spring.

С оригинальным текстом урока вы можете ознакомиться на spring.io.