REST API学习和总结_rest api获取学习反馈-优快云博客

本文链接：https://blog.youkuaiyun.com/su371128017/article/details/110450069

本文介绍了REST API的设计理念，包括资源定义、接口命名、过滤信息和状态码的使用。强调URL应由名词组成，避免动词，利用HTTP方法表示操作。过滤信息通过URL参数实现，状态码用于清晰传达请求结果。RESTful API的设计旨在提高接口的易理解和使用性。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

学习原文见：https://github.com/Snailclimb/JavaGuide/blob/master/docs/system-design/coding-way/RESTfulAPI%E7%AE%80%E6%98%8E%E6%95%99%E7%A8%8B.md

前言

REST API可以设计出更加简洁明了的接口，帮助实现系统之间的信息传递和调用关系。已经设计过并开发对接过银行和银联的API，一直用给方法命名的方式来命名接口，也一直在思考怎么能更高效简洁的定义API。这个规范可以借鉴参考，刚刚好正中下怀，解答了我的很多困惑。

总结思考

1. REST简单说为了实现为了获取资源信息或对其实施动作的规范。从发出请求方式，到返回内容格式，以及动作完成后资源。

2. 原来的设计接口过程中，用了太多v+n的组合。目的是为了给自己提醒也为了方便对接的开发，看来可以借鉴REST，但不能直接全盘套用。虽然用GET和POST方法就可以区分是插入还是查找行为，但是和你对接的人也要接受这样的规则才行。

3. 关于classes和schools的层级，目前所参与的项目都无法自定义url，只有gateway.do一个层级。所有的接口相当于平铺一层，根据的参数中method用名称来区分。

1、定义

RESTful API 可以你看到 url + http method 就知道这个 url 是干什么的，让你看到了 http 状态码（status code）就知道请求结果如何。

action	description	example
POST	请求创建资源	/classes：新建一个班级
GET	请求获取资源	/classes：列出所有班级
DELETE	请求删除资源	/classes/12：删除编号为 12 的班级
PUT	请求更新资源	/classes/12：更新编号为 12 的班级
PATCH	请求批量更新	使用的比较少

REST, 即 REpresentational State Transfer 的缩写，全称是 Resource Representational State Transfer ：翻译过来就是 “资源”在网络传输中以某种“表现形式”进行“状态转移”

资源（Resource） ：我们可以把真实的对象数据称为资源。每一种资源与URI（统一资源定位符）对应，比如/class/12：来获取这个班级信息。也包含子资源，比如 /classes/classId/teachers：列出某个指定班级的所有老师的信息

表现形式（Representational）"资源"的外在表现形式，比如 json，xml，image,txt

状态转移（State Transfer）资源的状态，可能在通过增删改查（通过 HTTP 动词实现）后引起资源状态的改变。

2、路径（接口命名）

路径又称"终点"（endpoint），表示 API 的具体网址

网址中不能有动词，只能有名词，API 中的名词也应该使用复数。因为 REST 中的资源往往和数据库中的表对应，而数据库中的表都是同种记录的"集合"（collection）。如果 API 调用并不涉及资源（如计算，翻译等操作）的话，可以用动词。 比如：GET /calculate?param1=11&param2=33
建议用中杠 - 不用下杠 _ 比如邀请码写成 invitation-code而不是 ~~invitation_code~~

接口尽量使用名词，禁止使用动词。下面是一些例子：

GET    /classes：列出所有班级
POST   /classes：新建一个班级
GET    /classes/classId：获取某个指定班级的信息
PUT    /classes/classId：更新某个指定班级的信息（一般倾向整体更新）
PATCH  /classes/classId：更新某个指定班级的信息（一般倾向部分更新）
DELETE /classes/classId：删除某个班级
GET    /classes/classId/teachers：列出某个指定班级的所有老师的信息
GET    /classes/classId/students：列出某个指定班级的所有学生的信息
DELETE classes/classId/teachers/ID：删除某个指定班级下的指定的老师的信息

不推荐：

/getAllclasses
/createNewclass
/deleteAllActiveclasses

3、过滤信息（Filtering）

理清资源的层次结构，比如业务针对的范围是学校，那么学校会是一级资源:/schools，老师: /schools/teachers，学生: /schools/students 就是二级资源。

如果我们在查询的时候需要添加特定条件的话，建议使用 url 参数的形式。比如我们要查询 state 状态为 active 并且 name 为 guidegege 的班级：

GET /classes?state=active&name=guidegege

比如我们要实现分页查询：

GET /classes?page=1&size=10 //指定第1页，每页10个数据

4、状态码（Status Codes）

状态码范围：

对于状态码，搜索的网络上不同人的声音，并结合自身参与的系统。对于对接人员，越清晰的状态码肯定越好，但是对于设计人员，如果有一些变更和调整，就会显得比较难以进行，系统都是在迭代中前进，因此并不一定所有的状态码都要这么清晰，最重要的是分清楚前后端的错误，数据库错误，网络等错误的大概方向。

RESTful 的极致是 hateoas ，但是这个基本不会在实际项目中用到。（hateoas没有了解，没有见过，先留个脚印）