基于.NetCore开发博客项目 StarBlog - (21) 开始开发RESTFul接口

前言

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

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

关于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方法。

接口开发规划

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

目前我把接口分成这几类

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

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

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

需要关注的其他东西

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

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

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

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

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

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

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

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

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

OK，本文就到这吧。

系列文章