1. Overview

1.概述

In this article, we’ll have a look at Spring REST Shell and some of its features.

在这篇文章中，我们将看一下Spring REST Shell和它的一些特性。

It’s a Spring Shell extension so we recommend reading about it first.

这是一个Spring Shell扩展，所以我们建议先阅读关于它的介绍。

2. Introduction

2.简介

The Spring REST Shell is a command-line shell designed to facilitate working with Spring HATEOAS-compliant REST resources.

Spring REST Shell是一个命令行外壳，旨在促进与Spring HATEOAS兼容的REST资源的工作。

We no longer need to manipulate the URLs in bash by using tools like curl. Spring REST Shell provides a more convenient way of interacting with REST resources.

我们不再需要通过使用curl.等工具在bash中操作URL。Spring REST Shell提供了一种与REST资源交互的更方便的方式。

3. Installation

3.安装

If we’re using a macOS machine with Homebrew, we can simply execute the next command:

如果我们使用的是带有Homebrew的macOS机器，我们可以简单地执行下一个命令。

brew install rest-shell

For users of other operating systems, we need to download a binary package from the official GitHub project page, unpack the package and find an executable to run:

对于其他操作系统的用户，我们需要从GitHub官方项目页面下载一个二进制包，解压后找到一个可执行文件来运行。

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

Another option is to download the source code and perform a Gradle task:

另一个选择是下载源代码并执行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

If everything is set correctly, we’ll see the following greeting:

如果一切设置正确，我们将看到以下问候语。

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

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

4. Getting Started

4.入门

We’ll be working with the API already developed for another article. The localhost:8080 is used as a base URL.

我们将使用已经为另一篇文章开发的API。localhost:8080被用作基础URL。

Here’s a list of exposed endpoints:

这里有一个暴露的端点的列表。

GET /articles – get all Articles
GET /articles/{id} – get an Article by id
GET /articles/search/findByTitle?title={title} – get an Article by title
GET /profile/articles – get the profile data for an Article resource
POST /articles – create a new Article with a body provided

The Article class has three fields: id, title, and content.

Article类有三个字段。id, title, 和 content.。

4.1. Creating New Resources

4.1.创建新资源

Let’s add a new article. We’re going to use the post command passing a JSON String with the –data parameter.

让我们添加一篇新的文章。我们将使用post命令，在-data参数中传递一个JSONString。

First, we need to follow the URL associated with the resource we want to add. The command follow takes a relative URI, concatenates it with the baseUri and sets the result as the current location:

首先，我们需要follow与我们要添加的资源有关的URL。命令follow接收一个相对的URI，将其与baseUri连接起来，并将结果设置为当前位置。

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

The result of the execution of the command will be:

执行命令的结果将是。

< 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. Discovering Resources

4.2.发现资源

Now, when we’ve got some resources, let’s find them out. We’re going use the discover command which reveals all available resources at the current URI:

现在，当我们得到一些资源时，让我们把它们找出来。我们将使用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

Being aware of the resource URI, we can fetch it by using the get command:

知道了资源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. Adding Query Parameters

4.3.添加查询参数

We can specify query parameters as JSON fragments using the –params parameter.

我们可以使用-params参数将查询参数指定为JSON片段。

Let’s get an article by the given title:

让我们通过给定的标题获得一篇文章。

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. Setting Headers

4.4.设置标头

The command called headers allows managing headers within the session scope – every request will be sent using these headers. The headers set takes the –name and –value arguments to determine a header.

名为headers的命令允许在会话范围内管理头信息 – 每个请求都将使用这些头信息发送。headers set采用-name和-value参数来确定一个头。

We are going to add a few headers and make a request including those headers:

我们将添加一些标题，并提出包括这些标题的请求。

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. Writing Results to a File

4.5.将结果写入文件

It’s not always desirable to print out the results of an HTTP request to the screen. Sometimes, we need to save the results in a file for further analysis.

把HTTP请求的结果打印到屏幕上并不总是可取的。有时，我们需要将结果保存在一个文件中，以便进一步分析。

The –output parameter allows performing such operations:

-output参数允许执行此类操作。

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

>> first_article.txt

4.6. Reading JSON From a File

4.6.从文件中读取 JSON

Often, JSON data is too large or too complex to be entered through the console using the –data parameter.

通常，JSON数据太大或者太复杂，无法通过控制台使用-data参数输入。

Also, there are some limitations on the format of the JSON data we can enter directly into the command line.

另外，我们可以直接在命令行中输入JSON数据的格式有一些限制。

The –from parameter gives the possibility of reading data from a file or a directory.

-from参数提供了从文件或目录中读取数据的可能性。

If the value is a directory, the shell will read each file that ends with “.json” and perform a POST or PUT with the content of that file.

如果值是一个目录，shell将读取每个以“.json”结尾的文件，并将该文件的内容执行POST或PUT。

If the parameter is a file, then the shell will load the file and POST/PUT data from that file.

如果参数是一个文件，那么shell将加载该文件并从该文件POST/PUT数据。

Let’s create the next article from the file second_article.txt:

让我们从文件second_article.txt创建下一篇文章。

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

1 files uploaded to the server using POST

4.7. Setting Context Variables

4.7.设置上下文变量

We can also define variables within the current session context. The command var defines the get and set parameters for getting and setting a variable respectively.

我们还可以在当前会话上下文中定义变量。命令var定义了get和set参数，分别用于获取和设置一个变量。

By analogy with the headers, the arguments –name and –value are for giving the name and the value of a new variable:

与headers相类似，参数-name和-value用于给出一个新变量的名称和值。

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

articles

Now, we’re going to print out a list of currently available variables within the context:

现在，我们要在上下文中打印出一个当前可用的变量列表。

http://localhost:8080:> var list

{
  "articlesURI" : "articles"
}

Having made sure that our variable was saved, we’ll use it with the follow command to switch to the given URI:

在确保我们的变量被保存后，我们将使用它和follow命令来切换到给定的URI。

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

4.8. Viewing History

4.8.查看历史

All the paths we visit are recorded. The command history shows these paths in the chronological order:

我们访问的所有路径都被记录下来。命令history按时间顺序显示这些路径。

http://localhost:8080:> history list

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

Each URI is associated with a number that can be used to go to that URI:

每个URI都与一个数字相关联，可以用来前往该URI。

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

5. Conclusion

5.结论

In this tutorial, we’ve focused on an interesting and rare tool in the Spring ecosystem – a command line tool.

在本教程中，我们着重介绍了Spring生态系统中一个有趣而罕见的工具–命令行工具。

You can find more information about the project over on GitHub.

你可以在GitHub上找到关于该项目的更多信息。

And, as always, all the code snippets mentioned in the article can be found in our repository.

而且，像往常一样，文章中提到的所有代码片段都可以在我们的资源库中找到。