2022-06-09
devops
00
请注意,本文编写于 624 天前,最后修改于 623 天前,其中某些信息可能已经过时。

目录

Restful概念
协议
http方法
使用名词
列表页 /users
状态码
错误处理
消息
错误消息
版本
返回结果

Restful概念

representational state transfer 表现层状态转移, 表现层就是WEB的uri(资源), rest指资源的状态发生变化,资源的增删改查,资源发生了改变。

访问一个资源 http://10.8.8.8/index.jsp , GET 获取资源, POST 提交数据; URI不变,但是资源变化了

**注意:rest只是论文,没有标准;后来很多人尝试,有一种风格 叫restful, 如下: **

  1. 统一URL
  2. 不同的操作
  3. 达到状态转移,这种方式就是Restful

使用restful,注意的问题如下:

协议

可以使用http, https https: 更安全

http方法

对url资源执行的动作

动作(http请求方法)说明
GET资源; 多个,1个
POST创建新资源;多个,1个
PUT资源完整修改;多个,1个
PATCH资源的某1项修改;多个,1个
DELETE删除资源;多个,1个

使用名词

URL指向资源,表现的是资源, 应该使用名词表达,而不是动词表达

  • 只需要名称,不要出现动词(路径,查询字符串)。动词由Http提供
  • 英文名词统一复数
描述错误正确
获取多个用户GET http://localhost/get_all_users 其中有动词GET http://localhost/users
获取1个 id=1的用户GET http://localhost/user/1 资源名词非复数GET http://localhost/users/1
创建多个用户POST http://localhost/add_users 其中有动词POST http://localhost/users
更新1个用户 id=1的用户POST http://localhost/update_users 其中有动词PUT http://localhost/users/1
删除资源 id=1的用户POST http://localhost/users/1?action=del 查询字符串有动词DELETE http://localhost/users/1
id=1的用户,部分内容修改PATCH http://localhost/users/1

对人的管理,只需要2类

  • 列表页 /users 查加删
    • GET 获取; POST 添加;(与ID无关)
  • 详情页 /users/<int:id>
    • GET 获取; PUT/PATCH 更新; DELETE 删除 (与ID相关)

对文章的管理

  • /posts
  • /posts/<int: id>

子资源访问

描述错误正确
获取id=1的用户的所有文章GET http://localhost/get_user_blogs?id=1 其中有动词
GET http://localhost/getuserblogs?id=1
GET http://localhost/GetUserBlogs?id=1
GET http://localhost/users/1/posts
获取id=1的用户的id=2的文章GET http://localhost/users/1/posts/2

之前的风格,是查询参数带数据。淘汰 而且风格不统一

restful风格,是URL路径自然带数据。最佳实践 风格统一,代码好 1用户 2号博客

列表页 /users

  • 列表页 /users 查加删
    • GET 获取; POST 添加;(与ID无关)
  • 详情页 /users/<int:id>
    • GET 获取; PUT/PATCH 更新; DELETE 删除 (与ID相关)

/users 默认返回所有数据,这样不行,一张表180G怎么办?数据库卡死了, 需要分页

描述URL描述sql
用户查询,分页/users?page=1&pagesize=20 对数据加要求,非业务数据 查询字符串
/users/page/1 这样好像是users下的业务 不好
第1页20个用户SELECT * FROM history OFFSET (page-1)*20 LIMIT 20;
用户查询 ,过滤/users?name=tom
/posts?tag=python
过滤tom用户
过滤python标签的博客
SELECT * FROM history where name="tom";
用户查询,排序/users?page=1&pagesize=20&sort=name.desc 单列排序
/users?page=1&pagesize=20&sort=name.asc,gender.desc 多列排序
/users?page=1&pagesize=20&sort=-name,id 简化 默认正,-表示逆序
第1页20个用户按姓名排序SELECT * FROM history ORDER BY name DESC OFFSET (page-1)*20 LIMIT 20
SELECT * FROM history ORDER BY name ASC,gender DESC OFFSET (page-1)*20 LIMIT 20

状态码

描述方法说明status
成功获取资源GETOK200
成功创建或修改POST,PUT,PATCHCREATED201
成功删除DELETENO CONTENT204
请求错误:GET参数问题;PUT提交数据错误ALLBad Request400
未认证ALLUnauthorized401
认证通过,无权限ALLForbidden403
认证通过,找的资源不存在ALLNot Found404
服务端ALLInternal Server Error500

错误处理

单单从状态码无法详细描述错误信息

进程成功,状态码0,非0 有问题

消息

json
{ "error": "User Not Found" }

错误消息

json
{ "code": 10056, "message": "Invalid ID", # 简单的描述 "description": "More details" # 详细的描述 }

大系统中,让用户给code,消息,描述。

版本

项目用的人越多,你不能随便修改。你需要升级项目,以便后续维护。

减少影响的方法

  1. 新接口新名称,旧接口,加参数,有默认值。
  2. 接口加版本信息

使用版本号,v2有2种风格

x.x.x 语义化版本, 发布时最终品才加x.x.x 而URL就大版本,小版本是兼容的。

  1. 第1个是大版本,不兼容
  2. 第2个是功能版本,兼容
  3. 第3个是补丁修复

返回结果

方法路径状态描述
GET/posts200返回所有文章 列表 或JS的数组
GET/posts/10200返回id=10的文章对象
POST/posts201创建新的文章并返回这个新创建的对象
PUT/posts/10201更新id=10的文章,并返回这个被更新的对象
PATCH/posts/10201部分更新id=10的文章,并返回这个被更新的对象
DELETE/posts/10204删除id=10的文章返回一个空对象, 或不返回任何对象

本文作者:mykernel

本文链接:

版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!