Spring Boot (2) 构建一个RESTful Web服务

0. 背景

本文示例编写一个 RESTful Web服务的过程。

1. 简介

先了解下什么是 RESTful Web服务

Representational State Transfer （缩写：REST）直译就是表现层状态转换，它是一种便于不同软件/程序在网络中互相传递信息 的架构风格。符合这种架构风格的网络服务 可被称为 RESTful 风格。

简单理解 RESTful 就是：
“ 用明确的方法 操作 语义清晰的资源，来呈现不同的资源表现形式”。

更多RESTful介绍参考我的另一篇文章 什么是 RESTful Web服务。

我们将用到 spring web 框架，先了解下。

spring web 框架

spring web 框架 是spring boot 基础上的 一个 web 开发框架。它提供了 @RestController 注解，@GetMapping，@RequestParam 等注解，使得很容易搭建一个 web 服务。

使用 Spring Boot 结合Spring Web 框架可以很方便的开发一个HTTP web服务。

2. 开始之前

创建新的项目

• 打开 IDEA，创建新的项目，选择 Spring boot Initializr 向导一步步引导创建。
• 在选择依赖项页面，要选择 Spring Web 依赖项。
• 再 Next 到完成创建。

Spring Web 依赖项, 其实就是在项目中添加这样的依赖:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

3. 操作示例

3.1 示例目标

我们将创建一个服务，它的网址像下面这样：

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

这是以个 REST风格的URL，它处理 /greeting 这样的资源，接受一个 name=User 这样的参数。

通过get访问时，它的返回结果是个JSON:

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

下面开始。

3.2 先写一个实体类

package com.example.restservice;

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

实体类很简单，有 id 和content两个字段，这个实体将来可以被序列化成json，对应上面的 JSON 格式。

3.3 写一个 控制器 （ RestController ）

package com.example.restservice;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.web.bind.annotation.GetMapping;
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();

    @GetMapping("/greeting")
    public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
        return new Greeting(counter.incrementAndGet(), String.format(template, name));
    }
}

下面我们逐步分解解释它。

@RestController 注解
它作用在一个类上。

在这个 GreetingController 类上使用了 @RestController 注解 ，它指示了 这个类是一个 Rest风格 的 控制器类（Controller）。

@GetMapping注解
它作用在一个类的方法上。

在这个方法 greeting 上使用了@GetMapping 注解，它可以确保以 GET 的方式 到达 /greeting 的请求将 被映射到 greeting() 方法。

常用的还有 @PostMappingPOST 注解。它们都是从 @RequestMapping 中衍生的， 也可以 这样使用 @RequestMapping(method=GET) 。

@RequestParam 注解
它作用在一个方法的参数上。

@RequestParam 表达了 和“查询字符串参数（queryString）” 的绑定。

• 它将 网址中的参数 name绑定到 greeting()方法的name 参数上。
• 如果name请求中不存在参数，则 defaultValue 将生效作为默认值。

方法的返回值
方法的返回值创建一个 具有id和content 字段的新对象 Greeting ，借助Spring的HTTP消息转换器支持，内置的 Jackson 库会将这个对象转换成 JSON 字符串写入到HTTP 响应中。

和传统的 MVC 相比

主要区别在于：创建HTTP响应体的方式。

• RESTful Web服务控制器填充并返回一个Greeting对象，对象数据将作为JSON直接写入HTTP响应。
• 传统MVC 依赖于视图转换，组装成HTML的服务器端呈现。

RESTful Web服务的 每个方法均返回领域对象而不是视图。

@SpringBootApplication
@SpringBootApplication 是一个方便的注解，它表示这是一个SpringBoot程序的起点。

它添加了以下所有内容：
@Configuration： 将类标记为应用程序上下文的Bean定义的源。

@EnableAutoConfiguration： 告诉Spring Boot根据类路径设置，其他bean和各种属性设置开始添加bean。例如，如果spring-webmvc在类路径上，则此注释将应用程序标记为Web应用程序并激活关键行为，例如设置DispatcherServlet。

@ComponentScan： 指示 Spring 在包中寻找其他组件，配置和服务，帮助找到 包 中声明的控制器。

main()方法
在 main()方法 中，使用 SpringApplication.run() 方法来启动应用程序。它将启动一个web容器，比如 tomcat。

整洁，纯净

• 没有一行XML。
• 也没有web.xml文件。
• 该Web应用程序是100％纯Java，因此您无需过多的各种配置基础架构设定。

验证这个程序
将程序跑起来，在浏览器中输入 [http://localhost:8080/greeting](http://localhost:8080/greeting), 来访问它，你可以看到一个返回的JSON字符串结果。

启动方法：
如果你使用 gradle, 使用 gradle方式 启动

./gradlew bootRun

如果你使用 Maven, 使用 maven 方式启动

./mvnw spring-boot:run

4. 扩展

构建成可执行的jar包（Build an executable JAR）

您可以使用Gradle或Maven 构建一个包含所有依赖项，类和资源的可执行JAR 包。然后运行 可以启动这个JAR包。

生成可执行jar 使得可以轻松地将一个服务作为应用程序进行发布，版本化和部署。

打包方式：
如果你使用 Maven, 执行构建成一个 jar 包：

./mvnw clean package

如果你使用 gradle，执行构建成一个 jar 包

./gradlew build

5. 参考

https://spring.io/guides/gs/rest-service/