[玩软件] RESTful 规范 Api 最佳设计实践
作者:CC下载站 日期:2019-10-23 00:00:00 浏览:53 分类:玩软件
RESTful是目前比较流行的接口路径设计规范,基于HTTP,一般使用JSON方式定义,通过不同HttpMethod来定义对应接口的资源动作,如:新增(POST)、删除(DELETE)、更新(PUT、PATCH)、查询(GET)等。
路径设计
在RESTful设计规范内,每一个接口被认为是一个资源请求,下面我们针对每一种资源类型来看下API路径设计。
路径设计的注意事项如下所示:
- 资源名使用复数
- 资源名使用名词
- 路径内不带特殊字符
- 避免多级URL
新增资源
新增资源使用POST方式来定义接口,新增资源数据通过RequestBody方式进行传递,如下所示:
curl -X POST -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users -d '{
"name": "恒宇少年",
"age": 25,
"address": "山东济南"
}'
新增资源后接口应该返回该资源的唯一标识,比如:主键值。
{
"id" : 1,
"name" : "恒宇少年"
}
通过返回的唯一标识来操作该资源的其他数据接口。
删除资源
删除资源使用DELETE方式来定义接口。
根据主键值删除单个资源
curl -X DELETE https://api.yuqiyu.com/v1/users/1
将资源的主键值通过路径的方式传递给接口。
删除多个资源
curl -X DELETE -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users -d '{ "userIds": [ 1, 2, 3 ] }'
删除多个资源时通过RequestBody方式进行传递删除条件的数据列表,上面示例中通过资源的主键值集合作为删除条件,当然也可以通过资源的其他元素作为删除的条件,比如:name
更新资源
在更新资源数据时使用PUT方式比较多,也是比较常见的,如下所示:
curl -X PUT -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users/1 -d '{
"name": "恒宇少年",
"age": 25,
"address": "山东济南"
}'
查询单个资源
唯一标识查询单个资源
curl https://api.yuqiyu.com/v1/users/1
通过唯一标识查询资源时,使用路径方式传递标识值,体现出层级关系。
非唯一标识查询单个资源
curl https://api.yuqiyu.com/v1/users?name=恒宇少年
查询资源数据时不仅仅都是通过唯一标识值作为查询条件,也可能会使用资源对象内的某一个元素作为查询条件。
分页查询资源
分页查询资源时,我们一般需要传递两个参数作为分页的条件,page代表了当前分页的页码,size则代表了每页查询的资源数量。
curl https://api.yuqiyu.com/v1/users?page=1&size=20
如果分页时需要传递查询条件,可以继续追加请求参数。
https://api.yuqiyu.com/v1/users?page=1&size=20&name=恒宇少年
动作资源
有时我们需要有动作性的修改某一个资源的元素内容,比如:重置密码。
用户的唯一标识在请求路径中进行传递,而修改后的密码通过RequestBody方式进行传递,如下所示:
curl -X POST -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users/1/actions/forget-password -d '{
"newPassword": "123456"
}'
版本号
版本号是用于区分Api接口的新老标准,比较流行的分别是接口路径、头信息这两种方式传递。
- 接口路径方式
我们在部署接口时约定不同版本的请求使用HTTP代理转发到对应版本的接口网关,常用的请求转发代理比如使用:Nginx等。
这种方式存在一个弊端,如果多个版本同时将请求转发到同一个网关时,会导致具体版本的请求转发失败,我们访问v1时可能会转发到v2,这并不是我们期望的结果,当然可以在网关添加一层拦截器,通过提取路径上班的版本号来进行控制转发。
# v1版本的请求
curl https://api.yuqiyu.com/v1/users/1
# v2版本的请求
curl https://api.yuqiyu.com/v2/users/1
- 头信息方式
我们可以将访问的接口版本通过HttpHeader的方式进行传递,在网关根据提取到的头信息进行控制转发到对应版本的服务,这种方式资源路径的展现形式不会因为版本的不同而变化。
# v1版本的请求
curl -H 'Accept-Version:v1' https://api.yuqiyu.com/users/1
# v2版本的请求
curl -H 'Access-Version: v2' https://api.yuqiyu.com/users/1
这两个版本的请求可能请求参数、返回值都不一样,但是请求的路径是一样的。
版本头信息的Key可以根据自身情况进行定义,推荐使用Accpet形式,详见 Versioning REST Services。
状态码
在RESTful设计规范内我们需要充分的里面HttpStatus请求的状态码来判断一个请求发送状态,本次请求是否有效,常见的HttpStatus状态码如下所示:
针对不同的状态码我们要做出不同的反馈,下面我们先来看一个常见的参数异常错误响应设计方式:
# 发起请求
curl -X POST -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users -d '{
"name": "",
"age": 25,
"address": "山东济南"
}'
# 响应状态
HttpStatus 200
# 响应内容
{
"code": "400",
"message": "用户名必填."
}
在服务端我们可以控制不同状态码、不同异常的固定返回格式,不应该将所有的异常请求都返回200,然后对应返回错误,正确的方式:
# 发起请求
curl -X POST -H 'Content-Type: application/json' https://api.yuqiyu.com/v1/users -d '{
"name": "",
"age": 25,
"address": "山东济南"
}'
# 响应状态
HttpStatus 400
# 响应内容
{
"error": "Bad Request",
"message": "用户名必填."
}
响应格式
接口的响应格式应该统一。
每一个请求成功的接口返回值外层格式应该统一,在服务端可以采用实体方式进行泛型返回。
如下所示:
/**
* Api统一响应实体
* {@link #data } 每个不同的接口响应的数据内容
* {@link #code } 业务异常响应状态码
* {@link #errorMsg} 业务异常消息内容
* {@link #timestamp} 接口响应的时间戳
*
* @author 恒宇少年 - 于起宇
*/
@Data
public class ApiResponse<T> implements Serializable {
private T data;
private String code;
private String errorMsg;
private Long timestamp;
}
- data
由于每一个API的响应数据类型不一致,所以在上面采用的泛型的泛型进行返回,data可以返回任意类型的数据。
- code
业务逻辑异常码,比如:USER_NOT_FOUND(用户不存在)这是接口的约定
- errorMsg
对应code值得描述。
- timestamp
请求响应的时间戳
总结
RESTful是API的设计规范,并不是所有的接口都应该遵循这一套规范来设计,不过我们在设计初期更应该规范性,这样我们在后期阅读代码时根据路径以及请求方式就可以了解接口的主要完成的工作。
作者:恒宇少年
链接:https://www.jianshu.com/p/35f1d3222cde
来源:简书
猜你还喜欢
- 04-19 [软件技巧] 5个在Chrome浏览器上恢复已删除的历史记录的顶级方法
- 03-29 [软件技巧] 剪映专业版怎么把两个草稿合在一起
- 03-29 [玩软件] Linux 虚拟机使用 xshell 连接 (debian、kali、CentOS)
- 03-29 [软件问题] 解决 win10 命令行下运行 python 弹出 Windows 应用商店
- 03-29 [软件技巧] Anaconda安装教程以及Anaconda和pip配置国内镜像
- 03-29 [玩软件] LatticePHP-使用PHP生成点阵图
- 03-29 [软件问题] chrome、Edge浏览器显示“您的浏览器受管理”是被植入病毒或其它程序了吗?
- 03-29 [环境问题] 为Nginx和Apache配置多版本PHP、切割多个conf文件
- 03-29 [软件玩法] 配置frp实现内网穿透
- 03-29 [软件玩法] VMware虚拟机安装MacOS系统教程
- 03-29 [软件技巧] frp 实现内网穿透(Windows 版)
- 03-27 [软件应用] 谷歌商店,可以访问了
取消回复欢迎 你 发表评论:
- 精品推荐!
-
- 最新文章
- 热门文章
- 热评文章
[课程] 极客时间-从 0 开发一款 iOS App
[网赚相关] 最新网易云梯计划网页版,单机月收入5000+!!
[游戏娱乐] 《永恒空间2》v1.1.39656中文版
[摄影] 玩转手机摄影 | 滤镜手机支架
[美食] 春天最不能忘记吃的菜,脆甜爽口营养高,减肥、控糖都很合适
[美食] “湿气”最怕这种菜,三天两头吃一次!祛湿健脾一身轻,别不懂吃
[影视资讯] 2023-2025年所有“漫威电影和剧集”上映播出时间整理
[经验] 摆地摊的八大禁忌
[游戏娱乐] 《驱灵者:新伊甸的幽灵》v1.4.1中文版
[游戏娱乐] 《诅咒村庄》v1.0.0中文版
[资料] [大学期末救急课] 猴博士+高斯课堂+斐多课堂,全集视频合集
[云资源] 价值2万元的老男孩Python教程
[书库] 史上最全摄影书推荐(附700本PDF版打包下载)
[云资源] 花了一千多元买的私人健身教程
[下载工具] Internet Download Manager 6.42.7 (IDM)
[影视] 灌篮高手 WEB-DL版下载/Slam Dunk/スラムダンク/灌篮高手:THE FIRST/灌篮高手电影版 2022 The First Slam Dunk 61.35G
[即时通讯] 腾讯QQ PC版9.7.22.29315去广告绿色纯净版
[开发环境] PhpStorm2023中文激活版v2023.3.3 正式版
[资料] 3000 套电影电视剧 LOGO 宣传片常用音效合集包
[安卓软件] 酷我音乐APP_v10.7.6.4 去广告破解豪华VIP版
[云资源] 价值2万元的老男孩Python教程
[影视] 灌篮高手 WEB-DL版下载/Slam Dunk/スラムダンク/灌篮高手:THE FIRST/灌篮高手电影版 2022 The First Slam Dunk 61.35G
[云资源] 花了一千多元买的私人健身教程
[书库] 史上最全摄影书推荐(附700本PDF版打包下载)
[动画] 北斗神拳(1984) [两季合集] [MKV]
[资料] 抗战阵亡将士资料+续编
[电视剧] 三体 (2024) 全8集 网飞版本 中文字幕 合集
[影视] 三大队 WEB-DL版下载/Endless Journey/请转告局长,三大队任务完成了 2023 三大队 6.7G
[纪录片] 河西走廊【10集 国语 中文字幕 1080P 10.8G MP4】
[影视] 涉过愤怒的海 WEB-DL版下载/怒海 / Across the Furious Sea 2023 涉过愤怒的海 26.3G
- 最新评论
-
我想看看mw2ddyy 评论于:04-26 好东西阿zfy123123 评论于:04-18 谢谢楼主xiaoqi 评论于:04-12 勿在线解压,勿手机解压,请在电脑上用最新款压缩软件解压!推荐360压缩或者好压CC下载站 评论于:04-10 无法解压啊,客服能不能给个解压教程ravengrey 评论于:04-10 谢谢支持!!CC下载站 评论于:03-26 很棒的资源,感谢分享云体风身 评论于:03-26 感谢分享,好东西云体风身 评论于:03-26 谢谢支持!CC下载站 评论于:03-14 央视精品,感谢付出提供。qwer9009 评论于:03-14
- 热门tag