iotat任务周志

数据库设计图

理解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……