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

/ 整合进阶篇ssm整合 / 4 条评论 / 1890浏览

写在前面的话

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

github 也看到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时大家都可能存在的误区:

良好RESTful API的设计原则

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

基本原则一:URI

基本原则二:HTTP动词

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

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

例子:

文章管理模块:

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)

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

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

基本原则四:错误处理

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

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

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

基本原则六:版本控制

[GET]    http://ssm-demo.hanshuai.xin/v1/articles?page=1&rows=10 
[PUT]    http://ssm-demo.hanshuai.xin/v1/articles/12 

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,增强安全验证。

总结

i'm back

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

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

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

如果你想继续了解该项目可以查看整个系列文章Spring+SpringMVC+MyBatis+easyUI整合系列文章,也可以到我的GitHub仓库或者开源中国代码仓库中查看源码及项目文档。

  1. 来看看看看看看~

  2. 运河店法规和法国

  3. 哎哟哟~~~~~

  4. 了空军建军节