SpringBoot RESTful实战

本文公众号来源：美码师

作者：美码师

本文已收录至我的GitHub

一、目标

1. 了解 Restful 是什么，基本概念及风格；

2. 能使用SpringBoot 实现一套基础的 Restful 风格接口；

3. 利用Swagger 生成清晰的接口文档。

二、Restful 入门

什么是REST 

摘自百科的定义：REST即表述性状态转移(英文：Representational State Transfer，简称REST)是Roy Fielding博士(HTTP规范主要贡献者)在2000年的论文中提出来的一种软件架构风格。是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。

通俗点说，REST就是一组架构约束准则；在这些准则中，有不少是利用了现有的WEB标准能力。而最终的目的则是简化当前业务层的设计及开发工作。

Restful API 则是指符合REST架构约束的API，关于这个词在早年前其实已经非常流行，但大多数开发者对其仍然处于观望状态，并不一定会立即采用。这个相信与当时技术社区的成熟度及氛围是密切相关。无论如何，在微服务架构如此流行的今天，Restful API已经成为了一种必备的的标准设计风格。

关键要点

理解 Restful 风格需要理解以下几点：

• 资源

资源指的就是一个抽象的信息实体，可以是一个用户、一首歌曲、一篇文章，只要是可作为引用的对象就是资源。每个资源通常会被映射到一个URI，通过访问这个URI可以获取到信息。

• 资源的表述

资源表述(Representation)指的则是资源的外在表现形式比如一个帖子，可以通过HTML格式展现，也可以通过XML、JSON等格式输出到客户端。

在前面的文章(SpringBoot-Scope详解)中提到，HTTP协议通过MIME来统一定义数据信息的格式标准。通常，Accept、Content-Type可以用来指定客户端及服务端可接受的信息格式，而这个就是资源的表述

• 状态转移

在HTTP访问过程中，资源的状态发生变化。这里会涉及到以下的几个动词：

名称	语义
GET	获取资源
POST	新建资源
PUT	更新资源
DELETE	删除资源

对于不同的访问方法，服务器会产生对应的行为并促使资源状态产生转换。

关于无状态

Restful 是无状态的设计，这点意味着交互过程中的请求应该能包含所有需要的信息，而不需要依赖于已有的上下文。然而 JavaEE中存在一些违背的做法，比如Cookie中设置JSESSIONID，在多次请求间传递该值作为会话唯一标识，这标识着服务端必须保存着这些会话状态数据。

PlayFramework框架实现了无状态的Session，其将会话数据经过加密编码并置入Cookie中，这样客户端的请求将直接携带上全部的信息，是无状态的请求**，这点非常有利于服务端的可扩展性。

三、SpringBoot 实现 Restful

接下来，我们利用 SpringBoot 来实现一个Restful 风格的样例。

说明基于 PetStore(宠物店) 的案例，实现对某顾客(Customer)名下的宠物(Pet)的增删改查。

1. 实体定义

Customer

1. public class Customer {

2. 
   

3.    private String name;

4. 
   

5.    public Customer() {

6.        super();

7.    }

8. 
   

9.    public Customer(String name) {

10.        super();

11.        this.name = name;

12.    }

13. 
    

14.    public String getName() {

15.        return name;

16.    }

17. 
    

18.    public void setName(String name) {

19.        this.name = name;

20.    }

21. 
    

22. }

Customer 只包含一个name属性，我们假定这是唯一的标志。

Pet

public class Pet {

    private String petId;
    private String name;
    private String type;
    private String description;

    public String getPetId() {
        return petId;
    }

    public void setPetId(String petId) {
        this.petId = petId;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getType() {
        return type;
    }

    public void setType(String type) {
        this.type = type;
    }

    public String getDescription() {
        return description;
    }

    public void setDescription(String description) {
        this.description = description;
    }

}

Pet 包含了以下几个属性

属性名	描述
petId	宠物ID编号
name	宠物名称
type	宠物类型
description	宠物的描述

2. URL资源

基于Restful 的原则，我们定义了以下的一组URL：

接口	方法	URL
添加宠物	POST	/rest/pets/{customer}
获取宠物列表	GET	/rest/pets/{customer}
获取宠物信息	GET	/rest/pets/{customer}/{petId}
更新宠物信息	PUT	/rest/pets/{customer}/{petId}
删除宠物	DELETE	/rest/pets/{customer}/{petId}

3. 数据管理

接下来实现一个PetManager 类，用于模拟在内存中对Pet数据进行增删改查代码如下：

1. @Component

2. public class PetManager {

3. 
   

4.    private static Map<String, Customer> customers = new ConcurrentHashMap<String, Customer>();

5.    private static Map<String, Map<String, Pet>> pets = new ConcurrentHashMap<String, Map<String, Pet>>();

6. 
   

7.    @PostConstruct

8.    public void init() {

9.        String[] customerNames = new String[] { 'Lilei', 'Hanmeimei', 'Jim Green' };

10. 
    

11.        for (String customerName : customerNames) {

12.            customers.put(customerName, new Customer(customerName));

13.        }

14.    }

15. 
    

16.    /**

17.     * 获取customer

18.     *

19.     * @param customer

20.     * @return

21.     */

22.    public Customer getCustomer(String customer) {

23.        if (StringUtils.isEmpty(customer)) {

24.            return null;

25.        }

26.        return customers.get(customer);

27.    }

28. 
    

29.    /**

30.     * 获取customer名下的 pet 列表

31.     *

32.     * @param customer

33.     * @return

34.     */

35.    public List<Pet> getPets(String customer) {

36.        if (StringUtils.isEmpty(customer)) {

37.            return Collections.emptyList();

38.        }

39. 
    

40.        if (!pets.containsKey(customer)) {

41.            return Collections.emptyList();

42.        }

43. 
    

44.        return pets.get(customer).values().stream().collect(Collectors.toList());

45.    }

46. 
    

47.    /**

48.     * 获取某个pet

49.     *

50.     * @param customer

51.     * @param petId

52.     * @return

53.     */

54.    public Pet getPet(String customer, String petId) {

55.        if (StringUtils.isEmpty(customer) || StringUtils.isEmpty(petId)) {

56.            return null;

57.        }

58. 
    

59.        if (!pets.containsKey(customer)) {

60.            return null;

61.        }

62.        return pets.get(customer).get(petId);

63.    }

64. 
    

65.    /**

66.     * 删除pet

67.     *

68.     * @param customer

69.     * @param petId

70.     * @return

71.     */

72.    public boolean removePet(String customer, String petId) {

73.        if (StringUtils.isEmpty(customer) || StringUtils.isEmpty(petId)) {

74.            return false;

75.        }

76. 
    

77.        if (!pets.containsKey(customer)) {

78.            return false;

79.        }

80.        return pets.get(customer).remove(petId) != null;

81.    }

82. 
    

83.    /**

84.     * 添加pet

85.     *

86.     * @param customer

87.     * @param pet

88.     * @return

89.     */

90.    public Pet addPet(String customer, Pet pet) {

91.        if (StringUtils.isEmpty(customer) || pet == null) {

92.            return null;

93.        }

94. 
    

95.        Map<String, Pet> customerPets = null;

96.        if (!pets.containsKey(customer)) {

97. 
    

98.            customerPets = new LinkedHashMap<String, Pet>();

99.            Map<String, Pet> previous = pets.putIfAbsent(customer, customerPets);

100. 
     

101.            // 已经存在

102.            if (previous != null) {

103.                customerPets = previous;

104.            }

105.        } else {

106.            customerPets = pets.get(customer);

107.        }

108. 
     

109.        if (pet.getPetId() == null) {

110.            pet.setPetId(UUID.randomUUID().toString());

111.        }

112. 
     

113.        customerPets.put(pet.getPetId(), pet);

114.        return pet;

115.    }

116. 
     

117.    /**

118.     * 更新某个pet

119.     *

120.     * @param customer

121.     * @param petPojo

122.     * @return

123.     */

124.    public Pet updatePet(String customer, Pet petPojo) {

125.        if (StringUtils.isEmpty(customer) || petPojo == null) {

126.            return null;

127.        }

128. 
     

129.        if (petPojo.getPetId() == null) {

130.            return null;

131.        }

132. 
     

133.        Pet pet = getPet(customer, petPojo.getPetId());

134.        pet.setType(petPojo.getType());

135.        pet.setName(petPojo.getName());

136.        pet.setDescription(petPojo.getDescription());

137. 
     

138.        return pet;

139.    }

140. 
     

141. }

4. 控制层实现

SpringBoot 提供了 @RestController，用于快速定义一个Restful 风格的Controller类@RestController=@ResponseBody + @Controller

@RestController
@RequestMapping('/rest/pets/{customer}')
public class RestApiController {

    @Autowired
    private PetManager dataManager;

    /**
     * 添加宠物
     * 
     * @param customer
     * @param pet
     * @return
     */
    @PostMapping
    public ResponseEntity<Object> addPet(@PathVariable String customer, @RequestBody Pet pet) {
        validateCustomer(customer);

        Pet newPet = dataManager.addPet(customer, pet);

        // 返回 201.created
        if (newPet != null) {
            URI location = ServletUriComponentsBuilder.fromCurrentRequest().path('/{petId}')
                    .buildAndExpand(newPet.getPetId()).toUri();

            return ResponseEntity.created(location).build();
        }

        // 返回 204.noContent
        return ResponseEntity.noContent().build();
    }

    /**
     * 获取宠物列表
     * 
     * @param customer
     * @return
     */
    @GetMapping
    @ResponseBody
    public List<Pet> listPets(@PathVariable String customer) {
        validateCustomer(customer);

        List<Pet> pets = dataManager.getPets(customer);
        return pets;
    }

    /**
     * 获取某个宠物
     * 
     * @param customer
     * @param petId
     */
    @GetMapping('/{petId}')
    @ResponseBody
    public Pet getPet(@PathVariable String customer, @PathVariable String petId) {
        validateCustomer(customer);
        validatePet(customer, petId);

        Pet pet = dataManager.getPet(customer, petId);
        return pet;
    }

    /**
     * 更新宠物信息
     * 
     * @param customer
     * @param petId
     * @param pet
     */
    @PutMapping('/{petId}')
    public ResponseEntity<Object> updatePet(@PathVariable String customer, @PathVariable String petId, @RequestBody Pet pet) {
        validateCustomer(customer);
        validatePet(customer, petId);

        pet.setPetId(petId);
        Pet petObject = dataManager.updatePet(customer, pet);
        if (petObject != null) {
            return ResponseEntity.ok(petObject);
        }

        return ResponseEntity.noContent().build();

    }

    /**
     * 删除某个宠物
     * 
     * @param customer
     * @param petId
     * @return
     */
    @DeleteMapping('/{petId}')
    public ResponseEntity<Object> removePet(@PathVariable String customer, @PathVariable String petId) {
        validateCustomer(customer);
        validatePet(customer, petId);

        dataManager.removePet(customer, petId);
        return ResponseEntity.ok().build();
    }

上述代码中已经实现了完整的增删改查语义。在Restful 风格的API 接口定义中，往往会引用 HTTP 状态码用于表示不同的结果，比如一些错误的状态类型。

这里我们对Customer、Pet 进行存在性校验，若资源不存在返回404_NotFound。

1.    /**

2.     * 校验customer是否存在

3.     *

4.     * @param customer

5.     */

6.    private void validateCustomer(String customer) {

7.        if (dataManager.getCustomer(customer) == null) {

8.            throw new ObjectNotFoundException(String.format('the customer['%s'] is not found', customer));

9.        }

10.    }

11. 
    

12.    /**

13.     * 校验pet是否存在

14.     *

15.     * @param customer

16.     */

17.    private void validatePet(String customer, String petId) {

18.        if (dataManager.getPet(customer, petId) == null) {

19.            throw new ObjectNotFoundException(String.format('the pet['%s/%s'] is not found', customer, petId));

20.        }

21.    }

自定义异常拦截

    /**
     * 自定义异常，及拦截逻辑
     * 
     * @author atp
     *
     */
    @SuppressWarnings('serial')
    public static class ObjectNotFoundException extends RuntimeException {

        public ObjectNotFoundException(String msg) {
            super(msg);
        }
    }

    @ResponseBody
    @ExceptionHandler(ObjectNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public String objectNotFoundExceptionHandler(ObjectNotFoundException ex) {
        return ex.getMessage();
    }

5. 接口验证

1. 添加宠物

URLPOST http://{{server}}/rest/pets/LiLei请求内容

1. {

2. 'name': 'Smart Baby',

3. 'description': 'very small and smart also.',

4. 'type': 'Dog'

5. }

返回示例

201 created
Content-Length →0
Date →Mon, 09 Jul 2018 05:15:01 GMT
Location →http://localhost:8090/rest/pets/LiLei/b5400334-e7b3-42f1-b192-f5e7c3193543

2. 获取宠物列表

URLGET http://{{server}}/rest/pets/LiLei请求内容

1. <Empty>

返回示例

200 OK
Content-Type →application/json;charset=UTF-8
Date →Mon, 09 Jul 2018 05:23:27 GMT
Transfer-Encoding →chunked
[
    {
        'petId': 'b5400334-e7b3-42f1-b192-f5e7c3193543',
        'name': 'Smart Baby',
        'type': 'Dog',
        'description': 'very small and smart also.'
    },
    {
        'petId': '610780af-94f1-4011-a175-7a0f3895163d',
        'name': 'Big Cat',
        'type': 'Cat',
        'description': 'very old but I like it.'
    }
]

3. 查询宠物信息

URLGET http://{{server}}/rest/pets/LiLei/b5400334-e7b3-42f1-b192-f5e7c3193543请求内容

1. <Empty>

返回示例

200 OK
Content-Type →application/json;charset=UTF-8
Date →Mon, 09 Jul 2018 05:25:24 GMT
Transfer-Encoding →chunked
{
    'petId': 'b5400334-e7b3-42f1-b192-f5e7c3193543',
    'name': 'Smart Baby',
    'type': 'Dog',
    'description': 'very small and smart also.'
}

4. 更新宠物信息

URLPUT http://{{server}}/rest/pets/LiLei/b5400334-e7b3-42f1-b192-f5e7c3193543请求内容

1. {

2. 'name': 'Big Cat V2',

3. 'description': 'I don't like it any more',

4. 'type': 'Cat'

5. }

返回示例

200 OK
Content-Type →application/json;charset=UTF-8
Date →Mon, 09 Jul 2018 05:31:28 GMT
Transfer-Encoding →chunked
{
    'petId': 'a98e4478-e754-4969-851b-bcaccd67263e',
    'name': 'Big Cat V2',
    'type': 'Cat',
    'description': 'I don't like it any more'
}

5. 删除宠物

URLDELETE http://{{server}}/rest/pets/LiLei/b5400334-e7b3-42f1-b192-f5e7c3193543请求内容

1. <empty>

返回示例

200 OK
Content-Length →0
Date →Mon, 09 Jul 2018 05:32:51 GMT

相关出错

• 客户不存在：404 the customer['test'] is not found

• 宠物不存在：404 the pet['LiLei/b5400334-e7b3-42f1-b192-f5e7c31935431'] is not found

四、Swagger 的使用

关于Swagger

Swagger是目前非常流行的一个API设计开发框架(基于OpenApi)， 可用于API的设计、管理、代码生成以及Mock测试等。

目前Swagger的应用非常广，其涵盖的开源模块也比较多，这里将使用swagger-ui实现API在线DOC的生成。

引入依赖

1.        <dependency>

2.            <groupId>io.springfox</groupId>

3.            <artifactId>springfox-swagger2</artifactId>

4.            <version>2.7.0</version>

5.        </dependency>

6. 
   

7. 
   

8.        <dependency>

9.            <groupId>io.springfox</groupId>

10.            <artifactId>springfox-swagger-ui</artifactId>

11.            <version>2.7.0</version>

12.        </dependency>

定义API配置

@EnableSwagger2
@Configuration
public class SwaggerConfig {


    public static final String VERSION = '1.0.0';

    @Value('${swagger.enable}')
    private boolean enabled;

    ApiInfo apiInfo() {
        return new ApiInfoBuilder().
                title('Pet Api Definition')
                .description('The Petstore CRUD Example')
                .license('Apache 2.0')
                .licenseUrl('http://www./licenses/LICENSE-2.0.html')
                .termsOfServiceUrl('')
                .version(VERSION)
                .contact(new Contact('', '', '[e-mail]'))
                .build();
    }

    @Bean
    public Docket customImplementation() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .build()
                .enable(enabled)
                .apiInfo(apiInfo());
    }
}

@EnableSwagger2声明了Swagger的启用，Docket的Bean定义是API配置的入口，可以设置API名称、版本号，扫描范围等。

声明API描述

在原有的Controller 方法上添加关于API的声明，如下：

1. @Api(value = 'Pet Restful api')

2. @RestController

3. @RequestMapping('/rest/pets/{customer}')

4. public class RestApiController {

5. 
   

6.    @ApiOperation('添加宠物')

7.    @ApiImplicitParams({

8.            @ApiImplicitParam(paramType = 'path', name = 'customer', dataType = 'String', required = true, value = '客户名', defaultValue = ''),

9.            @ApiImplicitParam(paramType = 'body', name = 'pet', dataType = 'Pet', required = true, value = 'pet 请求', defaultValue = '') })

10.    @ApiResponses({

11.        @ApiResponse(code = 201, message = '添加成功'),

12.        @ApiResponse(code = 404, message = '资源不存在')

13.    })

14.    @PostMapping

15.    public ResponseEntity<Object> addPet(@PathVariable String customer, @RequestBody Pet pet) {

16.        ...

为了能描述返回对象的文档说明，为Pet类做API声明：

@ApiModel('宠物信息')
public class Pet {

    @ApiModelProperty(name='petId', value='宠物ID')
    private String petId;

    @ApiModelProperty(name='name', value='宠物名称')
    private String name;

    @ApiModelProperty(name='type', value='宠物类型')
    private String type;

    @ApiModelProperty(name='description', value='宠物描述')
    private String description;

相关的注解：

注解	描述
@ApiModelProperty	用在出入参数对象的字段上
@Api	用于controller类
@ApiOperation	用于controller方法，描述操作
@ApiResponses	用于controller方法，描述响应
@ApiResponse	用于@ApiResponses内，描述单个响应结果
@ApiImplicitParams	用于controller的方法，描述入参
@ApiImplicitParam	用于@ApiImplicitParams内，描述单个入参
@ApiModel	用于返回对象类

访问文档

最后，访问 http://localhost:8000/swagger_ui.html，可看到生成的文档界面：