结合SpringBoot，总结RESTful风格接口

Posted 2022-11-30 你，好

符合RESTful规范的接口会有很强的可读性，且具有自描述性、易扩展。而且相对安全些。
设计一套好的RESTfulAPI接口要尽量做到以下几点：

1. 尽量将API部署在专用域名之下

例如：
https://baike.baidu.com/（百度百科）
https://pinyin.sogou.com/（搜狗输入法）

当然，如果项目简单就不必自找麻烦了。

2. 将项目版本号放入URL里

例如：
https://developer.github.com/v4/(GitHub)

3. 多用名词，名词最好能与数据库表格名对应

例如：
https://www.nowcoder.com/contestRoom（牛客网）

4. 用HTTP请求类型来区分增删改查操作

常用的有五种：

• GET：对应select，从服务器中取出资源（一项或多项）。
• POST：对应insert，在服务器中新建一个资源。
• PUT：对应update，在服务器中更新资源。（客户端提供需更新的完整资源）
• PATCH：对应update，在服务器更新资源。（客户端提供需更新的属性）
• DELETE：对应delete，从服务器中删除资源。

举例：

• GET @GetMapping("/users") 获取所有用户
• POST @PutMapping("/user") 插入一个用户
• PUT @PutMapping("/user/id") 更新某一用户信息（提供该用户全部信息）
• PATCH @PatchMapping("/password/id") 修改密码（提供部分信息）
• DELETE @DeleteMapping("/user/id") 删除某一用户

5. 用 ? 来过滤信息

例如：

• https://www.nowcoder.com/contestRoom?page=2 指定第几页
• https://www.nowcoder.com/search?query=hello 指定查询条件

6. 用 - 或 _ 来分割URI

可以用 - 或 _ 来分割一些单词，使得uri更易读。
例如：

• http://www.oschina.net/news/38119/oschina-translate-reward-plan

7. 细化返回结果

• 状态码（code）

200 OK - [*]：操作成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误（比如参数错误）。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的（权限不足）。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

• 成功/错误信息（message）：返回友好提示信息
• 返回数据（data）

请求参数	操作	返回数据
GET	获取多个资源	返回资源对象列表（数组）
GET	获取单个资源	返回单个资源对象
POST	插入资源	返回新生成资源对象
PUT	更新资源	返回完整完整资源对象
PATCH	更新资源	返回完整资源对象
DELETE	删除资源	返回空

当然，仁者见仁智者见智，具体怎么设计接口也需要结合业务来判断。
参考：RESTful 架构详解、RESTful API 设计指南 - 阮一峰