Spring Boot入门教程：第二章：构建一个RESTful网络服务

这篇文章展示了怎么创建一个显示“Hello, World!”的RESTful网络服务。

本文目标

我们将会构建一个服务，通过http://localhost:8080/greeting接收HTTP的GET请求。

服务会返回一个代表欢迎语的JSON字符串，显示如下：

{“id”:1,“content”:“Hello, World!”}

通过请求字符串中可选项name参数，你可以自定义你的欢迎语，如下所示：

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

name参数会覆盖原来的默认值World，并反映在返回值里面，如下所示：

{“id”:1,“content”:“Hello, User!”}

你需要

• 15分钟左右
• IntelliJ IDEA
• JDK 1.8+
• Maven 3.2+

用Spring Initializr生成项目代码

对于所有的Spring应用，你都可以使用Spring Initializr生成基本的项目代码。Initializr提供了一个快速的方式去引入所有你需要的依赖，并且为你做了很多设置。当前例子只需要一个Spring Web依赖。具体设置如下图

如上图所示，我们选择了Maven作为编译工具。你也可以选择Gradle来进行编译。然后我们分别把Group和Artifact设置为“com.hansy”和“rest-service”。

生成的pom.xml文件内容如下：

<?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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.3.1.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.hansy</groupId>
	<artifactId>rest-service</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>rest-service</name>
	<description>Demo project for Spring Boot</description>

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

	<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>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>

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

</project>

创建一个资源表示类

我们已经配置好了项目和编译系统，接下来我们可以创建网络服务了。

首先我们可以思考一下服务交互过程。

本服务处理访问路径 /greeting下面的GET请求，请求字符串中可能包含name参数。该GET请求必须返回一个响应，其中状态码为 200 OK和内容为JSON格式的字符串。就像下面这样：

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

id字段是欢迎语的唯一识别符，content字段是表示欢迎语的文字。

为了把欢迎语的表示模型化，我们创建一个资源表示类。它是一个POJO类，有id和content字段，构造函数和访问器，如下所示：

package com.hansy.restservice;

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

应用使用Jackson JSON库把Greeting的对象实例自动转换为JSON字符串。Spring Boot的Web Starter默认包含Jackson库。

创建一个资源控制器

在Spring创建RESTful网络服务的实现方式中，HTTP请求是被控制器处理的。这些控制器通过@RestController注解来标识，比如下面的GreetingController，接收路径/greeting上的GET请求，然后返回一个Greeting类的对象实例：

package com.hansy.restservice;

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

import java.util.concurrent.atomic.AtomicLong;

@RestController
public class GreetingController {

    private static final String template = "Hello,%s!";
    private final AtomicLong counter = new AtomicLong();

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

这个控制器看起来简单明了，但是在后台有丰富的操作在进行。我们一步一步的解析。

@GetMapping注解保证路径 /greeting 上的GET请求会映射到greeting()方法上。

还有类似的注解提供给其他HTTP动作使用（例如：对应POST请求的@PostMapping注解）。另外，@RequestMapping注解则可以映射所有的HTTP动作（例如：@RequestMapping(method = RequestMethod.GET)）

@RequestParam注解将请求参数name绑定到greeting()方法的参数name上面。如果请求参数name不存在的话，方法参数name会使用默认值（defaultValue）的“World”。

方法体的流程为创建并返回一个Greeting对象。其中变量id通过AtomicLong类型的counter变量获取累加的新值，变量content则是用name参数配合格式化字符串template而获得的欢迎语。

传统MVC控制器和上面展示的RESTful控制器的关键不同点就是HTTP响应体的创建方式。传统MVC控制器依赖于View技术，在服务器端把Greeting数据渲染为HTML。与之相对的，RESTful控制器则是直接返回Greeting对象，然后Greeting对象会被转换为JSON，并写入HTTP响应体里面。

Spring的@RestController注解标识一个类作为控制器，该控制器的方法的返回值是对象而不是View。@RestController是@Controller和@ResponseBody的结合体。

Greeting对象必须转换为JSON字符串。因为Spring的HTTP消息转换器的默认支持，我们不需要手动去转换。因为classpath自带Jackson 2库，Spring会自动选择MappingJackson2HttpMessageConverter转换器，然后把Greeting实例转换为JSON。

测试服务

运行程序，访问http://localhost:8080/greeting，你会看到：

{
id: 1,
content: “Hello,World!”
}

接着，我们提供一个name请求参数通过访问http://localhost:8080/greeting?name=User。可以看到content的值从"Hello,World!“变为"Hello,User!”。结果如下：

{
id: 2,
content: “Hello,User!”
}

通过这个变化，可以知道GreetingController中的@RequestParam注解得到了预想的结果。name参数首先使用了默认值World，然后可以通过在请求参数里设置name进行覆盖。

我们还可以看到属性id从1变成了2。这说明你从不同的请求访问了同一个GreetingController实例，并且counter字段每次访问都递增。

小结

你已经用Spring开发了一个RESTful网络服务。

源码下载

rest-service

参考资料

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