A股上市公司传智教育(股票代码 003032)旗下技术交流社区北京昌平校区

 找回密码
 加入黑马

QQ登录

只需一步,快速开始

© Huang_TD 初级黑马   /  2019-6-21 13:53  /  1581 人查看  /  0 人回复  /   0 人收藏 转载请遵从CC协议 禁止商业使用本文

### restful接口的设计规范

restful设计方法规定了一下几个方面:

- 域名

  - 尽量每个域名(二级域名)完成每块功能
  - 如果API很简单就放在主域名下

- 版本

  - 应该将API的版本号放入URL路径中;示例:

  ```python
  http://www.example.com/app/1.0/foo
  http://www.example.com/app/1.1/foo
  http://www.example.com/app/2.0/foo
  ```

  - 另一种方式就是将版本号放在HTTP请求头中,这种方法没有放在url中方便,直观

- 路径

  - 资源路径中只能有名词,不能有动词,而且所用的名词往往与数据库的表名相对应
  - API中的名词应该使用复数

- Http动词(请求方式)

  - 常用的HTTP动词有下面四个(括号里是对应的SQL命令)
    - GET(SELECT):从服务器取出资源(一项或多项)
    - POST(CREATE):在服务器新建一个资源
    - PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)
    - DELETE(DELETE):从服务器删除资源
  - 还有三个不常用的HTTP动词
    - PATCH(UPDATE):在服务器更新(更新)资源(客户端提供改变的属性)
    - HEAD:获取资源的元数据
    - OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的

- 参数

  - 根据不同的请求方式,传递参数的格式也不一样;一般来说
    - 使用GET方式请求查询数据库数据:
      - 如果是查询一条数据则将数据的id以路径拼接参数的方式传递给服务器
      - 如果是要查询所有的数据则直接在路径中使用API的复数名词即可,不用跟数据的id;
      - 如果要查询表中的多条数据则以查询所有数据的方式,然后将筛选条件一个查询参数的格式传给服务器

- 过滤信息

  - 如果返回结果很多需要对返回结果进行过滤的话,过滤参数要以查询参数的方式进行传递(如:对返回结果的数量,指定第几页或指定开始位置等都可以通过查询参数进行传递)

- 状态码

  - 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 - [*]:服务器发生错误,用户将无法判断发出的请求是否成功

- 错误处理

  - 如果请求错误,服务器向用户返回的信息一般来说是以error为键名,出错的信息作为键值

- 返回结果

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

0 个回复

您需要登录后才可以回帖 登录 | 加入黑马