Github RESTful API规范参考 https://docs.github.com/en/rest

RESTful资料
https://www.imooc.com/learn/811 实战
https://www.imooc.com/learn/1048 restful api 测试

RESTful API开发核心知识点

  1. API版本化
  2. API应用授权，接口保护
    1. 认证，安全考虑点
    2. 维持认证
  3. 响应规范
    1. get
    2. post
    3. delete
    4. put
    5. patch
  4. 错误处理
    1. 参数错误
    2. 404
    3. 403
    4. 401
    5. 400
    6. 500
  5. 速率限制，限流
  6. 黑白名单
    1. Forbidden
    2. IP

什么是 RESTful 架构？

RESTful是什么？
Resource Representational State Transfe

  • 资源（Resource）?：我们可以把真实的对象数据称为资源。一个资源既可以是一个集合，也可以是单个个体
  • 表现形式（Representational
  • 状态转移（State Transfer）


  1. 每一个 URI 代表一种资源；
  2. 客户端和服务器之间，传递这种资源的某种表现形式比如 json，xml，image,txt 等
  3. 客户端通过特定的 HTTP 动词，对服务器端资源进行操作，实现”表现层状态转化”。

https://javamana.com/2021/09/20210922121422435u.html

常用的API请求

  1. 分页
  2. 搜索

REST 接口规范

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

动作

  • GET 请求从服务器获取特定资源。举个例子：?GET /classes（获取所有班级）
  • POST 在服务器上创建一个新的资源。举个例子：?POST /classes?（创建班级）
  • PUT 更新服务器上的资源（客户端提供更新后的整个资源）。举个例子：?PUT /classes/12（更新编号为 12 的班级）
  • DELETE 从服务器删除特定的资源。举个例子：?DELETE /classes/12（删除编号为 12 的班级）
  • PATCH 更新服务器上的资源（客户端提供更改的属性，可以看做作是部分更新），使用的比较少，这里就不举例子了
    1. GET /classes：列出所有班级
    2. POST /classes：新建一个班级
    3. GET /classes/classId：获取某个指定班级的信息
    4. PUT /classes/classId：更新某个指定班级的信息（一般倾向整体更新）
    5. PATCH /classes/classId：更新某个指定班级的信息（一般倾向部分更新）
    6. DELETE /classes/classId：删除某个班级
    7. GET /classes/classId/teachers：列出某个指定班级的所有老师的信息
    8. GET /classes/classId/students：列出某个指定班级的所有学生的信息
    9. DELETE classes/classId/teachers/ID：删除某个指定班级下的指定的老师的信息

路径（接口命名）

路径又称”终点”（endpoint），表示 API 的具体网址。实际开发中常见的规范如下：

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

过滤信息 Filtering

eggjs常用的请求方式

  • router.get()
  • router.post()
  • router.put()
  • router.del()

post, put, del, 获取请求参数，都是通过 ctx.request.body获取

restful的缺点：

  • 聚合数据有冗余的数据返回，例如，只要用户名，也返回了一堆创建时间和修改时间
  • GraphQL，专注于数据聚合，要什么就返回什么

get获取参数

ctx.query

/user/list?id=100

ctx.params

/user/list-detail/100

post put del获取参数

ctx.request.body

egg-validate参数验证

https://eggjs.org/zh-cn/tutorials/restful.html#%E5%BC%80%E5%90%AF-validate-%E6%8F%92%E4%BB%B6

Controller 中 this.ctx.validate()进行参数校验，失败抛出异常。

  1. async index() {
  2.   const { ctx } = this;
  3.   const rule = {
  4.     id: 'string',
  5.   };
  7.   // 校验 `ctx.request.body` 是否符合我们预期的格式
  8.   // 如果参数校验未通过，将会抛出一个 status = 422 的异常
  9.   // 验证错误状态码:422; success: undefined
  10.   ctx.validate(rule, ctx.params);
  11. }

参数校验失败，直接返回 422，阻塞页面渲染，优化：

  • 通过中间件的方式优化参数校验错误的逻辑

image.png