[SpringBoot guides系列翻译]SpringBoot构建RESTful程序入门
构建一个RESTful的WebService
这个指南将带你用Spring创建一个RESTful的helloworld程序。
你将完成
在下面地址上创建一个接收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分钟
- 你喜欢的文本编辑器(我这里用了vscode)或者IDE
- jdk1.8+
- Gradle 4+ 或 Maven 3.2+
- 你也可以直接把你的代码导入到你的ide中
- Spring Tool Suite
- IntelliJ IDEA
如何完成这份指南
其他的不说了,一步一步来,直接看通过Maven
通过Gradle
忽略~~
通过Maven
这里演示如何用Maven来构建你的spring应用,如果你不熟悉怎么使用Maven,可以看这里。
创建项目结构:
mkdir -p src/main/java/hello
然后定义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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.springframework</groupId>
<artifactId>gs-rest-service</artifactId>
<version>0.1.0</version>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.5.RELEASE</version>
</parent>
<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>
<dependency>
<groupId>com.jayway.jsonpath</groupId>
<artifactId>json-path</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
<properties>
<java.version>1.8</java.version>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
有几点可以说一下:
- 第一是固定的modelVersion=4.0
- 第二是几个groupId都是org.springframework.boot,这个我们一般写自己的公司或者组织相关的倒序域名,这里因为是spring自己的教程,所以都是一样的org.springframework.boot。
spring-boot-starter-parent
提供了依赖和插件管理的功能。spring-boot-starter-web
用于构建restful的webapi以及springmvc应用。,spring-boot-starter-test
用于测试,包含了JUnit,Hamcrest,Mockito。这3个包算是完整的项目基本上都要用到的。- 然后是spring-boot-maven-plugin插件。他提供了很多便捷的特性。
- 把用到的所有依赖打包成一个整体,这样方便服务的执行以及分发。
- 把
public static void main()
标记成可执行类。 - 提供了内置的依赖解析器用于设置相符的Spring Boot依赖的版本号。
通过IDE
介绍了如何使用intellij IDEA,占个位,忽略先。
创建一个资源表示类
定义好了pom就可以开始写代码了。
先想一下服务的交互是怎么样的。
服务处理/greeting
过的来的get
请求,可能会有一个name
参数。然后结果返回一个json以及200状态码。json如下。
{
"id": 1,
"content": "Hello, World!"
}
id
字段作为一个唯一表示符,content
表示内容。
下面创建一个java类来表示这个类。包含字段,构造函数,两个get方法。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库把对象转换成JSON。
接下来创建控制器。
创建一个资源控制器
Spring用控制器来处理HTTP请求。用@RestController
注解来标识。@RequestMapping
注解申明请求路径/greeting
,然后返回一个Greeting
的实例。下面示例代码。
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()
方法。
上面的
@RequestMapping
方法注解里面没有指定get
或者put
或者post
,所以,默认是接收所有方法。如果需要,可以按如下指定为只接收get方法@RequestMapping(method=GET)
@RequestParam
把请求过来的name
参数绑定到方法的name
参数上,如果没有传值,默认用defaultValue
指定的world
。
返回的Greeting
对象的id
由counter
构造,content
由template
构造。
与传统的MVC 里面的控制器对比,RESTful服务的HTTP请求的Response由控制器直接返回一个Greeting
对象,而传统的MVC里面的控制器还需要依赖视图渲染技术进行服务端的渲染技术返回html。
代码使用Spring 4的@RestController注解,把类标记成控制器并且返回领域对象而不是一个视图。可以算是@Controller
和 @ResponseBody
的合体。
Greeting
对象需要转换成json对象。Spring使用MappingJackson2HttpMessageConverter
选择Jackson2
作为默认的库把Greeting
对象转成json。
使你的程序可运行
虽然把程序打包成一个war文件,然后部署到外部的服务器是可行的。下面演示一种更简单的方式。把程序打包成一个可执行的jar文件,通过main()
方法驱动。通过这种方式,使用Tomcat服务器来托管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);
}
}
什么是bean。简单来说是由Spring的 IoC容器控制的,并且是程序的骨架。
@SpringBootApplication
是一个简便的注解,它添加了下面这些东西:
@Configuration
定义这个类是bean的来源类。@EnableAutoConfiguration
告诉SpringBoot去添加基于classpath设置的或者是其他的bean,以及各种属性。- 通常你可能会添加
@EnableWebMvc
注解在Spring MVC程序中。但是SpringBoot会自动为你添加,如果在classpath里面有spring-webmvc。这个标记把程序标记成web应用。激活并设置比如DispatcherServlet
之类的核心行为。 @ComponentScan
告诉Sping 去查找hello
包里面的其他的组件,配置服务,包括控制器。
mian()
方法使用SpingBoot的 SpringApplication.run()
方法来启动应用。是的,没有写xml配置,这是一个纯粹的java程序。
编译生成可执行的jar
你可以通过命令行的Maven或者Gradle来运行程序。或者你可以把程序编译生成一个可执行的jar文件。这个jar文件包含了必须的依赖,类,资源文件。这方便于分发部署。
mvn spring-boot:run
命令来运行程序。
mvn clean package
命令来打包程序生成jar。然后使用
java -jar target/gs-rest-service-0.1.0.jar
来运行。第一次需要要从Maven下载dependency,所以package过程有点长。。。喝杯☕️。
试试这个服务
启动默认是8080端口。访问http://localhost:8080/greeting,将会看到
{"id":1,"content":"Hello, World!"}
提供一个name
参数http://localhost:8080/greeting?name=User,content就会变掉。
{"id":2,"content":"Hello, User!"}
总结
恭喜,你已经学会~。