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

本指南将引导你完成用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入门指南一样,你可以从头开始,完成每一个步骤,也可以绕过你已经熟悉的基本设置步骤。无论哪种方式,你最终都能获得可以执行的代码。

从头开始,请跳到下文:从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对象,为idcontent数据提供字段、构造器和访问器,正如下面的列表(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注解来标识,下面列表中的GreetingControllersrc/main/java/com/example/restservice/GreetingController.java)通过返回一个Greeting类的新实例来处理/greetingGET请求。

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参数,则使用WorlddefaultValue

方法主体的实现根据 counter的下一个值创建并返回一个新的 Greeting 对象,该对象具有 idcontent 属性,并通过使用问候 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!"}

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

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

总结

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


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