使用Maven构建REST风格的网络服务

这篇指南将帮助你用Spring创建一个REST风格的网络服务

你将构建什么

你将构建一个服务，该服务将从如下地址接收HTTP GET请求：

http://localhost:8080/greeting

然后收到一个JSON表示的响应：

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

在请求字符串中，你也可以用可选的的name参数来自定义greeting url

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

name参数的值将重写默认值”World”,并反映在相应结果上

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

你需要什么

大约15分钟

一个中意的文本编辑器或者IDE

JDK1.8或更高版本

Maven 3.0+

你也可以从这篇指南导入代码，而且可以在Spring工具包（STS）中直接查看网页，通过STS成为你的工作方式

怎样完成这个指南

你可以从从头开始完成每一步，或者你也可以跳过你熟悉的步骤。无论哪种方式，都是以代码能运行结束

- 从头开始，请从开始一步步构建

- 跳过基本步骤，按照如下步骤操作：

- 下载并且解压资源那文件，或者用Git克隆git clone https://github.com/spring-guides/gs-rest-service.git ，将代码导入到Eclipse直接运行gs-rest-service-complete工程

构建过程

创建工程

首先用Eclipse创建一个Maven QuickStart工程，修改pom文件如下

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion>

<groupId>org.springframework</groupId>
<artifactId>gs-rest-service</artifactId>
<version>0.1.0</version>

<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.4.3.RELEASE</version>
</parent>

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.jayway.jsonpath</groupId>
<artifactId>json-path</artifactId>
<scope>test</scope>
</dependency>
</dependencies>

<properties>
<java.version>1.8</java.version>
</properties>

<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>

<repositories>
<repository>
<id>spring-releases</id>
<url>https://repo.spring.io/libs-release</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-releases</id>
<url>https://repo.spring.io/libs-release</url>
</pluginRepository>
</pluginRepositories>
</project>

Spring Boot Maven插件提供许多方便的功能：

- classpath集成所有需要的jar包，并且构建一个唯一的，可运行的jar包。它能让运行和传输你的服务更方便

- 查找

public static void main()

方法，作为可执行类的入口

- 提供内置的依赖项解析器，设置版本号去匹配Spring Boot依赖。可以提供任意版本，Spring Boot也有默认的选择

建立class源文件

现在已经创建了maven工程，接下来创建web服务。开始之前，首先考虑一下服务的交互过程。该服务将处理来自

/greeting

的

GET

请求，请求URL中可以有一个可选的

name

参数。

GET

请求应该返回

200 OK

响应，并且返回一个JSON格式的消息体，消息内容如下：

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

id代表greeting的唯一标识，content是greeting的文本表达表示

为了将greeting的文本表示模块化，要创建一个class资源文件，该class的java源文件路径

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;
}
}

创建controller资源

在该服务的构建过程中，来自外部的HTTP请求是被controller处理的。这个组件容易给被

@RestController

识别，

GreetingController

处理来自

/greeting

的

GET

请求，返回一个

Greeting class

实例,

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));
}
}

GreetingController

非常简洁，但是后台实现了许多功能，让我们一步一步拆解分析。

@RequestMapping

注解确保来自

/greeting

的HTTP请求被映射到

greeting()

方法

到现在为止，上边的例子没有定义

GET

，

PUT

，

POST

方法，因为

@RequestMapping

注解默认映射所有类型的HTTP请求，使用

@RequestMapping(method=GET)

方法可以缩小映射范围

@RequestParam

注解绑定请求字符串的

name

参数 传值到

greeting()

方法的

name

参数。 该请求参数被明确的标记为可选（默认required=true），如果该参数不存在，使用默认的

World

;方法体的实现创建并返回了一个Greeting对象，id属性基于计数器

counter

的下一个值，content属性的值使用template模板

Rest风格的Web服务控制器和传统的MVC控制器的最关键不同在于HTTP响应体创建的方式。相比于传统方式依赖视图技术完成服务端的数据转换到HTML，REST风格的WEB服务只是简单地填入并返回一个Greeting对象。该对象的数据将被直接以JSON方式返回给HTTP请求

使用

@RestController

注解标记的类将作为一个控制器，每个方法返回一个代替原来的视图。它是

@Controller

和

@ResponseBody

放在一起的一个简化处理

Greeting

对象必须被转化成

JSON

格式， 由于Spring对HTTP消息转换的支持，不需要开发人员手动处理。 因为Jackson 2 在classpath路径上, Spring的

MappingJackson2HttpMessageConverter

被自动选择用来将

Greeting

对象转换为JSON实例

确保应用可执行

虽然可以用传统的war包方式打包文件，并部署到一个外部服务器中,下边展示了一个更简单的方法创建一个单点的应用。将所有的内容打包到一个单独的可执行jar包中，通过传统的

main()

方法执行。在打包执行的过程中，实际上使用了Spring内置的Tomcat作为运行HTTP运行时的Servlet容器，来替代部署一个外部实例。

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基于classpath、其他bean设置、其他属性设置去开始添加bean

- 一般来讲对于一个Spring应用，需要添加

@EnableWebMvc

注解，但是当看到spring-webmvc在classpath中，Spring Boot会自动添加这个注解。这个注解标记该应用为Web应用并激活像

DispatcherServlet

设置这样的关键动作。

-

@ComponentScan

告诉Spring在

hello

包中去查找其他的组件、配置和服务，允许发现其控制器

main()

方法使用Spring Boot的

SpringApplication.run()

方法去运行应用。不知道你注意到没有，在这个web应用中没有任何一个XML配置，这个web应用是百分百的java用用，不需要处理任何其它的东西

构建可执行的jar

该应用可以在命令行用maven命令运行。也可以将所有需要的依赖，class文件和资源打包成可执行的jar包再运行。使用maven去打包的命令为

mvn clean package

，然后可以用java命令运行jar包

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

说明

本文翻译自

http://spring.io/guides/gs/rest-service/

部分内容有删减