1调研背景

目前存在以下情况:

1）一般开发人员更新接口后，没有同时更新rap，rap上的接口定义普遍存在跟代码不一致的情况。

2）后端开发人员查看别人接口，很难很快地知道接口的作用，以及接口入参和返回结果中每个字段的含义。

3）rap上的mock数据功能不是特别好用。

2 调研结果

为了解决以上问题，调研了主流的三个工具，swagger2、spring rest docs、apidoc

基于以下原则对软件做了筛选：

1）不允许使用注解（annotation），对代码侵入性比较强， 排除swagger2

2）不运行java程序就能生成文档，排除spring rest docs

3）可以给前端提供mock数据

所以采用了apidoc

参考文章：

 用spring Restdocs创建API文档   http://blog.csdn.net/forezp/article/details/71023510

 springboot集成swagger2，构建优雅的 Restful API http://blog.csdn.net/forezp/article/details/71023536

 springboot集成apidoc     http://blog.csdn.net/forezp/article/details/71023579

3 apidoc实施方案：

1） 测试环境部署统一的api文档服务器，目录按项目划分,访问路径: http://docs. ***.com/api/项目名/

2） 开发人员按照apidoc的规则对接口写详细的注释

3） 提交代码后，Jenkins执行gradle apidocs命令生成html文件，然后上传到服务器对应的目录中

4 项目参考案例

项目：git@git.***.com:wy-serverside/insurance-2b-group.git

文档：http://docs. ***.cn/api/insurance-2b-group/

Jenkins任务：test_insurance_2b_group

apidoc便捷生成工具：http://tool.suiyiwen.com/apidoc/

5 后端开发本地环境配置

5.1 Apidoc安装

首先需安装nodejs，然后安装apidoc(执行npm install apidoc –g)

5.2 项目配置

5.2.1 gradle项目的配置文件build.gradle增加配置

def isWindows() {
   return org.gradle.internal.os.OperatingSystem.current().isWindows()
}
String apidocCmd = isWindows() ? 'apidoc.cmd' : 'apidoc'
task apidocs(type: Exec, description: '执行生成apidoc文档操作') {
   workingDir './'
   def docCommand = [apidocCmd, '-o', './build/apidocs']
   commandLine docCommand
}

5.2.2项目的根目录增加文件apidoc.json

{
 "name": "springboot-sample接口文档",
 "version": "1.0.0",
 "description": "",
 "title": "springboot-sample",
 "url" : "https://demo.test.com"
}

5.2.3 Controller根据apidoc的规范增加注释（ http://apidocjs.com/）

/**
* @apiVersion 1.0.0
* @api {GET} /group/front/getOutlinePaySuccessInfo 获取支付成功数据
* @apiGroup TransferAccount
* @apiName getOutlinePaySuccessInfo
* @apiParam (请求参数) {String} orderID 订单号
* @apiParam (请求参数) {String} partnerCode 渠道code
* @apiParam (请求参数) {String} sign 签名
* @apiParamExample 请求参数示例
* ?orderID=G0000168752925895356416&partnerCode=wyxx&sign=064d8cc51ed0957839e62f6684a4fe5c
* @apiSuccess (响应参数) {String} accountName 收款人
* @apiSuccess (响应参数) {Number} insuredNum 被保人数量
* @apiSuccess (响应参数) {String} returnUrl 跳转地址（可能为空）
* @apiSuccess (响应参数) {Number} validStartDate 开始时间
* @apiSuccess (响应参数) {Number} validEndDate 截止时间
* @apiSuccessExample 响应示例
* {"code":200,"msg":"成功","data":{"groupName":"微易测试","insuredNum":5,"returnUrl":"http://www.baidu.com","validStartDate":1524127875000,"validEndDate":1524127875000}}
*/

5.2.4 本地执行gradle apidocs，生成文档

5.2.5  其他：idea注释模板使用

1）Settings-->editor-->Live Templates 新增模板

2）Abbreviation设置为apidoc

3）Context type设置为java:declaration

4）勾选Reformat according to stype

5）添加模板内容

6）Java文件中输入apidoc使用

/**
* @apiVersion 1.0.0
* @api {method$END$} path title
* @apiGroup name
* @apiName name
*
* @apiParam (请求参数) {type} field description
* @apiParam (请求参数) {type} field=defaultValue description
* @apiParamExample 请求参数示例
*             example
*
* @apiParam (请求体) {type} field description
* @apiParam (请求体) {type} field=defaultValue description
* @apiParamExample 请求体示例
*             example
*
* @apiSuccess (响应参数) {type} field description
* @apiSuccess (响应参数) {type} field description
* @apiSuccessExample 响应示例
*             example
*
*/

⑴强引用（StrongReference）

　　强引用是使用最普遍的引用。如果一个对象具有强引用，那垃圾回收器绝不会回收它。当内存空间不足，Java虚拟机宁愿抛出OutOfMemoryError错误，使程序异常终止，也不会靠随意回收具有强引用的对象来解决内存不足的问题.

　　使用强引用的一个例子。

　　图像缓存问题，图像缓存应该阻止我们重新载入图像，所以图像缓存保存有内存中已有的所有图像的引用，如果使用通常的强引用，强引用本身会使得图像一直存留在内存中，这样就使得程序员像上面一样，必须自己决定什么时候移除缓存中的引用，这样对象才能被垃圾回收机制回收。

⑵软引用（SoftReference）

　当你想引用一个对象，但是这个对象有自己的生命周期，你不想介入这个对象的生命周期，这时候你就是用弱引用。这个引用不会影响gc对对象的回收。

虚引用主要用来跟踪对象被垃圾回收器回收的活动。虚引用与软引用和弱引用的一个区别在于：虚引用必须和引用队列 （ReferenceQueue）联合使用。当垃圾回收器准备回收一个对象时，如果发现它还有虚引用，就会在回收对象的内存之前，把这个虚引用加入到与之 关联的引用队列中。

ReferenceQueue queue = new ReferenceQueue ();
PhantomReference pr = new PhantomReference (object, queue);

List结构的集合类：ArrayList，LinkedList，Vector，Stack

Map结构的集合类：HashMap，HashTable，LinkedHashMap

Set结构的集合类：HashSet，TreeSet，LinkedHashSet

Queue结构的集合：Queue接口

总结：

1）如果要求线程安全，使用Vector，Hashtable

2）如果不要求线程安全，使用ArrayList，LinkedList，HashMap

3)如果要求键值对，则使用HashMap，Hashtable

4）如果数据量很大，又要求线程安全考虑Vector

1．ArrayList: 元素单个，效率高，多用于查询

2．Vector:    元素单个，线程安全，多用于查询

3．LinkedList:元素单个，多用于插入和删除

4．HashMap:   元素成对，元素可为空

5．HashTable: 元素成对，线程安全，元素不可为空

ArrayList

底层是Object数组，所以ArrayList具有数组的查询速度快的优点以及增删速度慢的缺点。

而在LinkedList的底层是一种双向循环链表。在此链表上每一个数据节点都由三部分组成：前指针（指向前面的节点的位置），数据，后指针（指向后面的节点的位置）。最后一个节点的后指针指向第一个节点的前指针，形成一个循环。

双向循环链表的查询效率低但是增删效率高。

ArrayList和LinkedList在用法上没有区别，但是在功能上还是有区别的。

LinkedList

经常用在增删操作较多而查询操作很少的情况下：队列和堆栈。

队列：先进先出的数据结构。

栈：后进先出的数据结构。

注意：使用栈的时候一定不能提供方法让不是最后一个元素的元素获得出栈的机会。

Vector

（与ArrayList相似，区别是Vector是重量级的组件，使用使消耗的资源比较多。）

结论：在考虑并发的情况下用Vector（保证线程的安全）。

在不考虑并发的情况下用ArrayList（不能保证线程的安全）。