补习系列-springboot-restful应用

一、目标

  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

public class Customer {

    private String name;

    public Customer() {
        super();
    }

    public Customer(String name) {
        super();
        this.name = name;
    }

    public String getName() {
        return name;
    }

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

}

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数据进行增删改查
代码如下：

@Component
public class PetManager {

    private static Map<String, Customer> customers = new ConcurrentHashMap<String, Customer>();
    private static Map<String, Map<String, Pet>> pets = new ConcurrentHashMap<String, Map<String, Pet>>();

    @PostConstruct
    public void init() {
        String[] customerNames = new String[] { "Lilei", "Hanmeimei", "Jim Green" };

        for (String customerName : customerNames) {
            customers.put(customerName, new Customer(customerName));
        }
    }

    /**
     * 获取customer
     *
     * @param customer
     * @return
     */
    public Customer getCustomer(String customer) {
        if (StringUtils.isEmpty(customer)) {
            return null;
        }
        return customers.get(customer);
    }

    /**
     * 获取customer名下的 pet 列表
     *
     * @param customer
     * @return
     */
    public List<Pet> getPets(String customer) {
        if (StringUtils.isEmpty(customer)) {
            return Collections.emptyList();
        }

        if (!pets.containsKey(customer)) {
            return Collections.emptyList();
        }

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

    /**
     * 获取某个pet
     *
     * @param customer
     * @param petId
     * @return
     */
    public Pet getPet(String customer, String petId) {
        if (StringUtils.isEmpty(customer) || StringUtils.isEmpty(petId)) {
            return null;
        }

        if (!pets.containsKey(customer)) {
            return null;
        }
        return pets.get(customer).get(petId);
    }

    /**
     * 删除pet
     *
     * @param customer
     * @param petId
     * @return
     */
    public boolean removePet(String customer, String petId) {
        if (StringUtils.isEmpty(customer) || StringUtils.isEmpty(petId)) {
            return false;
        }

        if (!pets.containsKey(customer)) {
            return false;
        }
        return pets.get(customer).remove(petId) != null;
    }

    /**
     * 添加pet
     *
     * @param customer
     * @param pet
     * @return
     */
    public Pet addPet(String customer, Pet pet) {
        if (StringUtils.isEmpty(customer) || pet == null) {
            return null;
        }

        Map<String, Pet> customerPets = null;
        if (!pets.containsKey(customer)) {

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

            // 已经存在
            if (previous != null) {
                customerPets = previous;
            }
        } else {
            customerPets = pets.get(customer);
        }

        if (pet.getPetId() == null) {
            pet.setPetId(UUID.randomUUID().toString());
        }

        customerPets.put(pet.getPetId(), pet);
        return pet;
    }

    /**
     * 更新某个pet
     *
     * @param customer
     * @param petPojo
     * @return
     */
    public Pet updatePet(String customer, Pet petPojo) {
        if (StringUtils.isEmpty(customer) || petPojo == null) {
            return null;
        }

        if (petPojo.getPetId() == null) {
            return null;
        }

        Pet pet = getPet(customer, petPojo.getPetId());
        pet.setType(petPojo.getType());
        pet.setName(petPojo.getName());
        pet.setDescription(petPojo.getDescription());

        return pet;
    }

}

4. 控制层实现

SpringBoot 提供了 @RestController，用于快速定义一个Restful 风格的Controller类
@[email protected] + @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。

    /**
     * 校验customer是否存在
     *
     * @param customer
     */
    private void validateCustomer(String customer) {
        if (dataManager.getCustomer(customer) == null) {
            throw new ObjectNotFoundException(String.format("the customer['%s'] is not found", customer));
        }
    }

    /**
     * 校验pet是否存在
     *
     * @param customer
     */
    private void validatePet(String customer, String petId) {
        if (dataManager.getPet(customer, petId) == null) {
            throw new ObjectNotFoundException(String.format("the pet['%s/%s'] is not found", customer, petId));
        }
    }

自定义异常拦截

    /**
     * 自定义异常，及拦截逻辑
     *
     * @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. 添加宠物

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

{
 "name": "Smart Baby",
 "description": "very small and smart also.",
 "type": "Dog"
}

返回示例

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. 获取宠物列表

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

<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. 查询宠物信息

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

<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. 更新宠物信息

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

{
 "name": "Big Cat V2",
 "description": "I don't like it any more",
 "type": "Cat"
}

返回示例

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. 删除宠物

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

<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的生成。

引入依赖


        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </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.apache.org/licenses/LICENSE-2.0.html")
                .termsOfServiceUrl("")
                .version(VERSION)
                .contact(new Contact("", "", "[email protected]"))
                .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的声明，如下：

@Api(value = "Pet Restful api")
@RestController
@RequestMapping("/rest/pets/{customer}")
public class RestApiController {

    @ApiOperation("添加宠物")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "path", name = "customer", dataType = "String", required = true, value = "客户名", defaultValue = ""),
            @ApiImplicitParam(paramType = "body", name = "pet", dataType = "Pet", required = true, value = "pet 请求", defaultValue = "") })
    @ApiResponses({
        @ApiResponse(code = 201, message = "添加成功"),
        @ApiResponse(code = 404, message = "资源不存在")
    })
    @PostMapping
    public ResponseEntity<Object> addPet(@PathVariable String customer, @RequestBody Pet pet) {
        ...

为了能描述返回对象的文档说明，为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，可看到生成的文档界面：

参考文档

SpringBoot-tutorials-bookmarks
阮一峰-理解Restful架构
SprintBoot-使用Swagger发布API
swagger-2-documentation-for-spring-rest-api

欢迎继续关注"美码师的补习系列-springboot篇" ，期待更多精彩内容^-^

原文地址：https://www.cnblogs.com/littleatp/p/9426491.html

时间： 2024-08-29 18:16:45

补习系列-springboot-restful应用的相关文章

补习系列-springboot 实现拦截的五种姿势

目录 简介 姿势一.使用 Filter 接口 1. 注册 FilterRegistrationBean 2. @WebFilter 注解 姿势二.HanlderInterceptor 姿势三.@ExceptionHandler 注解 姿势四.RequestBodyAdvice/ResponseBodyAdvice RequestBodyAdvice 的用法 ResponseBodyAdvice 用法 姿势五.@Aspect 注解 思考 小结 简介 AOP(面向切面编程)常用于解决系统中的一些耦合

补习系列-springboot 单元测试之道

目录 目标 一.About 单元测试 二.About Junit 三.SpringBoot-单元测试 项目依赖 测试样例 四.Mock测试 五.最后 目标 了解 单元测试的背景 了解如何 利用 springboot 实现接口的测试 了解如何 利用 mokito 做代码的 mock 一.About 单元测试 单元测试其实是一种廉价的技术,是由开发者创建运行测试代码,用于对程序模块(软件设计的最小单位)进行正确性检验的一种做法. 而所谓的最小单元,就是指应用的最小可测试部件. 在面向对象领域,最小单

补习系列(9)-springboot 定时器，你用对了吗

目录 简介 一.应用启动任务 二.JDK 自带调度线程池 三.@Scheduled 定制 @Scheduled 线程池 四.@Async 定制 @Async 线程池 小结 简介 大多数的应用程序都离不开定时器,通常在程序启动时.运行期间会需要执行一些特殊的处理任务. 比如资源初始化.数据统计等等,SpringBoot 作为一个灵活的框架,有许多方式可以实现定时器或异步任务. 我总结了下,大致有以下几种: 使用 JDK 的 TimerTask 使用 JDK 自带调度线程池 使用 Quartz 调度

补习系列(10)-springboot 之配置读取

目录 简介 一.配置样例 二.如何注入配置 1. 缺省配置文件 2. 使用注解 3. 启动参数 还有.. 三.如何读取配置 @Value 注解 Environment 接口 @ConfigurationProperties 注解 四.不同环境中的配置 1. 区别开发.测试.发布环境 2. 声明多配置文件 参考文档 简介 在早前的博客中曾经写过 Spring 程序通过 Bean 映射实现配置信息的读取. 在SpringBoot 框架中读取配置的方式变得非常多样,这导致读者在搜寻资料时反而容易迷糊.

补习系列(15)-springboot 分布式会话原理

目录 一.背景 二.SpringBoot 分布式会话 三.样例程序 四.原理进阶 A. 序列化 B. 会话代理 C. 数据老化 小结 一.背景 在 补习系列(3)-springboot 几种scope 一文中,笔者介绍过 Session的部分,如下: 对于服务器而言,Session 通常是存储在本地的,比如Tomcat 默认将Session 存储在内存(ConcurrentHashMap)中. 但随着网站的用户越来越多,Session所需的空间会越来越大,同时单机部署的 Web应用会出现性能瓶颈

补习系列(20)-大话 WebSocket 与 &quot;尬聊&quot;的实现

目录 一.聊聊 WebSocket 二.Stomp 是个什么鬼 三.SpringBoot 整合 WebSocket A. 引入依赖 B. WebSocket 配置 C. 控制器 D. 前端实现 四.参考文档 一.聊聊 WebSocket 从HTML5技术流行至今,WebSocket已经有非常广泛的应用: 在线游戏,提供实时的操作交互体验 社交平台,与好友实时的私信对话 新闻动态,获得感兴趣的主题信息推送 ... 这些场景,都需要服务器能主动实时的给浏览器或客户端推送消息,注意关键词是主动,还有实

补习系列(21)-SpringBoot初始化之7招式

目录 背景 1. @PostConstruct 注解 2. InitializingBean 接口 3. @Bean initMethod方法 4. 构造器注入 5. ApplicationListener 6. CommandLineRunner 7. ApplicationRunner 测试代码 参考文档 背景 在日常开发时,我们常常需要 在SpringBoot 应用启动时执行某一段逻辑,如下面的场景: 获取一些当前环境的配置或变量 向数据库写入一些初始数据 连接某些第三方系统,确认对方可以

WebApi系列~基于RESTful标准的Web Api

WebApi系列~基于RESTful标准的Web Api 回到目录 微软的web api是在vs2012上的mvc4项目绑定发行的,它提出的web api是完全基于RESTful标准的,完全不同于之前的(同是SOAP协议的)wcf和webService,它是简单,代码可读性强的,上手快的,如果要拿它和web服务相比,我会说,它的接口更标准,更清晰,没有混乱的方法名称,有的只有几种标准的请求,如get,post,put,delete等,它们分别对应的几个操作,下面讲一下: GET:生到数据列表(默

[转] SpringBoot RESTful 应用中的异常处理小结

[From] https://segmentfault.com/a/1190000006749441 SpringBoot RESTful 应用中的异常处理小结 永顺 2016年08月29日发布 赞  |   6收藏  |  15 8.8k 次浏览 @ControllerAdvice 和 @ExceptionHandler 的区别 ExceptionHandler, 方法注解, 作用于 Controller 级别. ExceptionHandler 注解为一个 Controler 定义一个异常处