基于 Spring Boot 的 RESTful API 设计与实现

简介: RESTful 是一种规范,符合 RESTful 的 Api 就是 RESTful Api。简单的说就是可联网设备利用 HTTP 协议通过 GET、POST、DELETE、PUT、PATCH 来操作具有 URI 标识的服务器资源,返回统一格式的资源信息,包括 JSON、XML、CSV、ProtoBuf、其他格式。RESTful 的核心思想是,客户端发出的数据操作指令都是"动词 + 宾语"的结

RESTful 是一种规范,符合 RESTful 的 Api 就是 RESTful Api。简单的说就是可联网设备利用 HTTP 协议通过 GET、POST、DELETE、PUT、PATCH 来操作具有 URI 标识的服务器资源,返回统一格式的资源信息,包括 JSON、XML、CSV、ProtoBuf、其他格式。
RESTful 的核心思想是,客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如,GET /case 这个命令,GET 是动词,/case 是宾语。

RESTful API简介

  • RESTful 架构遵循统一接口原则,不论什么样的资源,都是通过使用相同的接口进行资源的访问。接口应该使用标准的 HTTP 方法如 GET ,PUT 和 POST ,并遵循这些方法的语义。

设计规范

常用的动词有以下 5 个


详情见 https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

Spring Boot 实现 RESTful API

我们可以通过 Spring Boot 注解来实现 RESTful API 。

现在需要编写的是对一个用户的增删改查操作,如下表是一个非 RESTful 和 标准 RESTful 的对比表。

下面我们着重介绍下以下两对注解。

Controller 一般应用在有返回界面的应用场景下。例如,管理后台使用了模板技术如 thymeleaf 开发,需要从后台直接返回 Model 对象到前台,那么这时候就需要使用 Controller 来注解。

RestController 一般应用在只有接口的应用场景下. 例如开发前后端分离的项目时,通过 Ajax 请求服务端接口,那么接口就使用 RestController 统一注解。

需要注意的是 RestController 是 Controller 的子集。RestController 是 Spring4 后新加的注解,从 RestController 注解源码可以看出 RestController 是 Controller 和 ResponseBody 两个注解的结合体,即Controller=RestController+ResponseBody。

RestController 注解源码

@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Controller
@ResponseBody
public @interface RestController {
    @AliasFor(
        annotation = Controller.class
    )
    String value() default "";
}

RequestMapping 和GetMapping/PostMapping/PutMapping/DeleteMapping 作用一样,其实可以相互替换,后者是前者的简化版本。

GetMapping 其实就等于将 RequestMapping 注解的 method 属性设置为 GET,PostMapping 其实就等于将 RequestMapping 注解的 method 属性设置为 POST,PutMapping、DeleteMapping 其实就等于将 RequestMapping 注解的 method 属性分别设置为 PUT、DELETE。

也就是说GetMapping、PostMapping、PutMapping、DeleteMapping 是 RequestMapping 的子集。

我们来看看 RequestMapping 的源码:

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Mapping
public @interface RequestMapping {
    String name() default "";

    //请求URI
    @AliasFor("path")
    String[] value() default {};
    @AliasFor("value")
    String[] path() default {};
    //请求类型,如 GET、POST、PUT、DELETE 等
    RequestMethod[] method() default {};
    //请求参数中必须包含某些参数值,才让该方法处理。
    String[] params() default {};
    //请求参数中必须包含某些指定的header值,才能让该方法处理请求。
    String[] headers() default {};
    //请求的内容类型(Content-Type),例如application/json, text/html;
    String[] consumes() default {};
    //响应的内容类型,仅当 request 请求头中的( Accept )类型中包含该指定类型才返回;
    String[] produces() default {};
}

示例说明:

  • 新增 2 个文件:dto/UserDto.java 和 controller/HogwartsTestUserController.java ,其中 UserController 类中包括了对用户的 4 个操作增删改查。
public class UserDto {

    private String name;
    private String pwd;

    public String getName() {
        return name;
    }

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

    public String getPwd() {
        return pwd;
    }

    public void setPwd(String pwd) {
        this.pwd = pwd;
    }
}
/**
 * RESTful API 风格示例 对资源 user 进行操作
 * 本示例没有使用数据库,也没有使用 service 类来辅助完成,所有操作在本类中完成
 * */
@Api(tags = "测试学院-用户管理模块", hidden = true)
@RestController
@RequestMapping("/api/user")
public class HogwartsTestUserController {

    /**
     * 查询用户列表,返回一个JSON数组
     * */
    @ApiOperation("查询用户列表")
    @GetMapping("/users")
    @ResponseStatus(HttpStatus.OK)
    public Object getUsers(){
        List<UserDto> list = getData();
        return list;
    }

    /**
     * 查询用户信息,返回一个新建的JSON对象
     * */
    @ApiOperation("查询用户信息")
    @GetMapping("/users/{id}")
    @ResponseStatus(HttpStatus.OK)
    public Object getUser(@PathVariable("id") Long id){

        if(Objects.isNull(id)){
            return null;
        }

        List<UserDto> list= getData();
        UserDto userDto = getUserDto(id, list);

        return userDto;
    }

    /**
     * 新增用户
     * */
    @ApiOperation("新增用户")
    @PostMapping("/users")
    @ResponseStatus(HttpStatus.CREATED)
    public Object addUser(@RequestBody UserDto user){

        List<UserDto> list= getData();
        list.add(user);//模拟向列表中增加数据
        return user;
    }

    /**
     * 编辑用户
     * */
    @ApiOperation("编辑用户")
    @PutMapping("/users/{id}")
    @ResponseStatus(HttpStatus.CREATED)
    public Object editUser(@PathVariable("id") Long id,@RequestBody UserDto user){
        List<UserDto> list = getData();
        for (UserDto userDto:list) {
            if(id.equals(userDto.getId())){
                userDto = user;
                break;
            }
        }

        return user;
    }

    /**
     * 删除用户
     * */
    @ApiOperation("删除用户")
    @DeleteMapping("/users/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public Object deleteUser(@PathVariable("id") Long id){
        List<UserDto> list = getData();
        UserDto userDto = getUserDto(id, list);
        return  userDto;
    }

    /**
     * 模拟数据
     * */
    private List<UserDto> getData(){
        List<UserDto> list=new ArrayList<>();

        UserDto userDto = new UserDto();
        userDto.setId(1L);
        userDto.setName("admin");
        userDto.setPwd("admin");
        list.add(userDto);

        userDto = new UserDto();
        userDto.setId(2L);
        userDto.setName("HogwartsTest1");
        userDto.setPwd("HogwartsTest1");
        list.add(userDto);

        userDto = new UserDto();
        userDto.setId(3L);
        userDto.setName("HogwartsTest2");
        userDto.setPwd("HogwartsTest2");
        list.add(userDto);

        userDto = new UserDto();
        userDto.setId(4L);
        userDto.setName("HogwartsTest3");
        userDto.setPwd("HogwartsTest3");
        list.add(userDto);

        return  list;
    }

    /**
     *  模拟根据id查询列表中的数据
     * @param id
     * @param list
     * @return
     */
    private UserDto getUserDto( Long id, List<UserDto> list) {
        UserDto UserDto = null;
        for (UserDto user : list) {
            if (id.equals(user.getId())) {
                UserDto = user;
                break;
            }
        }
        return UserDto;
    }
}

获取全部资源 获取所有用户

GET http://127.0.0.1:8081/api/user/users/

响应参数

[
  {
    "id": 1,
    "name": "admin",
    "pwd": "admin"
  },
  {
    "id": 2,
    "name": "HogwartsTest1",
    "pwd": "HogwartsTest1"
  },
  {
    "id": 3,
    "name": "HogwartsTest2",
    "pwd": "HogwartsTest2"
  },
  {
    "id": 4,
    "name": "HogwartsTest3",
    "pwd": "HogwartsTest3"
  }
]

获取单个资源 获取用户

GET http://127.0.0.1:8081/api/user/users/3

新增一个资源 新增一个用户

POST http://127.0.0.1:8081/api/user/users

请求参数

{
  "id": 4,
  "name": "HogwartsTest5",
  "pwd": "HogwartsTest5"
}

编辑更新一个资源

PUT http://127.0.0.1:8081/api/user/users/3

请求参数

{
  "name": "HogwartsTest6",
  "pwd": "HogwartsTest6"
}

删除一个资源

DELETE http://127.0.0.1:8081/api/user/users/3

下面介绍一些 Spring Boot 常用配置项,通过这些常用配置项,我们可以修改 Spring Boot 的一些默认配置。
修改服务默认端口:

server:
  port: 8093

指定服务名称:

spring:
  application:
    name: aitest

多环境配置

spring:
  profiles:
    active: dev


如上图新建 application-dev.yml、application-test.yml、application-uat.yml、application-prod.yml 四套配置文件环境,我们在四套配置文件中将设置服务端口号分别设置为 8091/8092/8093/8094。

然后启动服务,可以看到服务的端口号会和 application.yml 中激活的环境配置信息一致。
原文链接

更多技术文章分享
https://qrcode.ceba.ceshiren.com/link?name=article&project_id=qrcode&from=Aliyun&timestamp=1654677169&author=YL
相关文章
|
11天前
|
监控 Java 应用服务中间件
高级java面试---spring.factories文件的解析源码API机制
【11月更文挑战第20天】Spring Boot是一个用于快速构建基于Spring框架的应用程序的开源框架。它通过自动配置、起步依赖和内嵌服务器等特性,极大地简化了Spring应用的开发和部署过程。本文将深入探讨Spring Boot的背景历史、业务场景、功能点以及底层原理,并通过Java代码手写模拟Spring Boot的启动过程,特别是spring.factories文件的解析源码API机制。
39 2
|
3天前
|
JSON 缓存 JavaScript
深入浅出:使用Node.js构建RESTful API
在这个数字时代,API已成为软件开发的基石之一。本文旨在引导初学者通过Node.js和Express框架快速搭建一个功能完备的RESTful API。我们将从零开始,逐步深入,不仅涉及代码编写,还包括设计原则、最佳实践及调试技巧。无论你是初探后端开发,还是希望扩展你的技术栈,这篇文章都将是你的理想指南。
|
6天前
|
存储 API 数据库
使用Python和Flask构建简单的RESTful API
使用Python和Flask构建简单的RESTful API
|
6天前
|
JSON 关系型数据库 测试技术
使用Python和Flask构建RESTful API服务
使用Python和Flask构建RESTful API服务
|
15天前
|
SQL 缓存 测试技术
构建高性能RESTful API:最佳实践与避坑指南###
—— 本文深入探讨了构建高性能RESTful API的关键技术要点,从设计原则、状态码使用、版本控制到安全性考虑,旨在为开发者提供一套全面的最佳实践框架。通过避免常见的设计陷阱,本文将指导你如何优化API性能,提升用户体验,确保系统的稳定性和可扩展性。 ###
53 12
|
11天前
|
JSON JavaScript API
深入浅出Node.js:从零开始构建RESTful API
【10月更文挑战第39天】 在数字化时代的浪潮中,API(应用程序编程接口)已成为连接不同软件应用的桥梁。本文将带领读者从零基础出发,逐步深入Node.js的世界,最终实现一个功能完备的RESTful API。通过实践,我们将探索如何利用Node.js的异步特性和强大的生态系统来构建高效、可扩展的服务。准备好迎接代码和概念的碰撞,一起解锁后端开发的新篇章。
|
14天前
|
存储 API 开发者
深入理解RESTful API设计原则
本文探讨了RESTful API的设计原则,强调了其在现代Web服务中的重要性。通过分析状态表示转移(REST)的概念、核心约束以及最佳实践,本文旨在为开发者提供构建高效、可扩展和易于维护的API的指导。文章还讨论了常见的设计陷阱和如何避免它们,以确保API设计的健壮性和灵活性。
|
1天前
|
JSON API 开发者
深入理解RESTful API设计原则
在数字化时代,API已成为连接不同软件应用的桥梁。本文旨在探讨RESTful API设计的基本原则和最佳实践,帮助开发者构建高效、可扩展的网络服务接口。通过解析REST架构风格的核心概念,我们将了解如何设计易于理解和使用的API,同时保证其性能和安全性。
|
1天前
|
安全 测试技术 API
构建高效RESTful API:后端开发的艺术与实践####
在现代软件开发的浩瀚星空中,RESTful API如同一座桥梁,连接着前端世界的绚丽多彩与后端逻辑的深邃复杂。本文旨在探讨如何精心打造一款既高效又易于维护的RESTful API,通过深入浅出的方式,剖析其设计原则、实现技巧及最佳实践,为后端开发者提供一份实用的指南。我们不深入晦涩的理论,只聚焦于那些能够即刻提升API品质与开发效率的关键点,让你的API在众多服务中脱颖而出。 ####
10 0
|
JSON 缓存 JavaScript
SpringBoot学习笔记(五、Restful与json)
SpringBoot学习笔记(五、Restful与json)
211 0
SpringBoot学习笔记(五、Restful与json)
下一篇
无影云桌面