译 2.Spring构建REST Web Service

上篇文章我们已经对Spring 已经有了一个初步的认识，接下来本篇文章我们将继续一起在官网学习新技术。 原文地址：https://spring.io/guides/gs/rest-service/

---

本指南指导您使用Spring创建一个“Hello World”REST Web Service 的过程。

1. 你将会建立什么？

Tips: 上面已经提到，我们将使用Spring创建一个“Hello World”REST Web服务的过程，但是最终的效果是什么样呢？

我们将构建一个接受HTTP GET请求的服务：

http://localhost:8080/greeting

当我们发出上面的Http Get 请求后，会响应返回下面的JSON 内容。

{"id":1,"content":"Hello, World!"}

我们也可以带一个参数进行请求

http://localhost:8080/greeting?name=User

 Name参数值重写“Word”的默认值，并反映在响应中：

{"id":1,"content":"Hello, User!"}

2. 你将需要准备什么？

• 大约十五分钟

• 一个喜欢的文本编辑器或者IDE

• JDK 1.8 or later

• Gradle 4+ or Maven 3.2+

• You can also import the code straight into your IDE:

  • Spring Tool Suite (STS)

  • IntelliJ IDEA

3.如何完成本指南?

像大多数Spriing 入门指南一样，你可以从头开始，完成每一步，或者你可以绕过已经熟悉的基本设置步骤。不管怎样，你最终都会得到工作代码

3.1 获取工作代码

  a.使用Maven构建

  b. 使用Gradle构建

  c. 使用IDE构建

• 阅读怎么使用 Spring Tool Suite.构建

• 阅读怎么使用  IntelliJ IDEA 构建

  d.  点击下载 然后 解压仓库源码

  e. 使用git 克隆

git clone https://github.com/spring-guides/gs-rest-service.git

上面有五种方法，但是由于之后我们会经常使用IDE来完成这些操作，所以这里我们使用IDE 来构建入门指南项目

3.1.1 用STS开始入门指南

本指南引导您使用Spring工具套件（STS）构建一个入门指南。

3.1.1.1 你将会构建什么？

您将选择Spring指南并将其导入Spring Tool Suite。然后你可以阅读指南，处理代码，运行项目。

3.1.1.2 你需要什么？

• 大约15分钟

• Spring Tool Suite (STS)

• JDK 8 或者更高

3.1.1.3 安装STS

   如果你还没有安装STS，请访问上面的链接。从那里，您可以下载一个副本为您的平台。要安装它，只需解压缩下载的存档文件。

   当你完成后，继续登陆 STS

3.1.1.4 导入入门指南

   使用STS启动并运行，从文件菜单打开Import Spring Getting Started Content 向导。

 点击File ——> New ————> Import Spring Geting Started Content

然后会弹出来一个窗口向导，将为您提供从Spring网站搜索和挑选任何已发布指南的机会。

你可以浏览列表，或者输入搜索词来立即过滤选项。

当提供即时搜索结果时，该标准适用于标题和描述。支持通配符。

输入rest ，选择 Rest Service ,点击Finish 

您可以选择Maven或Gradle作为构建系统来使用。

您还可以决定是否抓取初始代码集、完成代码集，或两者兼而有之。

对于大多数项目，

• （initial）初始代码集是一个空的项目，使得您可以通过指南复制和粘贴您的方式
•   (Complete)完整的代码集是来自已经进入的指南的所有代码。如果你抓住这两个，你可以比较你的工作与指南的差异。

最后，你可以让STS向网站上的指南打开浏览器标签。这会让你在不离开STS的情况下通过向导工作。

 STS将在您的工作区中创建两个新项目，导入消耗REST代码库（初始和完整），并在STS中打开浏览器选项卡，如下所示：

 

Tips: 

gs-rest-service-complete 是完成后的项目

gs-rest-service-initial 是初始化一个空的项目

3.1.2 用Intellij Idea 开始入门指南

 本指南指导您使用Intellij Idea 构建一个入门指南。

3.1.2.1 你将会构建什么？

你会选择一个Spring指南并导入到iTeliJ的想法中。然后你可以阅读指南，处理代码，运行项目。

3.1.2.2 你需要准备什么？

• 15分钟

• IntelliJ IDEA

• JDK 6  或者更高

3.1.2.3 安装 IntelliJ IDEA

如果你还没有安装 IntelliJ IDEA (Ultimate Edition) ，请访问上面的链接。从那里，您可以下载一个副本为您的平台。要安装它，只需解压缩下载的存档文件。

 当你完成后，继续启动Intellij IDEA

3.1.2.4 导入入门指南

要导入现有的项目，需要一些代码，

点击下载

或者使用Git 克隆或复制其中一个入门指南，例如REST服务指南：

git clone https://github.com/spring-guides/gs-rest-service.git

下载解压后如图所示

使用Intellij IDEA 启动和运行，点击欢迎屏幕上的导入项目，或在主菜单上打开文件：

 在弹出对话框中，确保在完整文件夹下选择Maven的POM.xml或Gradle的build.gradle文件：

这里我们选择build.gradle

Intellij IDEA 将创建一个项目，所有的代码从指南准备运行。

保持默认，点击OK

构建完成后如图所示

3.2 创建资源表示类

 既然已经建立了项目并建立了系统，就可以创建Web服务。

 通过考虑服务交互来开始这个过程。

服务将处理查询t /greeting  GET 请求，可选地在查询字符串中使用name参数。GET请求应该返回一个200 OK响应，其中JSON在表示greetin的主体中。它应该看起来像这样：

{
    "id": 1,
    "content": "Hello, World!"
}

ID字段是问候语的唯一标识符，content是问候语的文本表示。

 为了建模问候语表示，您创建一个资源表示类。提供一个字段，构造函数普通java对象，并为ID和content数据访问：

src/main/java/hello/Greeting.java

package hello;

public class Greeting {
    private final long id;
    private final String content;

    public Greeting(long id, String content) {
        this.id = id;
        this.content = content;
    }

    public long getId() {
        return id;
    }
    public String getContent() {
        return content;
    }
}

 正如您在下面的步骤中看到的，Spring使用Jackson JSON库自动将问候类型的实例封送到JSON中。

 接下来，创建将为这些问候服务的资源控制器。

3.3 创建资源Controller

在Spring构建REST Web服务的方法中，HTTP请求由控制器处理。这些组件很容易被@ RESTController注释标识，下面的GreetingController通过返回Greeting 类的新实例来处理GET请求/greeting：

 src/main/java/hello/GreetingController.java

package hello;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {
    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();

    @RequestMapping("/greeting")
    public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) {
        return new Greeting(counter.incrementAndGet(),
                            String.format(template, name));
    }
}

这个控制器简洁明了，但引擎盖下还有很多事情要做。让我们一步一步地打破它。

 @RequestMapping  注解 确保将HTTP请求 /greeting映射到 greeting()方法。

上面的示例不指定GET、PUT、POST等等，因为@RequestMapping 默认映射所有HTTP操作。使用@RequestMapping（Method= GET）来缩小此映射。

@RequestParam将查询字符串参数name 的值绑定到greeting（）方法的name参数中。 如果请求中缺少name参数，则使用“World”的默认值。

方法体的实现基于计数器的下一个值创建并返回一个带有id和content属性的新Greeting对象，并使用问候template 格式化给定name。

传统的MVC控制器和上面的RESTful Web服务控制器之间的一个主要区别在于HTTP响应主体的创建方式。

这个RESTful Web服务控制器只需填充并返回一个Greeting对象，而不是依赖视图技术将问候数据的服务器端呈现呈现给HTML。

对象数据将作为JSON直接写入HTTP响应。

此代码使用Spring 4的新的@RestController注释，该注释将类标记为控制器，其中每个方法都返回一个域对象而不是视图。 它是@Controller和@ResponseBody的缩写。

@RestController = = @Controller + @ResponseBody 

Greeting对象必须转换为JSON。 由于Spring的HTTP消息转换器支持，您不需要手动执行此转换。

由于Jackson 2位于classpath中，因此会自动选择Spring的MappingJackson2HttpMessageConverter将Greeting实例转换为JSON。

3.4 使应用程序可执行

虽然可以将此服务作为传统WAR文件打包以部署到外部应用程序服务器，但下面演示的更简单的方法会创建独立应用程序。

您将所有内容打包到一个单独的，可执行的JAR文件中，由一个良好的旧Java main（）方法驱动。

一路上，您使用Spring的支持将Tomcat servlet容器作为HTTP运行时嵌入，而不是部署到外部实例。

src/main/java/hello/Application.java

package hello;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
} 

SpringBootApplication是一个方便的注解，它增加了以下所有内容：

• @Configuration将类标记为应用程序上下文的bean定义的来源。
• @EnableAutoConfiguration通知Spring Boot根据类路径设置，其他bean和各种属性设置开始添加bean。
• 通常你会为Spring MVC应用程序添加@EnableWebMvc，但Spring Boot在类路径中看到spring-webmvc时会自动添加。 这将该应用程序标记为Web应用程序并激活关键行为，例如设置DispatcherServlet。
• @ComponentScan告诉Spring在hello包中查找其他组件，配置和服务，以便找到控制器。

main（）方法使用Spring Boot的SpringApplication.run（）方法启动应用程序。你有没有注意到没有一行XML？ 没有web.xml文件。这个Web应用程序是100％纯Java，您不必处理配置任何管道或基础设施。

3.5 构建一个可执行的JAR

您可以使用Gradle或Maven从命令行运行应用程序。 或者您可以构建一个包含所有必需的依赖项，类和资源的可执行JAR文件，并运行该文件。 这使得在整个开发生命周期内跨越不同环境等，将服务作为应用程序发布，版本化和部署变得非常容易。

如果您正在使用Gradle，则可以使用./gradlew bootRun运行该应用程序。 或者您可以使用./gradlew构建构建JAR文件。 然后你可以运行JAR文件：

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

如果您使用的是Maven，则可以使用./mvnw spring-boot：run来运行该应用程序。 或者，您可以使用./mvnw clean包构建JAR文件。 然后你可以运行JAR文件：

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

上述过程将创建一个可运行的JAR。 您也可以选择构建经典的WAR文件。

记录输出显示。 该服务应该在几秒钟内启动并运行。

3.6 测试 service

 现在这个service已经启动，我们访问 http://127.0.0.1:8080/greeting 你将会看到这样的结果

{"id":1,"content":"Hello, World!"}

提供一个name参数进行查询，访问 http://localhost:8080/greeting?name=User

{"id":2,"content":"Hello, User!"}

注意content 文本内容已经从 "Hello ,World!" 变成了" Hello, User!"

此更改演示了GreetingController中的@RequestParam排列按预期工作。 name参数已被赋予默认值“World”，但始终可以通过查询字符串显式覆盖。

还要注意id属性如何从1更改为2.这证明您正在针对多个请求中的同一个GreetingController实例工作，并且它的计数器字段按照预期在每次调用时递增。

恭喜！ 您刚刚用Spring开发了一个RESTful Web Service。

源码下载：https://github.com/geekxingyun/JavaEE-Framework-Sample/tree/master/Spring-Build-Restful-Web-Service-Sample