Building a RESTful Web Service

2017-06-10 本文已影响143人 b7cda9616c52

文章内容来自官方文章：https://spring.io/guides/gs/rest-service/

这篇文章是介绍如何使用 Spring 创建 RESTful web service。

What you’ll build

创建一个可接收 HTTP Get 请求的服务：
http://localhost:8080/greeting

并且返回问好的 json 字符串：
{"id":1,"content":"Hello, World!"}

可以传入 name 参数修改返回字符串中的问好对象：
http://localhost:8080/greeting?name=User

这时返回的字符串如下：
{"id":1,"content":"Hello, User!"}

What you’ll need

大概15分钟时间
一个喜欢的编辑器或 IDE
JDK 1.8 或以上
Gradle 2.3+ 或 Maven 3.0+
也可以直接将代码导入 IDE:
- Spring Tool Suite (STS)
- IntelliJ IDEA

How to complete this guide

和许多 Spring 的 Getting Started guides 一样，可以从头开始一步一步的来，也可以绕开比较熟悉的基础部分，只要最后运行正确了就行。

从头开始，请查看 Build with Gradle。
跳过基础部分，按照如下方法：

下载并解压代码，或使用 git 拉取
git clone [https://github.com/spring-guides/gs-rest-service.git](https://github.com/spring-guides/gs-rest-service.git) 。
进入 gs-rest-service/initial 目录。
直接查看 Create a resource representation class。

完成之后，可以与 gs-rest-service/complete 中的内容进行比较。

Build with Gradle

这里使用 Gradle 构建项目，若对 Gradle 不熟悉，可以先查看 Building Java Projects with Gradle 。

Create the directory structure

使用 mkdir -p src/main/java/hello 命令创建项目的目录结构：

└── src
    └── main
        └── java
            └── hello

创建 build.gradle 文件，下面是其中的内容：

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:1.5.2.RELEASE")
    }
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'idea'
apply plugin: 'org.springframework.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 ，即上面 classpath("org.springframework.boot:spring-boot-gradle-plugin:1.5.2.RELEASE") 所指定的插件，提供了许多便捷的特性：

将所有的 jar 包打成一个可运行的 "über-jar"，方便执行和传送。
搜索 public static void main() 作为启动类。
内置了许多与 Spring Boot dependencies 版本对应的依赖包，当然也可以自己修改依赖包版本。

Build with Maven

稍后继续。。。

Build with your IDE

如何将代码导入到 Spring Tool Suite。
如何将代码导入 Intellij IDEA。

Create a resource representation class

现在可以编写服务代码了。
服务可接收名为 /greeting 的 GET 请求，有一个可选参数 name ，正常的情况（状态码 200 OK）下返回问好的 JSON 字符串。

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

id 是问好的唯一标识，content 是问好内容。
下面创建一个问好的类：

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 字符串。

Create a resource controller

Spring 构建 RESTful 服务，HTTP 请求使用 controller 进行控制。controller 组件使用 @RestController 进行修饰。下面来看看 GreetingController 的写法：

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 请求对应的是 greeting() 方法。

上面的例子中，没有指定 GET、PUT、POST等，@ RequestMapping 可接收所有的 HTTP 操作。使用 @RequestMapping(method=GET) 限制匹配范围。

@RequestParam 指定请求参数为 name 的值传入方法的 name 参数，默认请求参数都是不可缺少的（required=true），如果没有传入传入该参数，则其值为 defaultValue 的值。
也就是说请求时不指定 name 参数，返回的问好对象为 World。

RESTful 与传统的 MVC 服务的区别是返回的不是 view technology 在服务端进行数据渲染后的 html，而是直接返回数据。

上面的代码使用的是 Spring 4 的 @RestController，标明该类为一个 controller，其中的每个方法都返回数据而不是界面。它是 @Controller 和 @ResponseBody 合起来的简写。

Greeting 对象必须被转换为 JSON 格式，Spring 会自动使用 Jackson 完成。MappingJackson2HttpMessageConverter 的作用就是如此。

Make the application executable

可以将其打包为 [WAR] 部署到其他应用服务里，这里我们有一种更简单的方式将其作为单独的应用进行部署。可其打包为一个可执行的
JAR 文件，与启动 main() 方法一样启动。以前是将其部署到 Tomcat 中运行，现在我们可单独进行部署。

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 ，标明类是 application context 的一个资源。
@EnableAutoConfiguration tells Spring Boot to start adding beans based on classpath settings, other beans, and various property settings.
可以为 Spring MVC 应用添加 @EnableWebMvc 注解，只是当在 classpath 发现有 spring-webmvc 时 Spring Boot 自动添加了。标明应用是 web 应用，并激活其行为特性如 DispatcherServlet。
@ComponentScan 在 hello 包下查找其他 components，configurations，services，让其找到 controllers。

main() 方法中使用 SpringApplicaton.run() 方法启动。我们没有写任何 XMl。没有 web.xml 配置，这个简单的 web 应用完全是 Java 写的，不需要处理各种配置。

Build an executable JAR

可以在终端利用 Gradle 或 Maven 运行应用。也可以打包成以可执行的 JAR 文件执行。
若使用 Gradle，启动应用使用 ./gradlew bootRun，打包为 JAR 文件使用 ./gradlew build，使用如下命令启动：
java -jar build/libs/gs-rest-service-0.1.0.jar

若使用 Maven，启动命令 ./mvnw spring-boot:run，打包 JAR 文件 ./mvnw clean package。使用如下命令运行：
java -jar target/gs-rest-service-0.1.0.jar

上面是打包为可运行的 JAR 文件，也可以打包为 WAR 文件 build a classic WAR file

Test the service

服务启动好了，现在开始测试。
输入 http://localhost:8080/greeting，返回：
{"id":1,"content":"Hello, World!"}

输入 http://localhost:8080/greeting?name=User，返回：
{"id":2,"content":"Hello, User!"}