入门 | 构建RESTful Web 服务

您将构建的内容

您将构建一个服务，该服务将接受https://127.0.0.1:8080/greeting上的HTTP GET请求。

它将返回问候语的JSON表示，如下所示

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

您可以使用查询字符串中的可选name参数自定义问候语，如下所示

https://127.0.0.1:8080/greeting?name=User

name参数值将覆盖默认值World，并反映在响应中，如下所示

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

您需要什么

大约15分钟
您最喜欢的文本编辑器或IDE
Java 17或更高版本
Gradle 7.5+ 或 Maven 3.5+
您也可以直接将代码导入您的IDE

如何完成本指南

与大多数Spring 入门指南一样，您可以从头开始并完成每个步骤，也可以跳过您已经熟悉的基本设置步骤。无论哪种方式，您最终都会得到可运行的代码。

要从头开始，请继续执行从Spring Initializr开始。

要跳过基础步骤，请执行以下操作

下载并解压缩本指南的源代码存储库，或使用Git克隆它：git clone https://github.com/spring-guides/gs-rest-service.git
进入gs-rest-service/initial目录
跳至创建资源表示类。

完成后，您可以将您的结果与gs-rest-service/complete中的代码进行比较。

从Spring Initializr开始

您可以使用此预初始化项目并点击“生成”以下载ZIP文件。此项目已配置为适合本教程中的示例。

要手动初始化项目

导航到https://start.spring.io。此服务将引入应用程序所需的所有依赖项，并为您完成大部分设置工作。
选择Gradle或Maven以及您要使用的语言。本指南假设您选择了Java。
点击依赖项并选择Spring Web。
点击生成。
下载生成的ZIP文件，这是一个使用您选择的选项配置的Web应用程序的存档。

如果您的IDE具有Spring Initializr集成，则可以从您的IDE完成此过程。

您也可以从Github分叉项目并在您的IDE或其他编辑器中打开它。

创建资源表示类

现在您已经设置了项目和构建系统，您可以创建Web服务了。

首先考虑服务交互。

该服务将处理/greeting的GET请求，查询字符串中可以选择包含name参数。GET请求应返回带有正文中JSON的200 OK响应，它应该类似于以下输出

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

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

要建模问候语表示，请创建一个资源表示类。为此，请为id和content数据提供一个Java记录类，如下所示（来自src/main/java/com/example/restservice/Greeting.java）

package com.example.restservice;

public record Greeting(long id, String content) { }

此应用程序使用Jackson JSON库自动将Greeting类型的实例编组到JSON中。Jackson默认情况下包含在Web启动器中。

创建资源控制器

在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注解确保将对/greeting的HTTP GET请求映射到greeting()方法。

其他HTTP动词也有配套注解（例如，@PostMapping用于POST）。还有一个@RequestMapping注解，它们都从中派生，并且可以用作同义词（例如，@RequestMapping(method=GET)）。

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

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

传统MVC控制器和前面显示的RESTful Web服务控制器之间的关键区别在于创建HTTP响应正文的方式。此RESTful Web服务控制器不是依赖于视图技术来将问候语数据到HTML的服务器端呈现，而是填充并返回一个Greeting对象。对象数据将直接作为JSON写入HTTP响应。

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

必须将Greeting对象转换为JSON。由于Spring的HTTP消息转换器支持，您无需手动执行此转换。因为Jackson 2位于类路径上，所以Spring的MappingJackson2HttpMessageConverter将自动选择来将Greeting实例转换为JSON。

运行服务

Spring Initializr为您创建了一个应用程序类。在这种情况下，您无需进一步修改该类。以下列表（来自src/main/java/com/example/restservice/RestServiceApplication.java）显示了应用程序类

package com.example.restservice;

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

@SpringBootApplication
public class RestServiceApplication {

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

}

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

@Configuration：将类标记为应用程序上下文的bean定义的来源。
@EnableAutoConfiguration：告诉Spring Boot根据类路径设置、其他bean和各种属性设置开始添加bean。例如，如果spring-webmvc位于类路径中，则此注解将应用程序标记为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文件。

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

测试服务

服务启动后，访问https://127.0.0.1:8080/greeting，您应该看到

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

通过访问https://127.0.0.1:8080/greeting?name=User提供name查询字符串参数。请注意content属性的值如何从Hello, World!更改为Hello, User!，如下所示

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

此更改表明GreetingController中的@RequestParam安排按预期工作。name参数已赋予默认值World，但可以通过查询字符串显式覆盖。

还要注意id属性如何从1更改为2。这证明您正在跨多个请求处理同一个GreetingController实例，并且其counter字段正在按预期在每次调用时递增。

总结

恭喜！您刚刚使用Spring开发了一个RESTful Web服务。

另请参阅

以下指南可能也有帮助

想要编写新的指南或为现有指南做出贡献？请查看我们的贡献指南。

所有指南均以ASLv2许可证发布代码，并以署名-非衍生作品创作共用许可证发布编写内容。

构建RESTful Web 服务