构建一个RESTful Web Service（Building a RESTful Web Service）

╰+攻爆jí腚メ 2022-08-21 00:12 17阅读 0赞

本文详细介绍了基于Spring创建一个“hello world” [RESTful web service][]工程的步骤。

**目标**  
构建一个service，接收如下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  
JDK1.8或更高  
Gradle 2.3+或Maven 3.0+  
你也可以使用[Spring Tool Suite (STS)][Spring Tool Suite _STS]直接import该工程

**如何完成**  
如同所有的Spring[入门教程][Link 1]，你可以选择一步一步的自己实现，也可以跳过基本的设置步骤。最终，你都将得到一份可以正常运行的代码。

如果选择按步实现，继续下一节。

如果选择跳过基本的安装部分，则执行以下命令从github获取代码：

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

切换当前目录到gs-rest-service/initial，跳到**Create a resource representation class**步骤。  
完成后，可以与gs-rest-service/complete中的代码对比一下，确保正确。

**建立工程**  
首先建立一个基本的构建脚本。基于Spring构建应用时，可以用使用任何的构建系统。这里我们以Gradle和Maven为例。如果不熟悉它们，请参考[Building Java Projects with Gradle][]或者[Building Java Projects with Maven][]

**建立目录结构**  
在你选定的工程目录下，建立如下子目录结构；例如，在\*nix系统中使用mkdir -p src/main/java/hello命令：

└── src  
　　└── main  
　　　　└── java  
　　　　　　└── hello  
　　　　　　  
**创建Gradle构建文件**  
下面是初始的gradle构建文件。

build.gradle

buildscript {  
        repositories {  
            maven { url "http://repo.spring.io/libs-snapshot" }  
            mavenLocal()  
        }  
    }  
    
    apply plugin: 'java'  
    apply plugin: 'eclipse'  
    apply plugin: 'idea'  
    
    jar {  
        baseName = 'gs-rest-service'  
        version =  '0.1.0'  
    }  
    
    repositories {  
        mavenCentral()  
        maven { url "http://repo.spring.io/libs-snapshot" }  
    }  
    
    dependencies {  
        compile("org.springframework.boot:spring-boot-starter-web:1.0.0.RC1")  
        compile("com.fasterxml.jackson.core:jackson-databind")  
        testCompile("junit:junit:4.11")  
    }  
    
    task wrapper(type: Wrapper) { 
        gradleVersion = '1.8'  
    }

你也可以使用Maven，Maven的配置文件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.3.3.RELEASE</version>
        </parent>
    
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-starter-web</artifactId>
            </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>

如果你使用STS（Spring Tool Suite），可以直接导入该工程。

注意：本文使用了[Spring Boot][]。

**创建资源描述类（Create a resource representation class）**  
现在已经建立了工程和构建系统，下面创建你的web service。

首先考虑服务间的交互（service interactions）。

这个服务要处理/greeting的GET请求，其查询字符串包含一个可选的name参数。这个GET请求应该一个200 OK的响应，以及JSON结构的描述问候语的内容。格式如下：

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

id域是问候语的唯一标识，content域是问候语的文本描述。  
为了对问候语的描述进行建模，创建了一个资源描述类。提供了一个包含域（id和content）、构造方法和访问器（getter和setter）的pojo（pain old java object）类：

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格式。  
下面创建资源控制器（resource controller）来发送这些问候语。

**创建资源控制器（Create a resource controller）**  
采用Spring构建RESTful web services时，采用控制器处理HTTP请求。控制器组件通过@Controller注解来标识，下面的GreetingController类处理/greeting的GET请求，并返回一个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));
        }
    }

这个controller很简单，但是其内部做了大量工作，麻雀虽小，五脏俱全。我们一步一步的解释。  
@RequestMapping注解确保对/greeting的HTTP请求映射到greeting()方法。

注意：上述例子中没有写明GET、PUT、POST等等。这是因为@RequestMapping注解默认情况下映射所有的HTTP操作。使用@RequestMapping(method=GET)指定只映射GET请求。

@RequestParam把查询字符串中name参数的值绑定到greeting()方法的name参数上。该查询参数不是必须的（required=false）；如果请求时没有指定该参数，则使用其默认值“World”（defaultValue）。

方法体的实现创建并返回了一个新的Greeting对象，该对象的id属性每次自增1，content属性采用template和name组合而来。

传统的MVC控制器和上述RESTful web service控制器的一个关键区别在于：HTTP响应体的创建方式。前者采用视图层技术（[view technology][]）实现把服务器端的数据渲染为HTML，后者则返回一个Greeting对象。对象数据将会直接以JSON格式写到HTTP响应中。

通过以下方式实现上述功能，greeting()方法的@ResponseBody注解告诉Spring MVC不需要使用服务器端视图层渲染问候语对象（the greeting object），取而代之的是，返回的问候语对象时一个response body，而且应该直接写出。

Greeting对象必须转换成JSON格式。由于Spring支持HTTP报文转换，你不需要手工进行转换。由于[Jackson 2][]在classpath中，因而Spring的[MappingJackson2HttpMessageConverter][]会自动将Greeting实例转换为JSON格式。

**打包部署运行（Make the application executable）**  
虽然可以将这个service打包成传统的[WAR][]文件，并部署到一个外部的应用服务器上，但是我们采用了一个更简单的方式：创建一个独立的（standalone）应用程序。把所有文件打包到一个可执行的JAR文件中，由古老的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;  
    
    @SpringBootApplication  
    public class Application {   
    
        public static void main(String[] args) {  
            SpringApplication.run(Application.class, args);  
        }  
    }

main()方法调用了SpringApplication帮助类，把Application.class传递给它的run()方法作为参数。这样Spring就会去从Application读取注解，并作为[Spring application context][]的一个组件进行管理。  
@ComponentScan注解告诉Spring递归地搜索hello包和其子包中直接或间接标记为@Component的类。这确保Spring发现并注册GreetingController，由于它被标记为@Controller，而@Controller是一类@Component注解。

@EnableAutoConfiguration注解基于你的classpath的内容打开合理的默认行为。例如，由于应用程序依赖于嵌入版的Tomcat（tomcat-embed-core.jar），一个Tomcat服务器会自动建立并进行合理的默认配置。应用程序也依赖于Spring MVC（spring-webmvc.jar），一个Spring MVC DispatcherServlet会为你配置和注册–不需要web.xml！自动配置（Auto-configuration）是一种强大的灵活的机制。详请参考[API文档][API]。

**构建可执行JAR（Build an executable JAR）**  
目前位置，Application类已经写完，下面通过构建系统把所有文件打包为一个可执行jar文件。这将便于对这个service在多种不同环境中进行发布、版本控制和部署。

下面是采用Gradle的步骤，如果采用Maven，可以在[这里][Link 2]找到pom.xml文件，执行mvn clean package构建工程。

更新build.gradle文件的buildscript部分，如下：

buildscript {  
        repositories {  
            maven { url "http://repo.spring.io/libs-snapshot" }  
            mavenLocal()  
        }  
        dependencies {  
            classpath("org.springframework.boot:spring-boot-gradle-plugin:1.0.0.RC1")  
        }  
    }

再在build.gradle中添加如下语句：

apply plugin: 'spring-boot'

可以在[这里][Link 3]看到最终版本的build.gradle文件。  
Spring Boot gradle plugin收集classpath中的所有jar包，并构建一个单独的uber-jar，这使得更加便于执行和传输你的service。它也搜索public static void main()方法标志为一个可执行类。

下面执行如下命令生成一个单独的可执行JAR文件，该JAR文件包含所有必需的依赖的类和资源：

./gradlew build

如果你使用Gradle，可以使用如下语句执行生成的JAR文件：

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

如果使用Maven，使用如下语句：

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

注意：上述过程将生成一个可执行JAR。你也可以选择[构建一个WAR文件][WAR 1]。  
**执行（Run the service）**  
如果采用Gradle，可以在命令行中执行如下命令来运行你的service：

./gradlew clean build && java -jar build/libs/gs-rest-service-0.1.0.jar

注意：如果采用Maven，可以执行如下语句mvn clean package && java -jar target/gs-rest-service-0.1.0.jar  
日志输出。service将会启动并在数秒钟内运行。

**测试（Test the service）**  
现在service已经启动，访问[http://localhost:8080/greeting][http_localhost_8080_greeting]，你会看到：

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

查询字符串中指定一个name参数，如[http://localhost:8080/greeting?name=User][http_localhost_8080_greeting_name_User]。content的值从“Hello, World!”变为“Hello, User!”：

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

这说明GreetingController类中的@RequestParam注解起作用了。name参数给定的默认值为“World”，但是可以通过在查询字符串中设定值覆盖它。  
注意id属性从1变为2。这表明你在多次请求中访问了同一个GreetingController实例，它的counter域每次访问时会自增1。

**小结（Summary）**  
恭喜！你已经开发出了一个基于Spring的RESTful web service。

英文原文：[Building a RESTful Web Service][]

[RESTful web service]: https://spring.io/understanding/REST
[Spring Tool Suite _STS]: https://spring.io/guides/gs/sts
[Link 1]: https://spring.io/guides
[Building Java Projects with Gradle]: http://spring.io/guides/gs/gradle
[Building Java Projects with Maven]: http://spring.io/guides/gs/maven
[Spring Boot]: http://spring.io/guides/gs/spring-boot/
[view technology]: http://spring.io/understanding/view-templates
[Jackson 2]: http://wiki.fasterxml.com/JacksonHome
[MappingJackson2HttpMessageConverter]: http://docs.spring.io/spring/docs/3.2.4.RELEASE/javadoc-api/org/springframework/http/converter/json/MappingJackson2HttpMessageConverter.html
[WAR]: http://spring.io/understanding/WAR
[Tomcat]: http://spring.io/understanding/Tomcat
[Spring application context]: http://spring.io/understanding/application-context
[API]: http://docs.spring.io/spring-boot/docs/0.5.0.M4/api/org/springframework/boot/autoconfigure/EnableAutoConfiguration.html
[Link 2]: https://github.com/spring-guides/gs-rest-service/blob/master/complete/pom.xml
[Link 3]: https://github.com/spring-guides/gs-rest-service/blob/master/complete/build.gradle
[WAR 1]: http://spring.io/guides/gs/convert-jar-to-war/
[http_localhost_8080_greeting]: http://localhost:8080/greeting
[http_localhost_8080_greeting_name_User]: http://localhost:8080/greeting?name=User
[Building a RESTful Web Service]: http://spring.io/guides/gs/rest-service/