文档说明
截止日期: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:\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文档
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
备注:其他看过哪些文档资料,记不太清楚了!但如果博客里面有粘贴链接,那一定是很必要的链接,都看看吧!