Перейти к основному содержимому

Введение в оболочку Spring REST

· 6 мин. чтения

1. Обзор​

В этой статье мы рассмотрим Spring REST Shell и некоторые его функции.

Это расширение Spring Shell, поэтому мы рекомендуем сначала прочитать о нем .

2. Введение​

Spring REST Shell — это оболочка командной строки, предназначенная для облегчения работы с ресурсами REST, совместимыми с Spring HATEOAS.

Нам больше не нужно манипулировать URL-адресами в bash с помощью таких инструментов, как curl. Spring REST Shell предоставляет более удобный способ взаимодействия с ресурсами REST.

3. Установка​

Если мы используем компьютер с macOS с Homebrew, мы можем просто выполнить следующую команду:

brew install rest-shell

Для пользователей других операционных систем нам необходимо скачать бинарный пакет с официальной страницы проекта GitHub , распаковать пакет и найти исполняемый файл для запуска:

tar -zxvf rest-shell-1.2.0.RELEASE.tar.gz
cd rest-shell-1.2.0.RELEASE
bin/rest-shell

Другой вариант — загрузить исходный код и выполнить задачу Gradle:

git clone git://github.com/spring-projects/rest-shell.git
cd rest-shell
./gradlew installApp
cd build/install/rest-shell-1.2.0.RELEASE
bin/rest-shell

Если все установлено правильно, мы увидим следующее приветствие:

___ ___  __ _____  __  _  _     _ _  __    
| _ \ __/' _/_   _/' _/| || |   / / | \ \   
| v / _|`._`. | | `._`.| >< |  / / /   > >  
|_|_\___|___/ |_| |___/|_||_| |_/_/   /_/   
1.2.1.RELEASE

Welcome to the REST shell. For assistance hit TAB or type "help".
http://localhost:8080:>

4. Начало работы​

Мы будем работать с уже разработанным API для другой статьи . В качестве базового URL используется localhost:8080 .

Вот список открытых конечных точек:

  • GET / articles – получить все статьи
  • GET /articles/{id} – получить статью по id
  • GET /articles/search/findByTitle?title={title} – получить статью по названию
  • GET /profile/articles — получить данные профиля для ресурса статьи .
  • POST /articles — создать новую статью с указанным телом

Класс Article имеет три поля: id, title и content.

4.1. Создание новых ресурсов​

Добавим новую статью. Мы собираемся использовать команду post для передачи строки JSON с параметром –data .

Во- первых, нам нужно перейти по URL-адресу, связанному с ресурсом, который мы хотим добавить. Следующая команда берет относительный URI, объединяет его с baseUri и устанавливает результат как текущее местоположение: `` 

http://localhost:8080:> follow articles
http://localhost:8080/articles:> post --data "{title: "First Article"}"

Результатом выполнения команды будет:

< 201 CREATED
< Location: http://localhost:8080/articles/1
< Content-Type: application/hal+json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Sun, 29 Oct 2017 23:04:43 GMT
< 
{
  "title" : "First Article",
  "content" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/articles/1"
    },
    "article" : {
      "href" : "http://localhost:8080/articles/1"
    }
  }
}

4.2. Обнаружение ресурсов​

Теперь, когда у нас есть некоторые ресурсы, давайте найдем их. Мы собираемся использовать команду Discover , которая показывает все доступные ресурсы по текущему URI :

http://localhost:8080/articles:> discover

rel        href                                  
=================================================
self       http://localhost:8080/articles/       
profile    http://localhost:8080/profile/articles
article    http://localhost:8080/articles/1

Зная URI ресурса, мы можем получить его с помощью команды get :

http://localhost:8080/articles:> get 1

> GET http://localhost:8080/articles/1

< 200 OK
< Content-Type: application/hal+json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Sun, 29 Oct 2017 23:25:36 GMT
< 
{
  "title" : "First Article",
  "content" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/articles/1"
    },
    "article" : {
      "href" : "http://localhost:8080/articles/1"
    }
  }
}

4.3. Добавление параметров запроса​

Мы можем указать параметры запроса как фрагменты JSON, используя параметр –params .

Получим статью по заданному названию:

http://localhost:8080/articles:> get search/findByTitle \
> --params "{title: "First Article"}"

> GET http://localhost:8080/articles/search/findByTitle?title=First+Article

< 200 OK
< Content-Type: application/hal+json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Sun, 29 Oct 2017 23:39:39 GMT
< 
{
  "title" : "First Article",
  "content" : null,
  "_links" : {
    "self" : {
      "href" : "http://localhost:8080/articles/1"
    },
    "article" : {
      "href" : "http://localhost:8080/articles/1"
    }
  }
}

4.4. Настройка заголовков​

Команда headers позволяет управлять заголовками в рамках сеанса — каждый запрос будет отправляться с использованием этих заголовков. Набор заголовков принимает аргументы –name и –value для определения заголовка.

Мы собираемся добавить несколько заголовков и сделать запрос, включая эти заголовки:

http://localhost:8080/articles:>
  headers set --name Accept --value application/json

{
  "Accept" : "application/json"
}

http://localhost:8080/articles:>
  headers set --name Content-Type --value application/json

{
  "Accept" : "application/json",
  "Content-Type" : "application/json"
}

http://localhost:8080/articles:> get 1

> GET http://localhost:8080/articles/1
> Accept: application/json
> Content-Type: application/json

4.5. Запись результатов в файл​

Не всегда желательно выводить результаты HTTP-запроса на экран. Иногда нам нужно сохранить результаты в файл для дальнейшего анализа.

Параметр –output позволяет выполнять такие операции:

http://localhost:8080/articles:> get search/findByTitle \
> --params "{title: "First Article"}" \
> --output first_article.txt

>> first_article.txt

4.6. Чтение JSON из файла​

Часто данные JSON слишком велики или слишком сложны для ввода через консоль с использованием параметра –data .

Кроме того, существуют некоторые ограничения на формат данных JSON, которые мы можем вводить непосредственно в командную строку.

Параметр –from дает возможность чтения данных из файла или каталога.

Если значением является каталог, оболочка будет читать каждый файл, оканчивающийся на «.json», и выполнять POST или PUT с содержимым этого файла.

Если параметр является файлом, то оболочка загрузит файл и данные POST/PUT из этого файла.

Создадим следующую статью из файла second_article.txt :

http://localhost:8080/articles:> post --from second_article.txt

1 files uploaded to the server using POST

4.7. Установка переменных контекста​

Мы также можем определить переменные в контексте текущего сеанса. Команда var определяет параметры get и set для получения и установки переменной соответственно.

По аналогии с заголовками , аргументы –name и –value предназначены для указания имени и значения новой переменной:

http://localhost:8080:> var set --name articlesURI --value articles
http://localhost:8080/articles:> var get --name articlesURI

articles

Теперь мы собираемся распечатать список доступных в настоящее время переменных в контексте:

http://localhost:8080:> var list

{
  "articlesURI" : "articles"
}

Убедившись, что наша переменная была сохранена, воспользуемся ею с помощью следующей команды для переключения на заданный URI:

http://localhost:8080:> follow #{articlesURI}
http://localhost:8080/articles:>

4.8. Просмотр истории​

Все пути, которые мы посещаем, записываются. История команд показывает эти пути в хронологическом порядке `` :

http://localhost:8080:> history list

1: http://localhost:8080/articles
2: http://localhost:8080

Каждый URI связан с номером, который можно использовать для перехода к этому URI:

http://localhost:8080:> history go 1
http://localhost:8080/articles:>

5. Вывод​

В этом уроке мы сосредоточились на интересном и редком инструменте в экосистеме Spring — инструменте командной строки.

Вы можете найти больше информации о проекте на GitHub .

И, как всегда, все фрагменты кода, упомянутые в статье, можно найти в нашем репозитории .