文档说明

截止日期: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-gatewaytykio/tyk-dashboardtykio/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

 

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

posted on 2017-09-06 08:29  何红霞  阅读(642)  评论(0编辑  收藏  举报