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仓库或者开源中国代码仓库中查看源码及项目文档。