RESTful设计方法

发布时间：2023-12-25 15:17:24 所属栏目：教程来源：DaWei

导读： 在初步了解了 RESTful 之后，我们接到一项任务，需要为一所学校开发一套师生管理系统，客户要求所开发的系统能在 PC 桌面通过浏览器使用，而且日后还想开发 IOS 和 Android 应用。了解需求之

在初步了解了 RESTful 之后，我们接到一项任务，需要为一所学校开发一套师生管理系统，客户要求所开发的系统能在 PC 桌面通过浏览器使用，而且日后还想开发 IOS 和 Android 应用。了解需求之后，我们毫不犹豫选择了前后端分离的开发模式，并且决定遵从时下最为流行的 RESTful 规范。接下来，我们就以后端开发人员的角色，一起来了解整个开发过程。

路径即"终点"（endpoint），是访问 API 的具体网址，通过访问每个网址，可以获取到相应的资源（resource）。在师生管理系统中，所谓资源，就是我们想获取的信息，比如获取 3 年 2 班所有学生姓名，获取小明的年龄、成绩等。

路径须满足以下规范：

1. 资源路径中应当使用名词，杜绝动词。资源路径中的名词，应当与数据库的表名相对应。

以下路径中包含动词，是不符合规范的例子，在实际工作中，应当避免。

/getStudents   ：获取学生信息
/listTeachers   ：获取老师信息
/retreiveStudentByID?Id=2020   ：获取ID为2020的学生信息
对于资源的操作，应该通过 HTTP 中的不同方法来区分处理资源的动作，资源路径中应当只包含名词。

GET /students ：将返回所有学生信息
POST /students ：将新增的学生信息存入数据库
GET /students/4 ：获取编号为4号的学生信息
PATCH（或）PUT /students/4 ：更新编号为4的学生信息

HTTP动词
对于资源的具体操作类型，由 HTTP 动词表示。
常用的 HTTP 动词有下面 4 个（括号里是对应的 sql 命令）。
GET（SELECT）：从服务器取出资源（一项或多项）
POST（CREATE）：在服务器新建一个资源
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）
DELETE（DELETE）：从服务器删除资源

还有 3 个不常用的 HTTP 动词。
PATCH（UPDATE）：在服务器更新(更新)资源（客户端提供改变的属性）
HEAD：获取资源的元数
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的

下面是一些例子。
GET /classes：列出所有班级
POST /classes：新建一个班级（上传文件）
GET /classes/ID：获取某个指定班级的信息
PUT /classes/ID：更新某个指定班级的信息（提供该班级的全部信息）
PATCH /classes/ID：更新某个指定班级的信息（提供该班级的部分信息）
DELETE /classes/ID：删除某个班级
GET /classes/ID/students：列出某个指定班级的所有学生
DELETE /classes/ID/students/ID：删除某个指定班级的指定学生

过滤信息（Filtering）
如果记录数量很多，服务器不可能都将它们返回给用户。API 应该提供参数，过滤返回结果。比如，我们想获取全校师生的个人信息，如果将这些信息一股脑地全部展示在网页上，是不明智也是不现实的。如果数据量太大，在实际开发中我们会采用分页展示的形式。另外，如果想在一次考试后，按照成绩高低展示学生信息，那么可以通过过滤信息来实现。

所谓过滤，就是在 URL 中添加一下限制参数。下面是一些常见的参数。
?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=score&order=asc：指定返回结果按照学生的成绩（score）正序（asc）排列顺序。
参数的设计允许存在冗余，即允许 API 路径和 URL 参数允许有重复。比如，想要查询某个班级所有学生信息，我们可以设计 GET /classes/ID/students 与 GET /students?class_id=ID 两种地址，任何一种都可得到相同的结果。

状态码（Status Codes）
服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的 HTTP 动词）。不同的状态码代表着不同的含义，比如以 2 开头的状态码通常代表服务器成功响应，3 开头的状态码代表发生了重定性（即跳转到了别的链接），4 开头的状态码通常表示客户端这边提供的信息有误，而 5 开头的状态码则表示服务器内部出现的错误。通过返回的状态码，用户即可判断请求成功与否，不成功问题在何处。

一些常用的状态码列举如下：
200 OK - [GET]：服务器成功返回用户请求的数据
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功
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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功
状态码的完全列表参见这里或这里。

错误信息
如果状态码是 4xx，服务器就应该向用户返回出错信息。一般来说，返回的信息是键值对形式的数据，将 error 作为键名，出错信息作为键值即可。比如，在一个提供查询学生信息的 API 中，要求客户端提供正确的 API key（可以理解为输入了正确的用户名和密码）才能访问，如果提供的 API key 不正确，此时服务器应拒绝访问，并返回错误信息。这样，客户端就知道了为何没能查到信息，修改成正确的 API key 即可。

{
error: "Invalid API key"
}

返回结果
针对不同操作，服务器向用户返回的结果应该符合以下规范。
GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

（编辑：百客网 - 百科网）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!