java EE技术体系——CLF平台API开发注意事项（4）——API生命周期治理简单说明

文档说明

截止日期：20170905，作者：何红霞，联系方式：QQ1028335395、邮箱：hehongxia626@163.com

综述

有幸加入到javaEE技术体系的研究与开发，也得益于大家的帮助和组织的支持，取得了一些有突破性的成果。我个人主要研究的内容是：API生命周期治理。整篇文档，均围绕着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:\jaxrs\jsersey2）

备注：更多参数说明：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文档

https://docs.docker.com/

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

备注：其他看过哪些文档资料，记不太清楚了！但如果博客里面有粘贴链接，那一定是很必要的链接，都看看吧！