前言

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

这篇酝酿很久了，作为本系列第二部分（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，本文就到这吧.

系列文章

• 基于.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接口

最后此篇关于基于.NetCore开发博客项目StarBlog-(21)开始开发RESTFul接口的文章就讲到这里了,如果你想了解更多关于基于.NetCore开发博客项目StarBlog-(21)开始开发RESTFul接口的内容请搜索CFSDN的文章或继续浏览相关文章，希望大家以后支持我的博客！ 。