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.13blog.site/articles/12

常见的RESTful误区

再讲一下一开始接触RESTful时你们均可能存在的误区：

• 一些伪静态的URL，如http://ssm-demo.13blog.site/contents/12,咱们能够经过浏览器访问该URL而获取信息，可是这并不表明着它就是RESTful API。
• URL里含有queryString就不是RESTful Api，如http://ssm-demo.13blog.site/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.13blog.site;
• 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.13blog.site/articles   // 新增
2. [GET]    http://ssm-demo.13blog.site/articles?page=1&rows=10 // 列表查询
3. [PUT]    http://ssm-demo.13blog.site/articles/12 // 修改
4. [DELETE] http://ssm-demo.13blog.site/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.13blog.site/v1/articles?page=1&rows=10 
[PUT]    http://ssm-demo.13blog.site/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，加强安全验证。

总结

以上作了一些简单的总结，可能并非十分的准确，若有错误，但愿可以指出我会及时修改，谢谢了。

推荐一下本身的达人课，感兴趣的朋友能够看一下：SSM搭建精美实用的管理系统

首发于个人我的博客，新的项目演示地址：perfect-ssm。

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

若是你想继续了解该项目能够查看整个系列文章Spring+SpringMVC+MyBatis+easyUI整合系列文章,也能够到个人GitHub仓库或者开源中国代码仓库中查看源码及项目文档。