电脑基础 · 2023年3月3日

Springboot怎么实现restfult风格Api接口

Springboot怎么实现restfult风格Api接口

前言

在最近的一次技术评审会议上,听到有同事发言说:“我们的项目采用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对开发效率有明显的提升吗?我觉得未必,只不过接口定义看起来更简洁了,无形中开发效率会有一点点的提升,要说明显肯定是没有。