Spring+SpringMVC+MyBatis+easyUI整合进阶篇(一)设计一套好的RESTful API

写在前面的话

看了一下博客目录,距离上次更新这个系列的博文已经有两个多月,并不是因为不想继续写博客,由于中间这段时间更新了几篇其他系列的文章就暂时停止了,如今已经讲述的差不多,也就继续抽时间更新《Spring+SpringMVC+MyBatis+easyUI整合》这个系列了。

也看到github上有人催更教程,这个真的是没想到,也谢谢你们的肯定和支持了。

由于《整合优化篇》中关于代码优化及数据层优化的文章占了较大的篇幅,导致遗漏了几篇原计划要更新在《整合优化篇》中的文章,关于RESTful的改造和缓存功能的整合并没有做,这段时间会补充进来。

理解RESTful

REST(Representational State Transfer),中文翻译叫"表述性状态转移",它首次出现在2000年Roy Fielding的博士论文中,Roy Fielding是 HTTP 规范的主要编写者之一。他在论文中提到:"我这篇文章的写作目的,就是想在符合架构原理的前提下,理解和评估以网络为基础的应用软件的架构设计,得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。"如果一个架构符合REST的约束条件和原则,我们就称它为RESTful架构,REST其实并没有创造新的技术、组件或服务,在我的理解中,它更应该是一种理念、一种思想,利用Web的现有特征和能力,更好地诠释和体现现有Web标准中的一些准则和约束。

看完这段理论性的介绍可能并不会使你对于RESTful有任何的想法,甚至只是一扫而过,那就通过实际的案例来讲解吧。

ssm项目中有文章管理这个模块,文章列表页面删除文章请求的服务端API地址为: http://ssm-demo.hanshuai.xin/article/delete.do, 这个URL并不是RESTful风格的API,稍加修改,URL变成: http://ssm-demo.hanshuai.xin/article/delete/12, 这样是不是就是RESTful风格了?

首先,这两个URL都不是RESTful API,因为这两个URL中都有delete的动作指示,RESTful API是面向资源的架构,因此其URL就应该是一个资源,而且不应该包含任何动作,对于资源的具体操作类型应该由HTTP动词表示,而不应该是动词存在于URL中,delete是一个动词,因此不符合该特点,对于文章删除功能其对应的RESTful API应该是: [DELETE] http://ssm-demo.hanshuai.xin/articles/12

常见的RESTful误区

再讲一下一开始接触RESTful时大家都可能存在的误区:

  • 一些伪静态的URL,如http://ssm-demo.hanshuai.xin/contents/12,我们可以通过浏览器访问该URL而获取信息,但是这并不代表着它就是RESTful API。
  • URL里含有queryString就不是RESTful Api,如http://ssm-demo.hanshuai.xin/articles/?page=1&rows=10,RESTful API可以包含queryString。
  • HTTP + JSON = RESTful API,HTTP和JSON不等于RESTful,RESTful特性更加丰富,不能将RESTful简单的等同于HTTP和JSON。

良好RESTful API的设计原则

关于RESTful API设计的具体实现可以到我的GitHub中查看,以下为整理的一些设计原则:

基本原则一:URI

  • 应该将API部署在专用域名之下:ssm-demo.hanshuai.xin;
  • URL中尽量不用大写;
  • URI中不应该出现动词,动词应该使用HTTP方法表示但是如果无法表示,也可使用动词,例如:search没有对应的HTTP方法,可以在路径中使用search,更加直观;
  • URI中的名词表示资源集合,使用复数形式;
  • URI可以包含queryString,避免层级过深。

基本原则二:HTTP动词

对于资源的具体操作类型,由HTTP动词表示,常用的HTTP动词有下面五个:

  • GET:从服务器取出资源(一项或多项)。
  • POST:在服务器新建一个资源。
  • PUT:在服务器更新资源(客户端提供改变后的完整资源)。
  • PATCH:在服务器更新资源(客户端提供改变的属性)。
  • DELETE:从服务器删除资源。

还有两个不常用的HTTP动词:

  • HEAD:获取资源的元数据。
  • OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。

例子:

文章管理模块:

1. [POST]   http://ssm-demo.hanshuai.xin/articles   // 新增
2. [GET]    http://ssm-demo.hanshuai.xin/articles?page=1&rows=10 // 列表查询
3. [PUT]    http://ssm-demo.hanshuai.xin/articles/12 // 修改
4. [DELETE] http://ssm-demo.hanshuai.xin/articles/12 // 删除

基本原则三:状态码(Status Codes)

处理请求后,服务端需向客户端返回的状态码和提示信息。

常见状态码(状态码可自行设计,只需开发者约定好规范即可)

  • 200:SUCCESS,请求成功;
  • 401:Unauthorized,无权限;
  • 403:Forbidden,禁止访问;
  • 410:Gone,无此资源;
  • 500:INTERNAL SERVER ERROR,服务器发生错误。 ...

基本原则四:错误处理

如果服务器发生错误或者资源不可达,应该向用户返回出错信息。

基本原则五:服务端数据返回

后端的返回结果最好使用JSON格式。

基本原则六:版本控制

  • 规范的API应该包含版本信息,在RESTful API中,最简单的包含版本的方法是将版本信息放到url中,如:
[GET]    http://ssm-demo.hanshuai.xin/v1/articles?page=1&rows=10 
[PUT]    http://ssm-demo.hanshuai.xin/v1/articles/12 
  • 另一种做法是,使用HTTP header中的accept来传递版本信息。

ssm项目较为简单,因此暂时没有加入版本信息。

以下为参考内容,借鉴了一位博主关于安全原则的整理:

安全原则一:Authentication和Permission

Authentication指用户认证,Permission指权限机制,这两点是使RESTful API强大、灵活和安全的基本保障。

常用的认证机制是Basic Auth和OAuth,RESTful API开发中,除非API非常简单,且没有潜在的安全性问题,否则,认证机制是必须实现的,并应用到API中去。Basic Auth非常简单,很多框架都集成了Basic Auth的实现,自己写一个也能很快搞定,OAuth目前已经成为企业级服务的标配,其相关的开源实现方案非常丰富(更多)。

安全原则二:CORS

CORS即Cross-origin resource sharing,在RESTful API开发中,主要是为js服务的,解决javascript调用RESTful API时的跨域问题。

由于固有的安全机制,js的跨域请求时是无法被服务器成功响应的。现在前后端分离日益成为web开发主流方式的大趋势下,后台逐渐趋向指提供API服务,为各客户端提供数据及相关操作,而网站的开发全部交给前端搞定,网站和API服务很少部署在同一台服务器上并使用相同的端口,js的跨域请求时普遍存在的,开发RESTful API时,通常都要考虑到CORS功能的实现,以便js能正常使用API。

目前各主流web开发语言都有很多优秀的实现CORS的开源库,我们在开发RESTful API时,要注意CORS功能的实现,直接拿现有的轮子来用即可。

安全原则三:SSL

http改为https,增强安全验证。

总结

以上做了一些简单的总结,可能并不是十分的准确,如有错误,希望能够指出我会及时修改,谢谢了。

首发于我的个人博客,新的项目演示地址:perfect-ssm

如果有问题或者有一些好的创意,欢迎给我留言,也感谢向我指出项目中存在问题的朋友,具体的功能实现及代码逻辑将在之后的文章中介绍。

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏微信公众号:Java团长

使用Java API的5个技巧

本文介绍了一些关于Java API安全和性能方面的简单易用的技巧,其中包括保证API Key安全和开发Web Service方面中在框架方面选择的一些建议。

9910
来自专栏恰童鞋骚年

.NET Core微服务之基于Jenkins+Docker实现持续部署(Part 1)

  互联网软件的开发和发布,已经形成了一套标准流程,最重要的组成部分就是持续集成(Continuous integration,简称 CI) => 持续集成指的...

10340
来自专栏极客猴

Django 学习笔记之环境搭建

古人云:功遇善其事,必先利其器。在正式学习 Django Web 框架之前,我们要把准备工作做好。准备工作主要是搭建开发环境,具体工作是安装 Python、创建...

9220
来自专栏Java架构

Facebook顶级架构师教你怎么使用Java来搭建微服务快速预览介绍$java -jar myservice.jarSelf-containedSpring BootWildfly SwarmIn-

27590
来自专栏史上最简单的Spring Cloud教程

我是如何根据豆瓣api来理解Restful API设计的

1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思。它是在Roy Fielding博士论文首次...

29450
来自专栏格子的个人博客

JMeter安装配置和分布式

前段时间公司的新项目上线了一段时间之后,随着运营规模的变大,老大要求对系统进行一个摸底,那么肯定有人要为这个伟大的工作献身了,是的,那个人就是我。谁让我是就是打...

11820
来自专栏Java架构

Facebook顶级架构师教你怎么使用Java来搭建微服务

微服务背后的大理念是将大型、复杂且历时长久的应用在架构上设计为内聚的服务,这些服务能够随着时间的流逝而演化。本文主要介绍了利用 Java 生态系统构建微服务的多...

403100
来自专栏ImportSource

CQRS距你有多远?

前面两集(微服务业务开发三个难题-拆分、事务、查询(上),微服务业务开发三个难题-拆分、事务、查询(下))翻译了Chris的大作。为了保证原意不跑偏同时通俗易懂...

49080
来自专栏圆方圆学院精选

【戴嘉乐】(进阶)基于IPFS和Ngrok构建自维护资源网关

上篇文章《【应用】(入门)基于IPFS和Ngrok构建自维护资源网关》,我们通过Ngrok为IPFS节点配置HTTP Tunnels,充分利用了其NAT穿越的特...

12910
来自专栏Java学习123

ESB企业服务总线

615140

扫码关注云+社区

领取腾讯云代金券