【Spring官方文档翻译】入门|创建一个RESTful Web服务

imjqy

已于 2023-01-14 13:11:47 修改

阅读量200

点赞数

分类专栏： Spring 文章标签： spring restful

于 2023-01-12 20:52:30 首次发布

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

版权

Spring 专栏收录该内容

1 篇文章 1 订阅

订阅专栏

Getting Started | Building a RESTful Web Service

入门|创建一个RESTful Web服务

你会创建什么
你需要什么
如何完成这个指南
用Spring Initializr开始
创建资源表示类
创建一个资源controller
创建一个可执行JAR包
测试服务
总结
参见

本指南将给你解释 Spring 创建“Hello, World” RESTful Web 服务的流程。

你会创建什么

你会创建一个接受HTTP GET请求的服务，请求在

http://localhost:8080/greeting

它会回复一个（一条问候语的 JSON），如以下列表所示

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

可以使用查询字符串中的可选的name参数自定义问候语，如以下清单所示：
http://localhost:8080/greeting?name=User
参数值将覆盖name的默认值，并反映在响应中，如以下清单所示:

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

你需要什么

大约15分钟
一个最喜欢的文本编辑器或IDE
JDK1.8或更新
Gradel 4+或Maven 3.2+
你也可以直接把代码加载进你的IDE
- Spring Tool Suite
- Intellij IDEA
- VSCode

如何完成这个指南

就像大多的Spring Getting Started指南，你可以从头开始并完成每个步骤，也可以绕过你已经熟悉的基本设置步骤。无论哪种方式，你最终都会得到正常运行的代码。

如果要从头开始，你可以移动到[[用Spring Initializr开始 id=be6b18b8-7c7a-48ab-8a78-703e9f968395]]

如果要跳过基本内容，做下面的事情：

下载并解压这篇指南的资源仓库，或者使用git克隆仓库：git clone https://github.com/spring-guides/gs-rest-service.git
cd进入gs-rest-service/initial
继续跳转到 [[创建资源表示类 id=be6b18b8-7c7a-48ab-8a78-703e9f968395]]

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

用Spring Initializr开始

技术考据癖 | Spring Initializr 的 Initializr 是拼写错误吗？
发布于 2020-11-30 16:08:16
你绝对不是第一个觉得 initializr 是拼写错误的人！
但和大家熟悉的 initializer 不同，Spring Initailizr 的 Initailizr 少了个 e 。Spring 团队为什么要选择这么个解释成本高、还像一个错别字的词当成工具名称呢？
其实这个项目是由 http://www.initializr.com/ 启发而来。initializr 是一个 HTML5 template 生成器，可以帮助开发者快速生成 HTML5 项目，其实和 Spring Initiaizr 的定位是完全一样的，只是面向的开发者不一样。不管怎么样，Initiaizr 这个词已经逐渐被 Spring 用户接受了。毕竟鲁迅说过，错别字嘛，用的多了也就成了标准。

你可以使用这个预先初始化的项目,点击Generate下载一个ZIP文件。这个项目适配了教程里的案例。

如果要手动初始化项目：
1. 导航到https://start.spring.io。这项服务提供了应用程序所需的所有依赖项，并为你完成了大部分设置。
2. 选择Gradle或Maven以及你要使用的语言。本指南假定你选择了Java。
3. 点击Dependencides，选择Spring Web
4. 点击Generate
5. 下载生成的ZIP文件，该文件是根据你的选择配置的Web应用程序的存档。
如果你的IDE具有Spring Initializr集成，则可以在你的IDE中完成此过程。
你也可以从Github fork项目并在你的IDE或其他编辑器中打开它。

创建资源表示类

现在你已经建立了项目并创建了系统，你能创造你的web服务了。

从思考服务交互开始创建Web服务的流程。

服务会处理对/greeting（可以在查询字符串带有name参数）的GET请求。这个GET请求应该返回一个200OK响应码，body中有表示一个问候语的JSON。输出类似于以下：

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

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

创建一个资源表示类来塑造表示问候语的事物。为此，为id和content数据提供一个带有字段、构造函数和访问器的普通的旧式的Java对象（POJO（Plain Old Java Object），指那些没有从任何类继承、也没有实现任何接口，更没有被其它框架侵入的java对象。），如下面的清单所示(来自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中。默认情况下，Jackson被包括在web starter中。

创建一个资源controller

在Spring的构建RESTful Web服务的方法中，HTTP请求由controller处理。这些组件由@RestController注释标识，下面列表中所示的GreetingController(来自src/main/java/com/example/restservice/GreetingController.java))通过返回Greeting类的新实例来处理对/Greting的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));
	}
}

这个contoller是简洁的和简单的，但在它的引擎盖下面还有很多事情发生。我们一步一步地把它分解。

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

还有其他HTTP动词的配套注解(例如，POST的@PostMapping)。还有一个@RequestMapping注解，POST和GET的注解都是从该注解派生而来的，并且可以用作同义词(例如@RequestMapping(method=get))。

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

方法体的实现创建并返回了一个带有id和content属性的Greeting对象。

方法体的实现，基于来自counter的下一个值和使用greeting的模板template格式化name的结果，创建并返回一个具有id和content属性的Greeting对象。

前面所示的传统MVC contoller和RESTful contoller的Web服务contoller之间的一个关键区别是创建HTTP响应体的方式。该RESTful Web服务contoller填充并返回一个Greeting对象，而不是依赖于 view technology在服务器端将问候语数据呈现为HTML。对象数据将以JSON的形式直接写入HTTP响应。

这段代码使用了Spring@RestController注解，它将类标记为controller，其中每个方法都返回一个domain对象（DO（Domain Object）：领域对象，就是从现实世界中抽象出来的有形或无形的业务实体。）而不是一个view。它是同时包含@Controller和@ResponseBody的缩写。

必须将Greeting对象转换为JSON。多亏了Spring的HTTP消息converter支持，你不需要手动执行此转换。因为Jackson 2在类路径上，所以会自动选择Spring的MappingJackson2HttpMessageConverter将Greeting实例转换为JSON。

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

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

这里的main()方法使用了Spring Boot’s SpringApplication.run()方法来启动一个应用程序。你注意到没有一行XML吗？也没有web.xml文件。这个Web应用程序是100%纯Java的，你不必配置任何plumbing or infrastructure。

创建一个可执行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提供一个查询字符串参数name。注意content属性的值如何从Hello，World！变为 Hello，User！，如下面的列表所示：

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

这一更改表明GreetingController中的@RequestParam布置正在按预期工作。名称参数的默认值为World，但该参数可以被查询字符串显式覆盖。

也要注意id属性的值如何已经从1变为了2。这证明你正在跨多个请求working against相同的GreetingController实例，并且其Counter字段在每次调用时都会按预期递增。

总结

祝贺!你刚刚使用Spring开发了一个RESTful web服务。

参见

以下指南也可能有所帮助：