文档说明
截止日期：20170905，作者：何红霞，联系方式：QQ1028335395、邮箱：hehongxia626@163.com
综述
有幸加入到javaEE技术体系的研究与开发，也得益于大家的帮助和组织的支持，取得了一些有突破性的成果。我个人主要研究的内容是：API生命周期治理。整篇文档，均围绕着API的整个生命周期管理，进行说明。侧重点为：设计、开发、维护、安全策略
为什么要研究API生命周期
API经济模式
公司开发模式的变革
产品的5.1版本智能迭代，采用了前端工程化，前后分离的开发模式。在这个过程中，由于我们初次采用此模式，我们遇到了一些问题，比如：
1， 前后端工程师沟通效率低、API再度实施
2， 前后端联调效率低，开发人员抱怨
3， API散落，安全机制还待健全……
因此，我们需要学习先进的思想理念和技术，需要找到一些解决方案去提高产品的质量和开发效率。API生命周期的治理，贯穿整个开发周期，它的意义十分重大，也是在未来，公司能够拥抱API经济，建立企业生态圈一个很关键的内容。
研究概况
1， 整个API的生命周期，都可以通过工具有效管理。在设计阶段，我们遵从OpenAPIspecification ，创建业界规范的API说明；在实施阶段，javaEE技术体系，则融合了Jeddict和swaggercodegen两大工具的优点，进行快速迭代开发；在监控、版本维护、安全策略，我们除了对于API本身做基于javaEE Security规范的OAuth2.0协议实现的安全控制外，还借助API网关，实现更加严格的API访问控制！
备注：云图平台正在践行此套模式
详情说明
备注：以云图平台为例
计划：
1， 技术：采用javaEE全套技术进行开发
2， 模式：前后端分离，API-First
设计：
在前后端分离的情况下，或者是API需要对外提供，对于API的规范性有很高的要求，这关系着API是否能正确、准确的被使用。我们采用swagger2 进行API的设置（可替换产品：blueprint。选swagger的最初原因：上手快，成本低，团队协作）。在这个过程中，需要说明的有以下几点：
Swagger宏观概述
swagger editor的应用
http://editor.swagger.io/?_ga=2.232826710.994065908.1504343949-394633204.1503387325#/
swagger codegen的应用
https://github.com/swagger-api/swagger-codegen/wiki/Server-stub-generator-HOWTO
云图平台JAX-RS（Jersey2.0）示例：使用cmd，以管理员身份打开命令行窗口，执行：java -jarJ:swagger-codegen-cli-2.2.1.jar generate -i "D: Basic.json" -ljaxrs -o jaxrs/jersey2
说明：-i 指定swagger API位置，这里为本地路径，也可为服务路径
-l 指定代码生成模板，此处为jaxrs
-o 代码生成的存放文件夹（以jar包所在路径为基本路径，此处的代码会保存在：J:jaxrsjsersey2）
备注：更多参数说明：java -jarswagger-codegen-cli-2.2.1.jar help generate
swagger服务器搭建
参考文档
文档
Swagger应用文档：https://swagger.io/docs/swagger-tools/#swagger-ui-documentation-29
关键示例
1， 在代码开发结束后，整合swagger生成文档：swagger整合SpringMVC （应用于ITOO平台的技术体系）
第一步：添加pom依赖：
<!--swagger-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>第二步：配置对于静态文件的访问控制
<bean class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration"id="swagger2Config"/> <mvc:resourceslocation="classpath:/META-INF/resources/"mapping="swagger-ui.html"/> <mvc:resourceslocation="classpath:/META-INF/resources/webjars/"mapping="/webjars/**"/>
搭建mock服务的三种形式
为什么需要mockservice
当API规范制定后，一个mockservice可以模拟真实服务让用户使用，比如：在前后端分离后，前端可直接使用mockservice进行开发。可有效避免前端编辑web-api，以及后期的URL访问路径和方法更改！ 并且，在使用的过程中，也尽可能早的发现不足，及时更改！
如何构建
第一种：利用swaggereditor
在使用swagger editor时，给参数、返回值提供一个默认值，并开启其mock服务。客户端使用时，可以直接调用发布的swagger服务。 待后端开发结束，以真实的后端API服务替换swaggermock服务！
第二种：利用swaggercodegen
在API编辑完毕后，使用swagger codegen生成一个可运行的真实服务供客户端调用
备注：相对第一种，可模拟真实服务运行中可能遭遇的各种问题：如500、401、404、200等；而第一种，总会默认返回成功请求的数据
第三种：利用API网关
将swagger设计好的API直接导入网关，客户端所有的API请求，统一由网关代理
参考建议
大型微服务架构最优：第三种，原因：整合细粒度的服务、对后期的服务部署无限制……
小型项目最优：第一种或第二种，原因：需要部署的服务并不会有太多，通常情况下，替换掉原有的mock服务工作量很小
实施
云图平台开发环境：IDE：NetBeans8.2；JDK：java 8；Maven：3.5；Mysql：5.6；server：Jbosseap 7
辅助工具：Jeddict：4.4.1；swagger codegen：2.2.1
开发模式
开发模式一共有三种（API-First、Design-First、Code-First），确切说来只有两种（Design-First、Code-First），在目前的云图平台，结合到前后端分离，我们选用的是Design-First。其基本异同为（API-First是一种理念，它的具体实现为Design-First）：
关于开发模式的建议
code-first
通过集成swagger和Spring，发布API文档（3分钟）
场景：
1，API可快速构建、更改少（或无更改、可快速更改）
2，内部应用
3，单表服务
可选择方案：
JavaEE: 使用类似于Jeddict工具，准确无误快速生成（5分钟）
Spring：Spring-roo (用命令行)
desing-first
将业务计划转换为人机可读API文档，快速构建基本框架代码
场景：
1，相对复杂的业务计划
2，对外服务（比如：前后端分离时，也算是一种对外服务）
3，相对无法快速交付
可选择方案：
1， 前后端负责人，协调API接口——swagger协作开发API
2， mockservice Test——前端确定当前版本API高可用——swagger测试
3， 使用swaggercodegen或者集成spring，生成后端controller层框架代码、VM，前端Angular部分代码
4， 前后分别API文档实施
5， 开发模式图形示例
快速开发工具
a. Jeddict （java EE）
b. Spring-roo（类似于Jeddict，使用命令行）
c. 快速搭建Spring框架工具：Spring专用IDE：STS（Spring-tool-suite），工程可视化配置：https://start.spring.io/
云图平台实施说明
1， 通过swaggercodegen生成API接口代码 +Jeddict工具，生成整套服务代码
2， 用swagger生成的API代码，替换掉Jeddict所生成代码中的rest层（即对外提供的API接口）
说明：为了紧密结合Jeddict，使用swagger生成的代码规范为：JAX-RS（Jersey2）
附：JAX-RS规范相关实现（仅供参考）：Difference betweenJAX-RS, Restlet, Jersey, RESTEasy, and Apache CXF
Jeddict应用手册
1， 插件安装
https://jeddict.github.io/page.html?l=p/installation
2， 插件应用
https://jeddict.github.io/page.html?l=tutorial/QuickStart
3， 常见问题
a. 跨域 http://blog.csdn.net/hhx0626/article/details/73699741
b. 安全 http://blog.csdn.net/hhx0626/article/details/77832791
c. Angular4 打包 http://blog.csdn.net/hhx0626/article/details/74903927
d. 测试 http://blog.csdn.net/hhx0626/article/details/77720283
备注：Jeddict的作者是非常友好耐心的人，在使用过程中，遇到问题，请及时到Twitter、Jeddict网站提问 1，Twitter: https://twitter.com/ImJeddict
2， Github:https://jeddict.github.io/
3，YouToBe:https://www.youtube.com/user/JPAModeler
监控、维护
这一块内容，主要是借助了APIGateway工具，所以，这里主要讲APIGateway
为什么需要网关
Pattern:API Gateway / Backend for Front-End 这是ChrisRichardson的一些说法
附ChrisRichardson简介：ChrisRichardson，是世界著名的软件大师，经典技术著作《POJOSIN ACTION》一书的作者，也是cloudfoundry.com 最初的创始人，他的研究领域包括Spring、Scala、微服务架构设计、NoSQL数据库、分布式数据管理、事件驱动的应用编程等。ChrisRichardson 与Martin Fowler、SamNewman、AdrianCockcroft 等并称为世界十大软件架构师。Chris与家人居住在美国加州奥克兰市的海滨小镇，他定期为企业提供微服务设计培训和实战项目的架构咨询服务。
搞笑一下：我为什么为云图平台搭了网关服务
1， 参加了OracleCode大会和Springsummit大会，多次提到了APIGateway， 牛逼的人在说，我就来试试
2， 闲得慌，反正闲着也是闲着，搭个网关服务玩儿一下
3， 扛把子说上头说要为咱们的服务做安全控制，懒，通过网关做，我也不想做负载，也不想做服务发现，也不想天天盯着服务器看性能问题，所以，放纵我的懒，做了个网关服务
4， 等公司进一步发展，对外提供API时，网关服务必不可少。我是公司的一块砖
为什么选择了Tyk
首先，我对比的服务有：SpringZuul、Kong、Tyk、阿里云、Oracle、Amazon、自己构建
由于是刚尝试，所以选取的原则有：开源、免费、简单。 再由于我主要做java EE这边的工作，所以Spring Zuul就没考虑（主要原因：需要改代码，在代码里面配置，而且功能相对简单）。 而自己构建企业网关，结合到人力、财力、技术支撑的考虑，暂时不予以选择。
所以，最终剩下的，就是Kong、Tyk。 当然，这两种，我都将服务器搭建好了，但最终选择了Tyk。
1， Kong只提供基本的代理功能，其他的监控、限流、日志等，都需要自己集成。而Tyk，是一个已经集成好的产品，对于公司目前的需求来说，足够了！
2， 一旦公司规模扩大，需要扩展，Tyk会有专门的团队协助升级！
3， Tyk的论坛、服务团队很活跃
4， 喜欢Tyk的作者Martin
为什么选择了Tyk私有云服务
Tyk一共支持三种服务：Cloud、Hybrid、On-Premises。目前使用的是On-Premises，原因：
1，免费账号，每天提供50K的API访问；2，安全；3，我爱折腾（想知道那些服务都是怎么搭建运行的，为构建自己的企业级网关做准备）
Tyk搭建
目前因为公司的docker容器技术比较成熟，所以，Tyk用的是Docker安装，安装文档：
https://tyk.io/docs/get-started/with-tyk-on-premise/installation/docker/
要点：
1，前提条件：安装docker（为了后面更简单，建议v1.9.0或以上），安装docker Compose
2，所需要的镜像：redis、mongo（做数据存储和缓存）、tykio/tyk-gateway、tykio/tyk-dashboard、tykio/tyk-pump-docker-pub
3，所需要的文件：tyk_quickstart：gitclone https://github.com/lonelycode/tyk_quickstart.git
备注：在运行Gateway容器时，需要额外配置一个环境变量，不然会导致RPC调用有误：所以，将文档中的命令行，换为：dockerrun -p 8080:8080-eTYK_GW_COPROCESSOPTIONS_ENABLECOPROCESS=false --name tyk_gateway --linktyk_redis:redis tykio/tyk-gateway
注意事项：DockerQuickstart 在这篇文档中，每次都要执行./setup.sh文件，而在这里面关于用户名和密码等，都是随机生成，这样在登录的时候，不方便，可以将其随机函数改为自定义值！
License获取地址：Tyk On-Premises –FREE Edition
Tyk应用
提示：只做基础应用说明
1，登录DashBoard—systemManagement—Addnew API or Import API
备注：在云图平台中，因为采用设计优先的开发模式，所以，点击import API，从swagger服务器一键导入即可。
2，API配置：点击上图中需要进一步配置的API 后面的Edit按钮，进入到详细配置页面
文档地址：API Management
CoreSettings
备注：这里划分的一级、二级等级，是根据当前需求（初次尝试网关服务）所设定。以后公司规模扩大，API应用于商业往来，限流、安全等级将会上升！
一级关注配置：listenpath（监听路径，跟restful的requestmapping路径差不多）、targetURL（被代理的服务）
二级关注配置：负载、服务发现（暂未进一步研究）、安全
负载：只需要将部署有API服务的服务添加到列表即可，Tyk会帮我们做高效的负载
安全：对于目前公司成员来说，选择OAuth2.0和JWT都是相对较好的！
三级关注配置：限流
Versions
版本控制策略基本上有：
Tyk里面有三种，能够满足公司API版本控制需求
版本控制需要额外考虑的现象：
1，当前版本不可用时，如何处理其调用？？？——可默认指向下一个最旧的可用版本
2，如何处理没有指定版本的请求？？？——可默认指向最旧或者最新的可用版本
其他配置
缓存、服务发现、API详细配置等，不一一说明了，请参考文档：https://tyk.io/docs/tyk-dashboard-v1-0/tyk-dashboard-configuration/
额外说明
1， 在真正使用（发布API）的时候，需要配置API暴露策略，参考其他配置文档
2， Tyk论坛地址：https://community.tyk.io/ 备注：Martin特别好，不管怎么呆萌的问题，他都能给你一步一步说，所以，遇到问题，实在解决不了，去论坛或者Twitter问。 如果你有幸赶上公司愿意付费使用，那你将会接触到Tyk另一支优秀的团队，特别棒！
资料整理
1，swagger官网API实例文件
URL：http://editor.swagger.io/?_ga=2.232826710.994065908.1504343949-394633204.1503387325#/
2，swaggercodegen生成的可运行代码
https://github.com/swagger-api/swagger-codegen/tree/master/samples/server/petstore
3，Kong搭建过程
https://getkong.org/install/docker/
4，docker文档
5，JAX-RS规范
https://docs.oracle.com/cd/E19226-01/820-7627/giqsx/index.html
6，Jeddict源码
https://github.com/jeddict/jeddict
https://github.com/jeddict/jCode
备注：其他看过哪些文档资料，记不太清楚了！但如果博客里面有粘贴链接，那一定是很必要的链接，都看看吧！