spring-boot 构建一个restful的web服务

构建一个restful的web服务

这篇文章告诉你如何通过spring创建一个”hello world”的restful的web服务

你会建立什么

你会建立一个接受HTTP GET请求的服务:

1
http://localhost:8080/greeting

问候语以JSON的形式响应:

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

你可以自定义问候语与一个可选 name 参数的查询字符串:

1
http://localhost:8080/greeting?name=User

这个name参数值覆盖默认的”World”,并反射到响应中:

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

你需要什么

  • 15分钟时间
  • 一个你喜欢的文本编辑器或者IDE(集成开发环境)
  • JDK 1.8或以上版本
  • Gradle 2.3+ 或者 Maven 3.0+
  • 你也可以从本指南中导入代码,以及查看该网页直接进入Spring Tool Suite(STS),并通过它来进行工作。

如何完成本指南

像大多数的 Spring Getting Started guides,你可以从头开始并完成每一个步骤,或者可以避开这个已经熟悉的基本设置步骤。无论以那种方式完成你的代码。

从头开始,请点击这里通过Gradle

跳过基础,进行如下操作:

  • 下载并解压源代码,或者使用git克隆它:
    git clone https://github.com/spring-guides/gs-rest-service.git
  • 进入 gs-rest-service/initial
  • 直接跳到 创建资源类

当你完成,你可以检查你的结果和代码在
gs-rest-service/complete

通过Gradle构建

首先你先建立一个基本的构建脚本,您可以使用spring在任何你喜欢的构建系统上构建app,但你的code需要用Gradle和Maven来运行。如果你不熟悉,要么,请参阅通过Gradle构建Java项目 或者 通过Maven构建Java项目

创建目录结构

在你选择的项目目录,创建如下的子目录结构,例子,在*nix系统通过 mkdir -p src/main/java/hello创建:

1
2
3
4
└── src
└── main
└── java
└── hello

创建Gradle构建文件

下面是最初的构建文件

build.gradle

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath("org.springframework.boot:spring-boot-gradle-plugin:1.4.1.RELEASE")
}
}
apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'spring-boot'
jar {
baseName = 'gs-rest-service'
version = '0.1.0'
}
repositories {
mavenCentral()
}
sourceCompatibility = 1.8
targetCompatibility = 1.8
dependencies {
compile("org.springframework.boot:spring-boot-starter-web")
testCompile('org.springframework.boot:spring-boot-starter-test')
}

这是Spring Boot gradle plugin 提供了许多快捷特性:

  • 它收集的类路径上所有jar文件,并建立一个单一的可运行的jar,这使得它更方便地执行和传输你的服务
  • 它搜索 public static void main()方法来标示可运行的类
  • 它提供了一个内置的依赖解析器,用于设置版本号以匹配Spring Boot dependencies。您可以覆盖任何你想要的版本,但它会默认引导的选择版本。

通过Maven构建

首先,你建立一个基本的构建脚本。你可以使用spring在任何你喜欢的构建系统上构建app,但是你的code必须通过Maven来运行,如果你还不熟悉Maven,请参阅Building Java Projects with Maven

创建目录结构

在你选择的项目目录,创建如下子目录结构;例子,在 *nix 系统通过mkdir -p src/main/java/hello 创建:

1
2
3
4
└── src
└── main
└── java
└── hello

pom.xml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
<?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>1.4.1.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>
<repositories>
<repository>
<id>spring-releases</id>
<url>https://repo.spring.io/libs-release</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-releases</id>
<url>https://repo.spring.io/libs-release</url>
</pluginRepository>
</pluginRepositories>
</project>

这是Spring Boot Maven plugin/提供许多快捷特性:

  • 它收集的类路径上所有jar文件,并建立一个单一的可运行的jar,这使得它更方便地执行和传输你的服务
  • 它搜索 public static void main()方法来标示可运行的类
  • 它提供了一个内置的依赖解析器,用于设置版本号以匹配Spring Boot dependencies。您可以覆盖任何你想要的版本,但它会默认引导的选择版本。

通过IDE构建

创建资源类

现在你已经设置了该项目,并构建系统,你可以创建Web服务。

通过考虑服务交互开始流程。

这个服务将处理GET请求/greeting,通过可选name参数查询字符串,GET请求应返回一个200 OK的响应JSON字符串,字符串应该是这样的:

1
2
3
4
{
"id": 1,
"content": "Hello, World!"
}

id字段是用于问候的唯一标识
content是问候的文字描述

问候转换成model表示,你可以创建一个资源类,通过一些id,content字段,构造方法和getter方法提供一个简单的java对象:
src/main/java/hello/Greeting.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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下处理GET请求/greeting返回一个实例Greeting

src/main/java/hello/GreetingController.java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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注解确保http请求/greeting映射到greeting()方法上。

上面的例子并不指定GETPUTPOST,等等,因为@RequestMapping在默认情况下映射的所有HTTP操作。使用@RequestMapping(method=GET)来缩小这种映射范围

@RequestParam绑定查询字符串name的值到greeting()方法的name参数上,这个查询字符串明确声明为可选(默认required=true),如果在请求参数中缺少,则使用默认值”World”。

这个方法体实现是通过idcontent属性创建一个Greeting对象返回,id是通过计数器,name是通过格式话模板字符串。

传统的MVC控制器和上面的RESTful Web服务控制器之间的主要区别在于HTTP响应体的创建方式。而不是依靠一个视图技术来执行服务器端渲染的HTML问候数据,这RESTful Web服务控制器简单地填充,并返回一个Greeting对象,对象数据将直接通过JSON格式写入到HTTP响应中。

该代码使用Spring4的新@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

1
2
3
4
5
6
7
8
9
10
11
12
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 基于类路径添加beans,其他beans和各个属性设置。

  • 通常你会添加@EnableWebMvc到Spring MVC的应用程序,但是当它看到的类路径上有spring-webmvc时会自动添加这个注解。它标志着程序是一个Web应用程序,并激活关键行为,如设置DispatcherServlet。

  • @ComponentScan告诉spring去查找在hello包下的其它组件,配置和服务,允许它找到HelloController。

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,你会看到:

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

提供查询字符串参数namehttp://localhost:8080/greeting?name=User

注意content属性从”Hello, World!”变成”Hello, User!”:

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

这一变化表明,在GreetingController@RequestParam安排按预期工作,name参数被赋予了默认值”World”,但始终可以通过查询字符串显式覆盖。

还要注意为何id属性已经从1改为2,这证明了你的工作对跨多个请求相同GreetingController实例,它的计数器字段被每次调用增加一次。

表明spring controller默认是单例的

总结

恭喜!你刚刚使用Spring开发RESTful Web服务

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