[SpringBoot guides系列翻译]SpringBoot构建RESTful程序入门

构建一个RESTful的WebService

这个指南将带你用Spring创建一个RESTful的helloworld程序。

你将完成

在下面地址上创建一个接收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分钟
你喜欢的文本编辑器（我这里用了vscode）或者IDE
jdk1.8+
Gradle 4+ 或 Maven 3.2+
你也可以直接把你的代码导入到你的ide中
- Spring Tool Suite
- IntelliJ IDEA

如何完成这份指南

其他的不说了，一步一步来，直接看通过Maven

通过Gradle

忽略~~

通过Maven

这里演示如何用Maven来构建你的spring应用，如果你不熟悉怎么使用Maven，可以看这里。

创建项目结构：

mkdir -p 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>2.0.5.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>
</project>

有几点可以说一下：

第一是固定的modelVersion=4.0
第二是几个groupId都是org.springframework.boot，这个我们一般写自己的公司或者组织相关的倒序域名，这里因为是spring自己的教程，所以都是一样的org.springframework.boot。
spring-boot-starter-parent提供了依赖和插件管理的功能。spring-boot-starter-web用于构建restful的webapi以及springmvc应用。,spring-boot-starter-test用于测试，包含了JUnit，Hamcrest，Mockito。这3个包算是完整的项目基本上都要用到的。
然后是spring-boot-maven-plugin插件。他提供了很多便捷的特性。
- 把用到的所有依赖打包成一个整体，这样方便服务的执行以及分发。
- 把public static void main()标记成可执行类。
- 提供了内置的依赖解析器用于设置相符的Spring Boot依赖的版本号。

通过IDE

介绍了如何使用intellij IDEA，占个位，忽略先。

创建一个资源表示类

定义好了pom就可以开始写代码了。

先想一下服务的交互是怎么样的。

服务处理/greeting过的来的get请求，可能会有一个name参数。然后结果返回一个json以及200状态码。json如下。

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

id字段作为一个唯一表示符，content表示内容。

下面创建一个java类来表示这个类。包含字段，构造函数，两个get方法。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库把对象转换成JSON。

接下来创建控制器。

创建一个资源控制器

Spring用控制器来处理HTTP请求。用@RestController注解来标识。@RequestMapping注解申明请求路径/greeting，然后返回一个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()方法。

上面的@RequestMapping方法注解里面没有指定get或者put或者post，所以，默认是接收所有方法。如果需要，可以按如下指定为只接收get方法@RequestMapping(method=GET)

@RequestParam把请求过来的name参数绑定到方法的name参数上，如果没有传值，默认用defaultValue指定的world。

返回的Greeting对象的id由counter构造，content由template构造。

与传统的MVC 里面的控制器对比，RESTful服务的HTTP请求的Response由控制器直接返回一个Greeting对象，而传统的MVC里面的控制器还需要依赖视图渲染技术进行服务端的渲染技术返回html。

代码使用Spring 4的@RestController注解，把类标记成控制器并且返回领域对象而不是一个视图。可以算是@Controller 和 @ResponseBody的合体。

Greeting对象需要转换成json对象。Spring使用MappingJackson2HttpMessageConverter选择Jackson2作为默认的库把Greeting对象转成json。

使你的程序可运行

虽然把程序打包成一个war文件，然后部署到外部的服务器是可行的。下面演示一种更简单的方式。把程序打包成一个可执行的jar文件，通过main()方法驱动。通过这种方式，使用Tomcat服务器来托管http运行时。

创建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);
    }
}

什么是bean。简单来说是由Spring的 IoC容器控制的，并且是程序的骨架。

@SpringBootApplication是一个简便的注解，它添加了下面这些东西：

@Configuration 定义这个类是bean的来源类。
@EnableAutoConfiguration 告诉SpringBoot去添加基于classpath设置的或者是其他的bean，以及各种属性。
通常你可能会添加@EnableWebMvc注解在Spring MVC程序中。但是SpringBoot会自动为你添加，如果在classpath里面有spring-webmvc。这个标记把程序标记成web应用。激活并设置比如DispatcherServlet之类的核心行为。
@ComponentScan告诉Sping 去查找hello包里面的其他的组件，配置服务，包括控制器。

mian()方法使用SpingBoot的 SpringApplication.run()方法来启动应用。是的，没有写xml配置，这是一个纯粹的java程序。

编译生成可执行的jar

你可以通过命令行的Maven或者Gradle来运行程序。或者你可以把程序编译生成一个可执行的jar文件。这个jar文件包含了必须的依赖，类，资源文件。这方便于分发部署。

mvn spring-boot:run命令来运行程序。

mvn clean package 命令来打包程序生成jar。然后使用

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

来运行。第一次需要要从Maven下载dependency，所以package过程有点长。。。喝杯☕️。

试试这个服务

启动默认是8080端口。访问http://localhost:8080/greeting，将会看到

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

提供一个name参数http://localhost:8080/greeting?name=User，content就会变掉。

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

总结

恭喜，你已经学会~。