[Spring官方教程] - 构建一个RESTful Web服务

[Jonathan]

本指南将引导你完成用Spring创建一个 “Hello, World” RESTful Web服务。

用Spring构建一个什么服务？

你将会建立一个服务，接受HTTP GET请求，地址是http://localhost:8080/greeting

它将响应一个JSON，如下表所示。

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

可以用查询参数，自定义Content中的内容

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

上面的URL中，name参数值覆盖了默认的World的默认值，响应如下。

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

你需要准备什么？

1. 约15分钟
2. 一个喜欢的文本编辑器或IDE
3. JDK 1.8或更高版本
4. Gradle 4+或Maven 3.2+。
5. 你也可以直接将代码导入你的IDE。
   • Spring Tool Suite (STS)
   • IntelliJ IDEA

如何完成这个指南

像大多数Spring入门指南一样，你可以从头开始，完成每一个步骤，也可以绕过你已经熟悉的基本设置步骤。无论哪种方式，你最终都能获得可以执行的代码。

要从头开始，请跳到下文：从Spring Initialize开始

如果要跳过基本步骤，请执行以下步骤。

• 下载并解压本指南的源码库，或使用Git克隆它：git clone https://github.com/spring-guides/gs-rest-service.git
• cd into gs-rest-service/initial
• 跳到下文: 创建一个 Resource 表示类

当你完成后，你可以对照gs-rest-service/complete中的代码检查你的结果。

从Spring Initialize开始

如果你使用Maven，请访问 Spring Initializr，生成一个带有所需依赖关系（Spring Web）的新项目。

下面的列表显示了选择Maven时创建的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.4.3</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</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>
		</dependency>
	</dependencies>

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

</project>

如果你使用Gradle，请访问Spring Initializr来生成一个具有所需依赖关系（Spring Web）的新项目。

下面的列表显示了当你选择Gradle时创建的build.gradle文件。

plugins {
	id 'org.springframework.boot' version '2.4.3'
	id 'io.spring.dependency-management' version '1.0.11.RELEASE'
	id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-web'
	testImplementation('org.springframework.boot:spring-boot-starter-test')
}

test {
	useJUnitPlatform()
}

手动初始化（可选）

如果你想手动初始化项目，而不是使用前面显示的链接，请按照下面的步骤进行。

1. 导航到 https://start.springboot.io 这项服务拉入你的应用程序所需的所有依赖性，并为你做大部分的设置。
2. 选择Gradle或Maven以及你想使用的语言。本指南假设你选择了Java
3. 点击Dependencies，选择Spring Web
4. 点击 Generate
5. 下载产生的ZIP文件，这是一个用你的选择配置的Web应用程序的压缩包。

如果你的IDE有Spring Initializr集成，你可以从你的IDE完成这个过程。

创建一个 Resource 表示类

现在你已经建立了项目和构建系统，你可以创建你的网络服务。

通过思考服务的交互开始这个过程。

该服务将处理对/greeting的GET请求，可以选择在查询字符串中加入一个名字参数。GET请求应该返回一个200 OK的响应，其主体是代表问候语的JSON。它应该类似于下面的输出。

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

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

为了给问候语表示法建模，创建一个资源表示法类。为此，提供一个普通的Java对象，为id和content数据提供字段、构造器和访问器，正如下面的列表（src/main/java/com/example/restservice/Greeting.java）所示。

package com.example.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。web starter默认包含了 Jackson

创建一个 Resource Controller

在Spring构建RESTful Web服务的方法中，HTTP请求是由控制器处理的。这些组件由@RestController注解来标识，下面列表中的GreetingController（src/main/java/com/example/restservice/GreetingController.java）通过返回一个Greeting类的新实例来处理/greeting的GET请求。

package com.example.restservice;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.web.bind.annotation.GetMapping;
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();

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

这个控制器简明扼要，但在“引擎盖”下有很多事情要做。我们把它一步步地分解。

@GetMapping注解确保HTTP GET对/greeting的请求被映射到greeting()方法。

其他的HTTP动词也有相应的注解（例如：POST的@PostMapping）。还有一个@RequestMapping注解，它们都来自于此，可以作为同义词（例如：@RequestMapping(method=GET)）。

@RequestParam将查询字符串参数name的值绑定到greeting()方法的name参数中。如果请求中没有name参数，则使用World的defaultValue。

方法主体的实现根据 counter的下一个值创建并返回一个新的 Greeting 对象，该对象具有 id 和 content 属性，并通过使用问候 template 格式化给定的 name。

传统的MVC控制器和前面展示的RESTful web服务控制器的一个关键区别是创建HTTP响应体的方式。这个RESTful web服务控制器不是依靠视图技术来执行服务器端的问候数据的HTML渲染，而是填充并返回一个Greeting 对象。该对象数据将以JSON格式直接写入HTTP响应。

这段代码使用了Spring@RestController注解，它将该类标记为控制器，其中每个方法都返回一个域对象，而不是视图。它是包括@Controller和@ResponseBody的简写。

Greeting’对象必须被转换为JSON。由于Spring的HTTP消息转换器的支持，你不需要手动进行这种转换。因为Jackson 2在classpath上，Spring的MappingJackson2HttpMessageConverter被自动选择来将Greeting实例转换为JSON。

@SpringBootApplication是一个方便的注解，添加了以下所有内容。

• @Configuration: 将该类标记为应用程序上下文的Bean定义的来源。
• @EnableAutoConfiguration。告诉Spring Boot开始根据classpath设置、其他Bean和各种属性设置来添加Bean。例如，如果spring-webmvc在classpath上，这个注解将应用程序标记为Web应用程序，并激活关键行为，如设置DispatcherServlet。
• @ComponentScan。告诉Spring寻找com/example包中的其他组件、配置和服务，让它找到控制器。

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

构建一个可执行的JAR

你可以用Gradle或Maven从命令行中运行该应用程序。你也可以构建一个包含所有必要的依赖关系、类和资源的可执行JAR文件并运行它。构建一个可执行的JAR文件可以让你在整个开发生命周期中，在不同的环境中，轻松地将服务作为一个应用来运输、版本和部署，等等。

如果你使用Gradle，你可以通过使用./gradlew bootRun来运行该应用程序。或者，你可以通过使用./gradlew build来构建JAR文件，然后运行JAR文件，如下所示。

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

如果您使用Maven，您可以通过使用./mvnw spring-boot:run来运行该应用程序。或者，您可以用./mvnw clean package构建JAR文件，然后运行JAR文件，如下所示。

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

这里描述的步骤创建了一个可运行的JAR。你也可以建立一个经典的WAR文件。

显示了日志输出。该服务应在几秒钟内启动和运行。

测试服务

现在，服务已经启动，访问http://localhost:8080/greeting，你应该看到。

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

通过访问http://localhost:8080/greeting?name=User提供一个名称查询字符串参数。注意content属性的值是如何从Hello, World！变成Hello, User！的，如下表所示。

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

这个变化表明@RequestParam在GreetingController中的安排是按预期工作的。name参数的默认值是World，但可以通过查询字符串明确地重写。

注意id属性如何从1变成2。这证明你在多个请求中针对同一个GreetingController实例工作，并且它的counter字段在每次调用时都会如期递增。

总结

恭喜你！你刚刚用Spring开发了一个RESTful网络服务。你刚刚用Spring开发了一个RESTful Web服务。

---

原文：https://spring.io/guides/gs/rest-service/