RESTful规范/风格

RESTful规范/风格

每个URI代表的是请求资源，因此URI中不能有动词，只能有名词。

1、引入

开发中，常会遇到这类问题：以添加用户为例，会很纠结。

1. 用 /createUser
2. 用 /user/create
3. 用 /userCreate
4. 用 /addUser
5. 用 /user/add
6. 用 /userAdd

以上都可，但是又不可。具体来说不那么标准，而且不是同一规范，也许当时用的是addUser，下次添加别的如菜单或许就用createMenu。

所以用一个统一规范来管理就很不错！！！

2、RESTful简介

REST（英文：Representational State Transfer，简称REST）：表述性状态转移

3、URI

请求资源（用户请求获取图片、文本、视频等资源）标识，即URI（Uniform Resource Identifier，即统一资源标识符）。

4、Http请求

Http请求头有Content-Type规定了资源的类型。

比如有的资源是 txt、MP3、MP4、json等格式。

5、规范

5.1、规范引入

如果我们要做一些操作，例如新增一个东西；或者删除一个东西；或者改变一个东西，例如0 -> 1、 1->0；或者查询一个东西；

那么一个请求，我们应该如何简单、清晰、规范地标识这些操作呢？

客户端可以发送 POST、PUT、GET、DELETE请求，服务器可以通过这些不同请求来了解客户端需要进行哪些操作。

5.2、特点

访问资源可以通过请求方式来标识：对资源的不同操作

• POST：增加操作，增加数据
• DELETE：删除操作，删除数据
• PUT：更新操作，更新数据
• GET：查询操作，获取数据

例如：

 @RequestMapping(value = "/testRestful", method = {RequestMethod.PUT})

前端通过<input type=“hidden” name=“_method” value=“PUT”>来使用

5.3、要素

• 协议

如：http(s)，有的用http，有的用https（苹果要求用https，因为此协议是加密传输，更安全）。

• 域名

如：

• www.baidu.com标识这是一个百度域名（baidu.com），前缀www标识万维网。
• api.baidu.com标识这是一个百度域名（baidu.com），前缀api标识这是专门用来调用接口的。

3. 路径

如：/users表示要操作用户相关的。/courses表示要操作课程相关的。

4. 版本

如：/v1/users表示要操作当前版本号为1的用户相关的数据。
（注意：在实际开发中，项目迭代升级后，可能有不少客户使用的还是老版本项目，因此需要保留老版本项目的内容。直到客户都不采用老版本之后，才能将老版本内容剔除。）

5. 动作

如：通过POST、DELETE、PUT、GET来标识客户端请求的操作，是增、删、改还是查。

6、案例

所有案例都不是绝对的，适合的才是最好的。

6.1、查询用户id为1课程为English的详细信息

1. /api/users/1/courses?course_name=English
2. /api/users/me/courses?course_name=English
3. /api/courses?user_id=1&course_name=English
4. /api/courses?course_name=English

那么上面选哪种？

2种情况：

• 针对当前登录用户，选择第4种，因为用户登录后的信息一般存在后端中，只需获取具体课程名，就可结合获取课程详细信息。

  优点：

  • 更安全，以防外部可以修改id值，来获取不同用户的信息

• 针对管理员，同样选择第4种，因为将用户id隐藏更安全。

  优点：

  • 利于保护用户隐私数据。

6.2、增删改查用户信息

1. /api/user/add
2. /api/user/delete
3. /api/user/update
4. /api/user/get

根据RESTful风格，清晰明了的做法：
（访问资源可以通过请求方式来标识：对资源的不同操作）

1. POST请求 /api/user
2. DELETE请求 /api/user/1
3. PUT请求 /api/user/1
4. GET请求 /api/user/1

6.3、转账：1号用户，转账100，给2号用户

• POST请求 /api/accounts/1/transfer/100/to/2

如果只看这个URI会有点迷惑。

正确设计：

• POST请求 /api/transaction?from=1&to=2&money=100

这样就比较清晰明了。

这只是案例演示。实际开发中，金额、用户账号都是隐藏在body体中，甚至还要加密，为了更安全。

6.4、状态码和提示信息设计

返回的结果设计：

code:
msg/message:
消息(data)：

6.5、翻页设计

1. /api/courses?page=1&pageSize=20

优点：方便统计翻页信息，可以跳转页数，一般列表低下都会有页码：1 2 3 …… 100
缺点：跳转页面过程中，有用户突然在前一页添加一条数据，那么就可能在翻页时看到前面的数据，用户会困惑。

2. /api/courses?max_page=1000

优点：对于手机那种下滑加载列表信息的情况就非常合适。至于统计是否到底部无数据，可以设计一个标识字段next，直至next为空，表示到达页底了。
缺点：显而易见，不能具体查第几页的信息。