使用Spring创建满足RESTful规范的Web Service

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

这个指南讨论如何使用Spring的RESTful web service来创建一个“hello world”程序。

示例功能简介

使用以下方式的HTTP GET请求来访问这个Service：

http://localhost:8080/greeting

使用下面greeting的JSON描述来响应这个请求：

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

在下面的查询字符串中有一个可选的name参数，可以实现greeting的定制化响应：

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

name参数值会替换默认的“World”，并反映到对应的响应中：

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

开发环境

一个文本编辑器或IDE；

JDK1.6或更新的版本；

Gradle1.11+或Maven3.0+；

也可以把本实例的代码直接导入到Spring Tool Suite（STS）中，然后在那儿开始工作。

如何完成这个指南

跟大多数Spring的入门指南一样，可以按照步骤从头开始，也可以跳过那些你已经熟悉的基本的步骤，不管使用哪种方法，最终都要编写工作代码。

要从头开始，请转到下面的“使用Gradle构建”标题。

要跳过基本步骤，请做以下事情：

1. 下载并解压本指南的资源库，或使用以下Git命令来克隆它：

git clone https://github.com/spring-guides/gs-rest-service.git

2. 在命令行进入gs-rest-service/initial目录

3. 跳转到下面的“创建资源描述类”标题。

使用Gradle构建

首先要建立一个基本的编译脚本。在编译使用Spring的应用程序时，你可以使用任意你喜欢的编译系统，但是本示例程序需要使用这里介绍的Gradle和Maven来工作。如果你不熟悉这两个工具，请参照“使用Gradle构建Java工程”或“使用Mave构建Java工程”

创建目录结构

在你选择的工程目录中，创建下列子目录结构；例如，在操作系统中使用mkdir/-p src/main/java/hello命令：

└── src

    └── main

        └── java

            └── hello

创建Gradle的编译文件

下面是初始的Gradle的编译文件。

build.gradle

buildscript {

    repositories {

        maven { url"https://repo.spring.io/libs-release" }

        mavenLocal()

        mavenCentral()

    }

    dependencies {

       classpath("org.springframework.boot:spring-boot-gradle-plugin:1.1.10.RELEASE")

    }

}

apply plugin: 'java'

apply plugin: 'eclipse'

apply plugin: 'idea'

apply plugin: 'spring-boot'

jar {

    baseName ='gs-rest-service'

    version =  '0.1.0'

}

repositories {

    mavenLocal()

    mavenCentral()

    maven { url"https://repo.spring.io/libs-release" }

}

dependencies {

   compile("org.springframework.boot:spring-boot-starter-web")

   testCompile("junit:junit")

}

task wrapper(type: Wrapper) {

    gradleVersion = '1.11'

}

Spring启动 gradle插件提供了很多方便的功能：

1. 它收集了所有的classpath上的jars，并把它们打包成一个单独的、可运行的“über-jar”，这让执行和传输服务更加方便。

2. 它会搜索Public static void main()方法，把它标记为可运行的类。

3. 它提供了一个内置的依赖解析器，把对应的版本号设置给匹配的Spring启动依赖，你可以用你所希望的版本来重写，但它会默认启动选择的版本设置。

使用Mave构建

首先建立基本的编译脚本，在使用Spring构建应用程序时，你可以使用任意你喜欢的构建系统，但是本示例的代码需要使用这里介绍的Maven。如果你还不熟悉Maven，可以参照“使用Maven来构建Java工程”。

创建目录结构

在你选择的工程目录中，创建下列子目录，例如，在操作系统命令行下使用mkdir/-p src/main/java/hello：

└── 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>1.1.10.RELEASE</version>

    </parent>

    <dependencies>

        <dependency>

            <groupId>org.springframework.boot</groupId>

            <artifactId>spring-boot-starter-web</artifactId>

        </dependency>

    </dependencies>

    <properties>

        <start-class>hello.Application</start-class>

    </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>

SpringBoot Maven插件提供了很多方便的功能：

1. 它收集了所有的classpath上的jars，并把它们打包成一个单独的、可运行的“über-jar”，这让执行和传输服务更加方便。

2. 它会搜索Public static void main()方法，把它标记为可运行的类。

3. 它提供了一个内置的依赖解析器，把对应的版本号设置给匹配的Spring启动依赖，你可以用你所希望的版本来重写，但它会默认启动选择的版本设置。

使用Spring工具集来创建

如果使用Spring工具集，那么你可以简单的直接导入这个指南。

创建一个资源描述类

现在可以创建该工程并编译系统，就可以创建自己的Web Service了。

以下是Service的交互过程:

该Service会处理/greeting的GET请求，在这个请求的查询字符串中会带有一个可选的name参数。这个GET请求应该返回200 OK的响应，并用JSON的格式在消息体中描述一个问候。它看上去格式如下：

{

    "id": 1,

    "content": "Hello, World!"

}

其中id字段这个问候的唯一标识，content字段问候的文本描述。

我们需要创建一个资源描述类来作为问候表述的模型。

这个类提供了一个带有字段、构造器以及id和content字段的访问器的普通Java对象：

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 service的方法中，HTTP请求是由控制器来处理的。通过@RestController注释可以很容易的识别这些组件，并且下面的处理/greeting的GET请求的GreetingController会返回一个新的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()方法。

注意：上面的示例中没有指定GET、PUT、POST等信息，因为在默认情况下，@RequestMapping会映射到所有的HTTP操作。使用@RequestMapping(method=GET)会使映射范围变窄。

@RequestParam把查询字符串参数name的值绑定到greeting()方法的name参数中。这个查询字符串参数不是必须的，如果在请求中没有这个参数，那么会使用默认值“World”。

这个方法的实现部分创建并返回了一个新的Greeting对象，这个对象的id属性值是来自counter对象的下一个值，content属性值是template变量使用name值格式化后的值。

RESTful web service控制器跟传统的MVC控制器的关键差异是是创建HTTP响应的方式不同，它不依赖于在服务端把相关数据展开到HTML中的视图技术，而是简单包装并返回一个Greeting对象，这个对象会用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.autoconfigure.EnableAutoConfiguration;

import org.springframework.boot.SpringApplication;

import org.springframework.context.annotation.ComponentScan;

@ComponentScan

@EnableAutoConfiguration

public class Application {

    public static void main(String[] args) {

        SpringApplication.run(Application.class, args);

    }

}

main()方法中调用的SpringApplication帮助器，并给它的run()方法提供了Application.class作为参数，这是告诉Spring要从Application对象中读取注释的元素数据，并且会把该Application对象作为Spring应用程序的上下文环境中的一个组件来管理。

@ComponentScan注释会告诉Spring采用递归的方法来搜索hell包和其子包中直接或间接带有Spring的@Component注释标记的类。这个只是确保Spring会找到并注册GreetingController类，因为它使用了@RestController注释，这注释是@Component注释的一种类型。

@EnableAutoConfiguration注释会基于你的类路径上内容来切换合理的默认行为，例如，因为本应用程序会依赖内置的Tomcat的版本（tomcat-embed-core.jar），所以建立和配置一个Tomcat服务就被认为是合理的默认行为。并且因为该应用程序还依赖Spring的MVC框架（spring-webmvc.jar），所以默认会给你配置和注册Spring MVC的DispatcherServlet类---无需web.xml！自动配置时一种强大、灵活的机制。更多的细节可参考API文档。

创建一个可执行的JAR

如果你正在使用Gradle，可以使用./gradlew bootRun命令来运行本应用程序。

你可以使用./gradlew build命令把所有的必要的依赖、类和资源都编译到一个可执行的JAR文件中。这样会让它在其整个生命周期内，很容易的进行传递、版本管理以及部署等等。

运行该JAR文件的命令如下：

java -jar build/libs/gs-rest-service-0.1.0.jar

如果你正在使用Maven，可以使用mvn spring-boot:run命令来运行本应用程序。或者适应mvn clean package命令来创建一个JAR文件，然后使用下面的命令来运行这个JAR文件：

java -jar target/gs-rest-service-0.1.0.jar

注意：上述创建可运行的JAR的过程，也可以用创建类的WAR文件来代替。

运行该JAR文件时，会有日志显示。

测试该Web Service

服务被启动后，在浏览器中访问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每次调用都像期望的那样被加1。