Spring 指南(构建RESTful Web服务)
构建RESTful Web服务
本指南将引导你完成使用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
参数值将覆盖默认值“World”并反映在响应中:
{"id":1,"content":"Hello, User!"}
需要什么
- 大约15分钟
- 最喜欢的文本编辑器或IDE
- JDK 1.8或更高版本
- Gradle 4+或Maven 3.2+
你还可以将代码直接导入IDE:
- Spring Tool Suite(STS)
- IntelliJ IDEA
如何完成本指南
请执行以下操作:
下载并解压缩本指南的源存储库,或使用Git克隆它:
git clone https://github.com/spring-guides/gs-rest-service.git
- 进入
gs-rest-service/initial
完成后,你可以根据gs-rest-service/complete
中的代码检查结果。
创建资源表示类
现在你已经设置了项目和构建系统,你可以创建Web服务。
通过考虑服务交互来开始这个过程。
该服务将处理/greeting
的GET
请求,可选地在查询字符串中使用name
参数,GET
请求应返回200 OK
响应,其中JSON位于表示问候语的正文中,它应该看起来像这样:
{ "id": 1, "content": "Hello, World!" }
id
字段是问候语的唯一标识符,content
是问候语的文本表示。
要为问候语表示建模,需要创建一个资源表示类,提供一个普通的java对象,其中包含id
和content
数据的字段、构造函数和访问器:
src/main/java/hello/Greeting.java
package hello; 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; } }正如你在下面的步骤中看到的那样,Spring使用Jackson JSON库自动将
Greeting
类型的实例编组为JSON。接下来,你将创建将为这些问候语提供服务的资源控制器。
创建资源控制器
在Spring构建RESTful Web服务的方法中,HTTP请求由控制器处理,这些组件可以通过@RestController
注解轻松被识别,下面的GreetingController
通过返回Greeting
类的新实例来处理/greeting
的GET
请求:
src/main/java/hello/GreetingController.java
package hello; import java.util.concurrent.atomic.AtomicLong; import org.springframework.web.bind.annotation.RequestMapping; 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(); @RequestMapping("/greeting") public Greeting greeting(@RequestParam(value="name", defaultValue="World") String name) { return new Greeting(counter.incrementAndGet(), String.format(template, name)); } }
这个控制器简洁并简单,但它的内部有很多东西,让我们一步一步地分解它。
@RequestMapping
注解确保对/greeting
的HTTP请求映射到greeting()
方法。
GET
与PUT
、POST
等,因为@RequestMapping
默认映射所有HTTP操作,使用@RequestMapping(method=GET)
缩小此映射范围。@RequestParam
将查询字符串参数name
的值绑定到greeting()
方法的name
参数中,如果请求中不存在name
参数,则使用“World”的defaultValue
。
方法体的实现基于counter
的下一个值和使用问候语template
格式化给定name
创建并返回具有id
和content
属性的新Greeting
对象。
传统MVC控制器和上面的RESTful Web服务控制器之间的关键区别在于创建HTTP响应体的方式,这个RESTful Web服务控制器只是填充并返回一个Greeting
对象,而不是依赖于视图技术来执行问候数据到HTML的服务器端渲染,对象数据将作为JSON直接写入HTTP响应。
此代码使用Spring 4的新@RestController
注解,它将类标记为控制器,其中每个方法都返回一个域对象而不是一个视图,这是@Controller
和@ResponseBody
汇总在一起的简写。
Greeting
对象必须转换为JSON,由于Spring的HTTP消息转换器支持,你无需手动执行此转换,因为Jackson 2在类路径上,所以会自动选择Spring的MappingJackson2HttpMessageConverter
将Greeting
实例转换为JSON。
使应用程序可执行
虽然可以将此服务打包为传统的WAR文件以便部署到外部应用程序服务器,但下面演示的更简单的方法创建了一个独立的应用程序,将所有内容打包在一个可执行的JAR文件中,由Java的main()
方法驱动,在此过程中,你使用Spring的支持将Tomcat servlet容器嵌入为HTTP运行时,而不是部署到外部实例。
src/main/java/hello/Application.java
package hello; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }
@SpringBootApplication
是一个方便的注解,添加了以下所有内容:
@Configuration
将类标记为应用程序上下文的bean定义源。@EnableAutoConfiguration
告诉Spring Boot根据类路径设置、其他bean和各种属性设置开始添加bean。- 通常你会为Spring MVC应用添加
@EnableWebMvc
,但Spring Boot会在类路径上看到spring-webmvc时自动添加它,这会将应用程序标记为Web应用程序并激活关键行为,例如设置DispatcherServlet
。 @ComponentScan
告诉Spring在hello
包中查找其他组件、配置和服务,允许它找到控制器。
main()
方法使用Spring Boot的SpringApplication.run()
方法来启动应用程序,你是否注意到没有一行XML?也没有web.xml文件,此Web应用程序是100%纯Java,你无需处理配置任何管道或基础结构。
构建可执行的JAR
你可以使用Gradle或Maven从命令行运行该应用程序,或者,你可以构建一个包含所有必需依赖项、类和资源的可执行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
正在按预期工作,name
参数的默认值为“World”,但始终可以通过查询字符串显式覆盖。
另请注意id
属性如何从1
更改为2
,这证明你正在针对相同的GreetingController实例跨多个请求,并且其counter
字段在每次调用时按预期递增。