我们已经习惯性的在创建各种软件的时候，习惯性第一时间考虑分布式构想（比如那些实现CORBA、Web服务协议栈和J2EE的平台）。在这篇文章里，我将以XCD项目现状的框架结构分享一下我们把支撑Web运行的协议和文档格式视为一种应用平台，一种可通过轻量级中间件访问的平台。虽然我们没有将Rest独立出来，但是我们提供了可以独立部署的支持。

引言

      我们知道，集成领域是不断变化的。Web的影响以及敏捷实践的潮流正在挑战我们的关于“良好的集成由什么构成”的观念。集成（integration）并不是一种夹在系统之间的专业活动；与此相反，现在，集成是成功方案里的不可缺少的一部分。

       然而，仍有许多人误解并低估Web在企业计算中的作用。即便是那些精通Web的人士，也常常要花费很大力气才能懂得，Web不是关于支持XML over HTTP的中间件方案，也不是一种简易的RPC机制。这是相当遗憾的，因为Web不是仅能提供简单的点对点连接，它还有更大的用处；它实际上是一个健壮的集成平台。

什么是HTTP REST

REST是一套用来创建Web Service的方法。

REST式的Web Service的主旨是让事情尽量的简单化。

REST式的Web Service使用HTTP里的方法：GET， POST， DELETE， PUT。你不需要使用URL或请求的内容来指定这个方法。

REST式的Web Service使用HTTP状态码作为返回值。

REST式的Web Service调用产生的HTTP请求内容只是用于服务数据不是用来指明调用方法，目标对象或返回值的。

使用REST方法来开发Web Service的关键点是利用HTTP协议的简单性，而不是去扩展这个协议。你的Web Service调用最终应该是非常的简单而且非常的易于理解。

举例来说，以这道题的url来讲：

http://www.xcd.com，表示全网可见，在http://www.xcd.com这个包里

query就是函数名(当然，我们也可以追加模块)

123456789是路径参数，表示订单编号

当我回答你使用GET获得订单信息，我输入的URL中就输入订单编号，然后返回DATA给你。

当不同的平台通过HTTP 请求平台，服务器收到的http响应就是GET重载下的返回值

当然了，REST的运用是非常灵活的，以上只是对标准模式下的一种描述。

XCD项目如何设计restful的

在说XCD项目如何使用restful的时候，在这里要感谢朱曦等公司提供帮助的同事。

XCD项目的restful使用的是Spring 的restful，对于为什么使用spring restful是因为spring restful上手快和开发简单。并且因为整体开发框架使用的都是Spring。所以集成业很方便。

对于XCD项目对于restful设计原则有二个，并且二种风格完全不同。

一种是以我为主的订单模块和虚拟库存这块的，（PS：如果被马波知道一定又要被他说不听他的了）

另外一种是以我负责的模块以为的其他模块。

先说我的设计原则，Controller 入口一个，URL多个，将Controller当前路由，通过动态URL，并且通过适配器模式进行使得原本由于接口不兼容而不能一起工作的那些类可以在一起工作。

举一个🌰（例子）

订单查询：订单查询分为买家订单查询，卖家订单查询，买手销售订单查询，买手囤货订单查询。

买家订单查询：买家通过自己的ID和Code获得自己所有下过的订单信息。

卖家订单查询：卖家通过自己的ID和Code获得自己所有的销售过的订单信息

买手销售订单查询：买手通过自己的ID和Code获得自己销售过的订单信息

买手囤货订单：买手通过自己的ID和Code获得自己囤过哪些货物

PS：这里面我们先不考虑分页等情况，但是考虑不同的订单类型（订单类型分：标准分销订单，标准买手囤货订单，第三方标准订单，第三方买手囤货订单，标准买手销售订单，第三方买手销售订单）

对内我的功能编号就一个：ISO151416。

按照开发原则我们的Controller也就是一个（ISO151416Controller）。因为我们设计的表在一套表中，所以对于业务而言，我只是关联的表可能不同并且返回的信息也不同，但是主表还是相同的。那么我们对于开发者而言，说简单点就是SQL不同。参数不同。

对外我的restful时4个。

分别是买家订单查询，卖家订单查询，买手销售订单查询，买手囤货订单。这样拆分对于调用者是简单清晰的。因为一个对应一个。

其实这种方式是在第一版本上面进行延伸的，因为当初设计的时候其实对外URL或者叫接口只有一个，然后不同的页面调用通过传入不同的参数。然后进行查询操作。但是这种方式会让调用者产生疑问。无法分辨。

在这里说明一点因为我们的所有的参数格式都是JSON格式，所以对内我们的参数是一套，但是提供给调用者是四套参数。每一种查询是不同的。如果我们在这边为了数据或者数据安全性参数验证。可以通过不同的验证类进行处理。

还一种方式，我们的设计原则是，将每一个功能的颗粒度最小话，然后将每一个功能设计一套Controller，Service，SQL出来。

举一个🌰（例子）

订单查询：订单查询分为买家订单查询，卖家订单查询，买手销售订单查询，买手囤货订单查询。

买家订单查询：买家通过自己的ID和Code获得自己所有下过的订单信息。

卖家订单查询：卖家通过自己的ID和Code获得自己所有的销售过的订单信息

买手销售订单查询：买手通过自己的ID和Code获得自己销售过的订单信息

买手囤货订单：买手通过自己的ID和Code获得自己囤过哪些货物

PS：这里面我们先不考虑分页等情况，但是考虑不同的订单类型（订单类型分：标准分销订单，标准买手囤货订单，第三方标准订单，第三方买手囤货订单，标准买手销售订单，第三方买手销售订单）

对内我们有买家标准分销订单，买家第三方订单，卖家第三方销售订单，卖家标准分销订单，买手标准囤货订单，买手第三方囤货订单，买手标准销售订单，买手第三方销售订单查询接口。

每一个接口的参数不同，然后处理一套Controller，Service，SQL。

这样的好处是将每一接口最小化，修改影响范围最小化。

对于这二种方式没有绝对的好或者坏，不同的设计人员对应设计的理解和认知不同而已。

关于Restful文档的编写

在写这个的时候，我可能又要被马波同学说了，因为我很多的时候不听马波的话，按照自己的想法做事，也就是典型的不听话的孩子（我永远18岁），其实这个是我的问题，因为当初设计这个Restful文档的时候我没有参与进去，一开始我就没有接接口开发这块。所以没怎么在意。哈哈哈。现在有说别人的文档不怎么好，是不是很贱啊。

我认为的接口文档应该包含以下几点。

1.请求URL

2.请求方式（POST，GET等）

3.参数类型（application／json或者application／xml）

4.功能描述

5.输入参数（包含参数说明，格式，实例）

6.输出参数（包含参数说明，格式，实例，异常情况和正常情况）

7.实例：请求实例返回实例。如果有时间应该也包含异常情况

其实微信API接口可以作为我们参考的。

为什么突然想写这个呢，因为我们需要积累和学习。

在这里分享一个《如何获取（GET）一杯咖啡——星巴克REST案例分析》

学无止境，每天记录一点。