Springboot怎么实现restfult风格Api接口

Posted 2023-03-08 凡夫贩夫

前言

在最近的一次技术评审会议上，听到有同事发言说：“我们的项目采用restful风格的接口设计，开发效率更高，接口扩展性更好...”，当我听到开头第一句，我脑子里就开始冒问号：项目里的接口用到的是restful风格的设计吗？restful风格的接口是怎么提高的开发效率？或者说这位同事对restful风格是不是有什么误解？于是乎，就有了这篇文章

restful是什么

rest是representational state transfer的缩写，翻译成中文的意思就是网络资源表述性状态转移。直译过来的内容真的很莫名其妙，有点看不懂。简单理解就是，传统的客户端与服务端资源交互接口中有资源状态的描述，restful风格的接口只有资源描述，关于状态的描述转移了，不包含在接口里了，更详细的内容接着往下看。

restful是web服务的一种架构设计风格和开发方式，本质是是一种设计思想和理念，并不是一种新技术，也不针对某一种编程语言，这种理念是在2000年的时候被一个叫Roy Fielding 的人提出来的。但是值得注意的是，rest并没有一个明确的标准，所以才被称之为一种设计风格，而这种设计风格倾向于更加简单轻量的web服务方法设计和实现。

restful的主要原则

虽然没有非常明确的标准，但是Roy Fielding 在提出这种设计理念的时候，也确定了一组架构约束条件和原则，只要满足这些约束条件和原则的应用程序或设计就可以称之为restful风格。restful主要的设计原则如下：

1、网络上的所有事物都被抽象为资源，如一张图片、一段文本，一条数据；

2、每个资源都有一个唯一的资源标识符，如URL；

3、同一个资源具有多种表现形式，即数据格式，如xml,json等；

4、对资源的各种操作不会改变资源标识符；

5、所有的操作都是无状态的，从客户端到服务端的每个请求都必须包含请求所必需的信息；

传统接口设计

本篇文章的主角是restful，而restful风格的设计实际是对传统接口交互的一种优化设计，那么这里简单回顾一下传统的http交互接口是如何设计的，以学生信息管理为例，传统接口通常是这样设计的：

1、查询学生信息列表，http://127.0.0.1:8080/student/queryList，请求方式为post；

2、查询学生信息详情，http://127.0.0.1:8080/student/queryDetail，请求方式为get；

3、保存学生信息，http://127.0.0.1:8080/student/add，请求方式为post；

4、更新学生信息，http://127.0.0.1:8080/student/update，请求方式为post；

5、删除学生信息，http://127.0.0.1:8080/student/del，请求方式为post；

restful风格接口设计

根据restful风格的设计原则，restful风格的接口通常是从这几个方面进行设计的：

1、资源定位描述设计：

restful风格的接口的每一个URL都代表一种资源，URL中只能有名词形式，不能有动词，名词能体现出操作资源的名称，完整的URL可以描述资源本身并且可以在计算机上定位到该资源；

2、资源操作设计：

资源描述设计中用 URL 定位资源，而对资源不同的操作动作，就用不同的http请求方式来表示，http的主要请求方式有get、post、put、delete；其中get表示从服务端获取资源，如查询类操作，post表示在服务端新建资源，如增加、保存类操作，put表示更新服务端上的资源，如更新操作，delete表示从服务端删除资源，如删除类操作；

3、返回状态码设计

  restful风格接口的返回值状态码的设计和http状态码的设计保持一致，常用的http状态码如下：

200 – OK – 一切正常

201 – OK – 新的资源已经成功创建

204 – OK – 资源已经成功擅长

304 – Not Modified – 客户端使用缓存数据

400 – Bad Request – 请求无效，需要附加细节解释如 "JSON无效"

401 – Unauthorized – 请求需要用户验证

403 – Forbidden – 服务器已经理解了请求，但是拒绝服务或这种请求的访问是不允许的。

404 – Not found – 没有发现该资源

422 – Unprocessable Entity – 只有服务器不能处理实体时使用，比如图像不能被格式化，或者重要字段丢失。

500 – Internal Server Error – API开发者应该避免这种错误。

rest的直译意思是网络资源表述性状态转移，转移后的状态是什么样的呢？还以学生信息管理为例，采用restful风格的设计大概是这样的：

1、查询学生信息列表，http://127.0.0.1:8080/students，请求方式为get；

2、查询学生信息详情，http://127.0.0.1:8080/student/id，请求方式为get；

3、保存学生信息，http://127.0.0.1:8080/student，请求方式为post；

4、更新学生信息，http://127.0.0.1:8080/student，请求方式为post；

5、删除学生信息，http://127.0.0.1:8080/student，请求方式为post；

如果是不同的客户端、版本的接口还可以这样区分：

1、查询学生信息列表，http://127.0.0.1:8080/web/v1/students，请求方式为get；

2、查询学生信息详情，http://127.0.0.1:8080/web/v1/student/id，请求方式为get；

3、保存学生信息，http://127.0.0.1:8080/web/v1/student，请求方式为post；

4、更新学生信息，http://127.0.0.1:8080/web/v1/student，请求方式为post；

5、删除学生信息，http://127.0.0.1:8080/web/v1/student，请求方式为post；

从上面学生信息管理的相关restful风格的接口观察，restful风格的接口大概有以下3个特征：

1、每个URL只表述资源本身；

2、不同的请求方式表述对资源的操作；

3、客户端和服务端之间，传递资源的某种资源的表现层；

Springboot项目restful风格的接口示例

@RestController
public class StudentController 
    /**
     * 查询学生信息列表接口
     * @param param
     * @return
     */
    @GetMapping("/students")
    public List<Student> studentList(Student param) 
        List<Student> result = new ArrayList<>();
        //列表查询业务逻辑
        return result;
    

    /**
     * 查询学生详情信息接口
     * @param param
     * @return
     */
    @GetMapping("/student")
    public Student detail(Student param) 
        Student student = new Student();
        //详情查询业务逻辑
        return student;
    

    /**
     * 增加学生信息接口
     * @param student
     * @return
     */
    @PostMapping("/student")
    public Student add(Student student) 
        //新增学生信息业务逻辑
        return student;
    

    /**
     * 更新学生信息接口
     * @param student
     * @return
     */
    @PutMapping("/student")
    public Student update(Student student) 
        //更新学生信息业务逻辑
        return student;
    

    /**
     * 删除学生信息接口
     * @param student
     * @return
     */
    @DeleteMapping("/student")
    public Student delete(Student student) 
        //删除学生信息业务逻辑
        return student;
    

restful风格设计的好处

1、URL本身有很强的可读性，具备自描述性；

2、强调http请求以资源为中心，规范了不同http请求方式的使用，具有对应的语义；

3、无状态的服务接口，可提高应用的扩展水平；

总结

restful的理念，本质上是用一种更加简单、清晰、便捷的方式，来定位、描述网络上的资源以及对这些资源的操作。具体在实操上，可能就仁者见仁，智者见智了。回头文章的开始，实际的项目接口的请求方式基本上是以post为主，get请求极少，put和delete请求根本没有，URL的命名实际上仍是传统的方式。restful对开发效率有明显的提升吗？我觉得未必，只不过接口定义看起来更简洁了，无形中开发效率会有一点点的提升，要说明显肯定是没有。