前言

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

这篇酝酿很久了,作为本系列第二部分(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 - (21) 开始开发RESTFul接口的更多相关文章

  1. 基于.NetCore开发博客项目 StarBlog - (6) 页面开发之博客文章列表

    系列文章 基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客? 基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目 基于.NetC ...

  2. 基于.NetCore开发博客项目 StarBlog - (7) 页面开发之文章详情页面

    系列文章 基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客? 基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目 基于.NetC ...

  3. 基于.NetCore开发博客项目 StarBlog - (8) 分类层级结构展示

    系列文章 基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客? 基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目 基于.NetC ...

  4. 基于.NetCore开发博客项目 StarBlog - (9) 图片批量导入

    系列文章 基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客? 基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目 基于.NetC ...

  5. 基于.NetCore开发博客项目 StarBlog - (10) 图片瀑布流

    系列文章 基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客? 基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目 基于.NetC ...

  6. 基于.NetCore开发博客项目 StarBlog - (11) 实现访问统计

    系列文章 基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客? 基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目 基于.NetC ...

  7. 基于.NetCore开发博客项目 StarBlog - (12) Razor页面动态编译

    系列文章 基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客? 基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目 基于.NetC ...

  8. 基于.NetCore开发博客项目 StarBlog - (13) 加入友情链接功能

    系列文章 基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客? 基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目 基于.NetC ...

  9. 基于.NetCore开发博客项目 StarBlog - (14) 实现主题切换功能

    系列文章 基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客? 基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目 基于.NetC ...

  10. 基于.NetCore开发博客项目 StarBlog - (15) 生成随机尺寸图片

    系列文章 基于.NetCore开发博客项目 StarBlog - (1) 为什么需要自己写一个博客? 基于.NetCore开发博客项目 StarBlog - (2) 环境准备和创建项目 基于.NetC ...

随机推荐

  1. Jpa常用API

    service中执行sql 根据请求参数拼接sql import javax.persistence.Query; import javax.persistence.EntityManager; @A ...

  2. 分布式存储系统之Ceph集群部署

    前文我们了解了Ceph的基础架构和相关组件的介绍,回顾请参考https://www.cnblogs.com/qiuhom-1874/p/16720234.html:今天我们来部署一个ceph集群: 部 ...

  3. 树莓派Zero 2 W(ubuntu-22.04)通过.NET6和libusb操作USB读写

    有这个想法的初衷 喜欢电子和DIY硬件的朋友对稚晖君应该都不陌生,他定期都会分享一些自己做的好玩的硬件,他之前做了一个ElectronBot桌面机器人我就很感兴趣,所以就自己也做了一个. 起初我只是自 ...

  4. 前端框架Vue------>第一天学习、Vue学习的路径、Vue官网(1)

    文章目录 1.学习目标 2.前端知识体系 2.1 前端三要素 2.2.MVVM 3.第一个Vue程序 4.Vue实例的生命周期 vue的官方文档:https://cn.vuejs.org/ 1.学习目 ...

  5. 一天五道Java面试题----第九天(简述MySQL中索引类型对数据库的性能的影响--------->缓存雪崩、缓存穿透、缓存击穿)

    这里是参考B站上的大佬做的面试题笔记.大家也可以去看视频讲解!!! 文章目录 1.简述MySQL中索引类型对数据库的性能的影响 2.RDB和AOF机制 3.Redis的过期键的删除策略 4.Redis ...

  6. Go | 讲解GOROOT、GOPATH、GOBIN

    前言 Go(又称 Golang)是 Google 开发的一种静态强类型.编译型.并发型,并具有垃圾回收功能的编程语言.Go 被誉为是未来的服务器端编程语言. Go是一门全新的静态类型开发语言,具有自动 ...

  7. 一篇文章带你了解轻量级Web服务器——Nginx简单入门

    一篇文章带你了解轻量级Web服务器--Nginx简单入门 Nginx是一款轻量级的Web服务器/反向代理服务器及电子邮件代理服务器 在本篇中我们会简单介绍Nginx的特点,安装,相关指令使用以及配置信 ...

  8. IO模型及高性能网络架构分析

    前言 操作系统一次IO调用过程 应用程序发起的一次IO操作包含两个阶段: IO调用:应用程序进程向操作系统内核发起调用. IO执行:操作系统内核完成IO操作. 操作系统内核完成IO操作还包括两个过程: ...

  9. rocky二进制安装mysql8.0

    (ubuntu的有点问题) 点击查看代码 #!/bin/bash Version=`cat /etc/os-release |awk -F'"| ' '/^NAME/{print $2}'` ...

  10. 在ubuntu 上安装golang

    https://golang.google.cn/dl/ 方式一 下载安装包 wget https://golang.google.cn/dl/go1.19.linux-amd64.tar.gz 解压 ...