全球热点评!基于.NetCore开发博客项目 StarBlog - (21) 开始开发RESTFul接口

首页 > 焦点 > 正文
2022-12-19 08:31:50

来源:

1前言

最近电脑坏了,开源项目的进度也受到一些影响

这篇酝酿很久了,作为本系列第二部分(API接口开发)的第一篇,得想一个好的开头,想着想着就鸽了好久,索性不扯那么多了,直接开写吧~


(资料图)

2关于RESTFul

网上很多相关的文章都要把RESTFul历史来龙去脉给复制一遍,所以我这就不重复了,现在主要的HTTP接口风格就俩:RPC和RESTFul。

举个例子就可以看出这俩的区别

RPC风格

分别是增删改查的接口

操作HTTP方法URL
post/blog/add
post/blog/deleteById
post/blog/updateById
get/blog/getAll

可以看出RPC风格的特点:

基本就是用post和get这俩方法来操作接口URL的命名跟函数命名一样,都是动词,一目了然

PS:RPC这种几乎一个团队一个风格,我见过有人把所有接口都做成post方法,然后请求参数全部用json格式放在body里的。

关键是这个请求参数还不统一,同个项目不同开发人员写的请求参数格式不一致,很恶心。(微信有些接口也是这样)

RESTFul风格

分别是增删改查的接口

操作HTTP方法URL
post/blog/
delete/blog/{id}/
put/blog/{id}/
get/blog/
get/blog/{id}/

可以看出RESTFul风格的特点:

利用各种HTTP方法来实现增删改查(其实还有patch、head这些方法,不展开了)URL的命名是名词,以资源名称作为URL,更统一使用get获取资源,方便后端、客户端、网关这些地方做缓存,提高性能接口返回值

除了请求接口,RESTFul还建议接口返回的时候根据不同状态使用不同的HTTP状态码。

以下是HTTP定义的五类状态码。

类别描述
1xx:信息通信传输协议级信息。
2xx:成功表示客户端的请求已成功接受。
3xx:重定向表示客户端必须执行一些其他操作才能完成其请求。
4xx:客户端错误此类错误状态代码指向客户端。
5xx:服务器错误服务器负责这些错误状态代码。
比如添加了数据,返回 201 (created)添加、更新、删除这些不需要返回数据的接口,返回 204 (no content)没登录,返回 401 (unauthorized)找不到,返回 404 (not found)没权限,返回 403 (forbidden)

这样就很清晰了,看接口返回的状态码就能知道结果如何。

在一些前端ajax库(比如axios)中,返回码如果是4xx或5xx,就会抛出异常,这样访问逻辑就可以根据错误做出一些提示。

例子

假设接口返回结构是这样

{"successful":true,"message":"请求成功","data":[{...},{...},{...}]}

请求接口的 JavaScript 代码如下

axios.get("/blog/").then(res=>msg.success(`请求成功,返回信息:${res.data.message}`)).catch(res=>msg.error(`请求失败,返回信息:${res.data.message}`))

但是!实际场景很复杂,HTTP标准状态码就40个,根本不够用啊。

所以这些HTTP状态码只能对返回值做个大概的分类,复杂系统还是得自己定义一套错误码。

小结

这俩各有优劣,RESTFul看起来比较统一优雅,但表达能力有限;RPC的URL命名看起来比较随意,不过自由发挥的空间也很大。

我个人是比较倾向RESTFul风格的,所以StarBlog使用了RESTFul风格的接口,不过这并不能满足全部功能需求,所以参考Django的RestFramework,将RESTFul和RPC稍微结合一下。

举个例子:要在博客增删改查的基础上增加设置置顶、点赞等功能。

操作HTTP方法URL
设置置顶post/blog/{id}/setTop/
点赞post/blog/{id}/thumbUp/
获取置顶文章get/blog/getTop/

可以看到这种缝合怪是以RESTFul为基础,增删改查以外的功能,在对应的资源上使用RPC风格。

setTop/ thumbUp/ getTop这些动词在RestFramework里面也叫 action ,意为对一系列资源执行的动作。

关于HTTP方法,对资源有修改的,使用post方法,没有修改单纯读取的,使用get方法。

3接口开发规划

本系列文章更新顺序跟StarBlog博客开发的顺序基本一致,即在已有MVC架构网站的基础上,增加RESTFul接口,用于管理后台(前后端分离)对博客进行配置管理。

目前我把接口分成这几类

auth - 认证授权,顾名思义,后面会细说admin - 管理员相关,主要功能有配置管理、访问记录、系统监控等blog - 博客相关,功能就是文章、分类、图片等信息的crudcommon - 公用接口,StarBlog除了博客功能外,还以接口形式提供了一些小功能,如一句诗、一言、随机图片、主题切换等test - 测试接口,用于一些功能测试,在正式环境会关闭访问links - 友情链接管理,这个功能比较复杂,单独做成一个分类

后续会有更多类似友情链接这样比较复杂的功能加入(比如评论),这种会单独做成一个分类。

PS:之前在开发博客前台的时候,把大部分功能都写在了 services里面,现在开发接口的时候就派上用场了,很多逻辑都是通用的,在接口的controller里面只需要调用这些 services就可以了。

4需要关注的其他东西

本文不涉及具体实现,只是作为RESTFul接口开发部分的前言或者大纲,接口开发看似就crud四个操作很简单,实际上比想象的复杂。

例如,获取文章列表接口,博客的文章数量会很多,不可能一个接口返回所有文章信息,因此要做分页处理,同时我们还希望能在文章列表实现关键词过滤、分类、状态筛选、排序等功能;

已登录用户才能发表评论,管理员才能管理文章,因此需要实现认证授权、角色管理等功能;

同一时间可能有很多人访问博客(或者是爬虫),需要对接口做限流处理,以免程序崩溃;

接口数量多起来了,swagger显示太杂乱,需要对接口分组,或者更换swagger前端;

正式环境不想让用户看到swagger接口文档,可以隐藏或者给swagger加锁;

频繁访问的资源,可以使用服务端缓存提升性能,减轻IO压力,使用客户端缓存降低服务器流量;

耗时操作(如批量导出文章、发送短信通知)放到异步任务队列(或者后台任务)里执行;

以上列举的种种只是我在撰写本文的当下考虑博客需要用到的,实际上应该还有很多。只能说后端的水很深,开发本项目的过程也是一个不断探索、实践的过程,“No silver bullet”,没有任何技术能适用全部场景,只能在不断的积累中得出某个场景下的最佳实践。

OK,本文就到这吧。

5系列文章基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客?基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目基于.NetCore开发博客项目 StarBlog - (3) 模型设计基于.NetCore开发博客项目 StarBlog - (4) markdown博客批量导入基于.NetCore开发博客项目 StarBlog - (5) 开始搭建Web项目基于.NetCore开发博客项目 StarBlog - (6) 页面开发之博客文章列表基于.NetCore开发博客项目 StarBlog - (7) 页面开发之文章详情页面基于.NetCore开发博客项目 StarBlog - (8) 分类层级结构展示基于.NetCore开发博客项目 StarBlog - (9) 图片批量导入基于.NetCore开发博客项目 StarBlog - (10) 图片瀑布流基于.NetCore开发博客项目 StarBlog - (11) 实现访问统计基于.NetCore开发博客项目 StarBlog - (12) Razor页面动态编译基于.NetCore开发博客项目 StarBlog - (13) 加入友情链接功能基于.NetCore开发博客项目 StarBlog - (14) 实现主题切换功能基于.NetCore开发博客项目 StarBlog - (15) 生成随机尺寸图片基于.NetCore开发博客项目 StarBlog - (16) 一些新功能 (监控/统计/配置/初始化)基于.NetCore开发博客项目 StarBlog - (17) 自动下载文章里的外部图片基于.NetCore开发博客项目 StarBlog - (18) 实现本地Typora文章打包上传基于.NetCore开发博客项目 StarBlog - (19) Markdown渲染方案探索基于.NetCore开发博客项目 StarBlog - (20) 图片显示优化基于.NetCore开发博客项目 StarBlog - (21) 开始开发RESTFul接口

标签:

THE END

相关热点

6月20日,资本邦了解到,一改上周的强势走势,今日,新东方在线(01797 HK)及新东方(09901 HK)H股股价均下跌。截至港股收盘,新东方在线跌32
2022-06-20 17:29:10
新华社电 上海市文化和旅游局近日发布《上海市密室剧本杀内容备案管理规定(征求意见稿)》,并截至12月8日面向社会公众广泛征求意见。这
2021-11-19 13:46:03
《中国证券报》17日刊发文章《备战2022 基金经理调仓换股布新局》。文章称,距离2021年结束仅剩一个多月,基金业绩分化明显。部分排名靠前
2021-11-19 13:46:03
交通运输部办公厅 中国人民银行办公厅 中国银行保险监督管理委员会办公厅关于进一步做好货车ETC发行服务有关工作的通知各省、自治区、直
2021-11-19 13:45:58
新华社北京11月17日电 题:从10月份市场供需积极变化看中国经济韧性新华社记者魏玉坤、丁乐读懂中国经济,一个直观的视角就是市场供需两端
2021-11-19 13:45:58
全国教育财务工作会议披露的消息称,2020年,中国国家财政性教育经费投入达4 29万亿元,占GDP总量的4 206%,我国国家财政性教育经费支出占G
2021-11-19 13:45:48
如果你也热爱“种草”,前方高能预警!让你心心念念、“浏览”忘返的网络平台,可能早已成为一块块“韭菜地”。近日,据《半月谈》报道,有...
2021-11-19 13:45:48
日前,工业和信息化部印发《“十四五”信息通信行业发展规划》(以下简称《规划》),描绘了未来5年信息通信行业的发展趋势。《规划》指出...
2021-11-19 13:45:40
本报讯(中青报·中青网记者 周围围)2021年快递业务旺季正式拉开帷幕。国家邮政局监测数据显示,仅11月1日当日,全国共揽收快递包裹5 69
2021-11-19 13:45:40
人民网曼谷11月17日电 (记者赵益普)17日上午,中国援柬埔寨第七批200万剂科兴新冠疫苗抵达金边国际机场。当天,柬埔寨政府在机场举行了
2021-11-19 13:45:35
金坛压缩空气储能国家试验示范项目主体工程一角受访者供图依托清华大学非补燃压缩空气储能技术,金坛压缩空气储能项目申请专利百余项,建立
2021-11-19 13:45:35
视觉中国供图42亿立方米据有关部门预计,今年山西煤炭产量有望突破12亿吨,12月份山西外送电能力将超过900万千瓦,今冬明春煤层气产量将达4
2021-11-19 13:44:34
14省份相继发布2021年企业工资指导线——引导企业合理提高职工工资今年以来,天津、新疆、内蒙古、陕西、西藏、山东、江西、山西、福建、四
2021-11-19 13:44:34
中新网客户端北京11月18日电 (记者 谢艺观)“一条路海角天涯,两颗心相依相伴,风吹不走誓言,雨打不湿浪漫,意济苍生苦与痛,情牵天下喜
2021-11-19 13:44:31
近日,交通运输部等三部门发布《关于进一步做好货车ETC发行服务有关工作的通知》。通知提到,对不具备授信条件的用户,商业银行可在依法合
2021-11-19 13:44:31
欧莱雅面膜陷优惠“年度最大”风波 涉及该事件集体投诉超6000人次美妆大牌双十一促销翻车?近日,因预售价格比双十一现货贵出66%,欧莱雅
2021-11-19 13:44:13
43 6%受访者会在工作两三年后考虑跳槽54 3%受访者认为跳槽对个人职业发展有利有弊如今对不少年轻人来说,想对一份工作“从一而终”不太容易
2021-11-19 13:44:13
超八成受访青年表示如有机会愿意开展副业 规划能力最重要64 4%受访青年指出做副业跟风心态最要不得如今,“身兼数职”已成为年轻人当中的
2021-11-19 13:44:01
发展氢能正当其时【科学随笔】氢能是一种二次能源,它通过一定的方法利用其他能源制取,具有清洁无污染、可储存、与多种能源便捷转换等优点
2021-11-19 13:44:01
“千杯不醉”的解酒“神药”能信吗?专家:网红“解酒药” 其实不算药俗话说,“酒逢知己千杯少”,酒一直是国人饭桌上至关重要的存在。尽...
2021-11-19 13:43:57
最新文章

相关推荐