数据库设计图
理解restful风格接口
网络应用程序,分为前端和后端两个部分。当前的发展趋势,就是前端设备层出不穷(手机、平板、桌面电脑、其他专用设备…)。
因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信。这导致API构架的流行,甚至出现"API First"的设计思想。RESTful API是目前比较成熟的一套互联网应用程序的API设计理论。
一、协议
API与用户的通信协议,总是使用HTTPs协议。
二、域名
应该尽量将API部署在专用域名之下。
三、版本
应该将API的版本号放入URL。
另一种做法是,将版本号放在HTTP头信息中,但不如放入URL方便和直观。Github采用这种做法。
四、路径(Endpoint)
路径又称"终点"(endpoint),表示API的具体网址。
在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。
五、HTTP动词
对于资源的具体操作类型,由HTTP动词表示。
常用的HTTP动词有下面五个(括号里是对应的SQL命令)。
GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
DELETE(DELETE):从服务器删除资源。
六、返回结果
针对不同操作,服务器向用户返回的结果应该符合以下规范。
GET /collection:返回资源对象的列表(数组)
GET /collection/resource:返回单个资源对象
POST /collection:返回新生成的资源对象
PUT /collection/resource:返回完整的资源对象
PATCH /collection/resource:返回完整的资源对象
DELETE /collection/resource:返回一个空文档
七、Hypermedia API
RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。
比如,当用户向api.example.com的根目录发出请求,会得到这样一个文档。
上面代码表示,文档中有一个link属性,用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系(collection关系,并给出该collection的网址),href表示API的路径,title表示API的标题,type表示返回类型。
restful接口设计误区
用Spring Boot开发API接口
返回格式
API接口要求返回的格式是 application/json,我们知道网页返回的格式一般是 text/html,因此,Spring Boot为写接口,提供了两种实现方式:类注解 和 方法注解。
类注解 @RestController
我们只需要在类上写上注解 @RestController,那么此Controller返回格式就都是text/json。
方法注解 @ResponseBody
我们只需要在某个方法上写上注解 @ResponseBody,那么该方法返回格式是text/json
请求方式
@RequestMapping
在RequestMapping的源码中提到,这种支持任意请求方式,类似于自适应。
@GetMapping
客户端只能用 GET 方式请求,适用于查询数据
@PutMapping
客户端只能用 PUT方式请求,使用于修改数据(但在实际使用中,我个人建议还是采用POST方式较为妥当)
@DeleteMapping
客户端只能用 DELETE方式请求,使用于删除数据。
接收参数
@RequestParam
public String getInfo(@RequestParam(name = “param”,
required = false,
defaultValue = “param dafault value”) String param)
name代表提交参数名。
required意思是这个参数是否必需,默认true,没有该参数,无法调用此方法;这里设为false,有无该参数都可以调用。
defaultValue如果该参数值为空,那么就使用默认值。
数据格式
下面我们来了解下,Spring Boot 可以支持的数据格式。
我一般常用的基本数据类型有 int、String。
而我们在日常中,还可能有 Array、List、Map……