使用SpringBoot和Maven快速搭建RESTful web服务

本博文和你一起使用SpringBoot和Maven快速搭建RESTful web Service。笔者当前IDE是idea。

1. 创建项目

在Idea中创建新的maven项目，在maven tab下选择maven-archetype-quickstart模板。

输入Maven项目的坐标值，并选择存储路径。

2. 完善目录结构

通过Maven模板生成的项目目录通常是不完整的，缺少resources目录。我们手动添加两个目录，并分别标记为资源文件。

3. pom.xml文件配置

Maven是非常优秀的jar管理工具，通过pom.xml引入依赖、插件，统一管理jar包。

<?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>com.ac</groupId>
    <artifactId>Demo</artifactId>
    <version>1.0-SNAPSHOT</version>

    <name>Demo</name>
    <!-- FIXME change it to the project's website -->
    <url>http://www.example.com</url>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.6.RELEASE</version>
    </parent>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

    <dependencies>
        <!-- 引入springboot依赖 -->
        <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>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.11</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <!-- 锁定插件版本，避免使用Maven默认版本 -->
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.springframework.boot</groupId>
                    <artifactId>spring-boot-maven-plugin</artifactId>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

其中，parent标签提供父级依赖，spring-boot-starter-parent为使用Maven构建的应用程序提供依赖性和插件管理。
spring-boot-starter-web，使用Spring MVC构建Web（包括RESTful）应用程序的启动器，默认使用Tomcat容器。
spring-boot-starter-test，使用JUnit，Hamcrest和Mockito等库来测试Spring Boot应用程序的启动器。

Spring Boot Maven插件spring-boot-maven-plugin提供了很多方便的特性。例如，它收集类路径上的所有jar包，并构建一个可运行的jar包集，方便执行和传输服务；搜索public static void main()方法以标记为可运行的类；它提供了一个内置的依赖项解析器，可以设置版本号以匹配Spring Boot依赖项。

4. 创建资源类

该服务将处理/greeting的GET请求，可选地在查询字符串中使用name参数。请求会返回200 OK响应，body中JSON报文表示内容，其中id字段是greeting的唯一标识，content是greeting的文本表示。

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

我们需要创建资源表示类，来建模greeting。下面我们提供一个POJO，设置字段、构造器、访问方法。

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;
    }
}

5. 创建controller

Spring通过controller来处理HTTP请求。如下GreetingController处理/greeting的GET请求，并返回一个Greeting类的对象。

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()方法。案例中并没有指定具体的HTTP方法，如GET、PUT、POST。此时，默认采取@RequestMapping(method=GET)映射所有HTTP操作。

@RequestParam注解用于绑定查询字符串参数name到greeting()方法的name参数上。如果请求中name参数缺失，使用默认值World。

传统MVC控制器和上面的RESTful Web服务控制器之间的关键区别在于创建HTTP响应主体的方式。 这个RESTful Web服务控制器只是填充并返回一个Greeting对象，而不是依靠视图技术使服务端greeting数据呈现为HTML。 对象数据将作为JSON直接写入HTTP响应。

代码中使用了Spring4的新注解@RestController，用于将类标记位控制器，其中每个方法返回一个域对象，而不是view，是@Controller和@ResponseBody汇总在一起的简写。

6. 创建服务启动器

虽然可以将此服务打包为传统的WAR文件以便部署到外部应用程序服务器，但下面演示以更简单的方法创建了一个独立的应用程序。 将所有内容打包在一个可执行的JAR文件中，由Java main（）方法驱动。 在此过程中，使用Spring的支持将Tomcat servlet容器嵌入为HTTP运行时，而不是部署到外部实例。

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是组合注解，用于快捷配置启动类。注解上有7个注解，其中前4个是元注解，用于修饰当前注解，无实际功能。
@SpringBootConfiguration继承自@Configuration，声明当前类是一个配置类，相当于Spring配置的xml文件。
@EnableAutoConfiguration作用是让Spring Boot会根据类路径中的jar包依赖为当前项目进行自动设置。例如，如果spring-webmvc位于类路径上，则会将应用程序标记为Web应用程序并激活关键行为，例如设置DispatcherServlet。
@ComponentScan告诉Spring自动扫描包中使用@Service，@Component，@Repository，@Controller的类，并注册为bean。

main()方法使用Spring Boot的SpringApplication.run()方法来启动应用程序。我们可以发现在整个过程中不需要配置任何XML文件。

7. 测试服务

首先启动服务

访问 http://localhost:8080/greeting，就可以得到如下结果。

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

再次访问带上name参数http://localhost:8080/greeting?name=User，结果会改变为

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

此时name参数生效，显式覆盖默认值。id属性由1改变为2。这证明在多个请求中针对相同的GreetingController实例，并且其计数器字段在每次调用时按预期递增。

至此，我们已经搭建好一个RESTful web Service。