微服务成熟度模型

微服务是一个持续演进的过程。

微服务成熟度模型参照Restful成熟度模型。

等级0

服务系统能为自身的功能提供服务
开放度限于自身进程内存、本域内本会话

等级1

服务系统能为其他系统提供服务
开放力度为HTTP接口
代码由各自的团队维护,使用领域模型
服务使用统一的语言技术
服务使用统一的协议通信

等级2

服务系统能被其他系统整合
开放力度为网络接口、内存管道
服务自制,故障隔离高可用,独立部署并持续交付
2种以上异构系统组合
2种以上的协议通信
服务可探索其他服务,亦可被其他服务探索

等级3

服务可自治、可被协调管控
任何力度的服务都应该可以方便的开放出来
热插拔高可用,交互无障碍,依赖自包含,自动化部署
多种异构系统组合
多种通信协议支持
代码开放,并由商业公司、开源社区多方共同维护

Advertisements

OAI 3.0-RC0变化

前言

对于apiary而言未来都会产生很大的变化,拭目以待。

至于Swagger3.0有啥变化,这里来分析一下。

 

变化

 

结构上

image00-1-768x539

对应的Swagger文档OAI文档

  1. 熟知的infopathstags不变
  2. hostbasePathschemes已经合并到servers里面
  3. consumesproduces已经被移除
  4. 其他的被移动到components里面

其中3、4影响是比较大的。

 

特性上

  • 支持完整的URL Templating
  • 对于file类型的重做
  • Request bodies不支持HTTP动词未定义的情况
  • 相对网址支持
  • callback表达式返工
  • 实例文档更加清晰
  • Schema支持nullable,增加writeOnly属性
  • JSON Schema支持到draft-wright-json-schema-00版本
  • Header遵循标准参数对象,Items从结果中被移除

 

 

 

重要

注意:这里将说明一下几个比较关注的问题,至于其他的一些细节还有待发现。

 

OAI名称

Swagger对象变为OpenAPI对象,可以通过上图直观表现出来。

算是正式使用OpenAPI(OAI)这个词代替Swagger,对于文档可以称为OAI文档,当然原有的一些工具仍然沿用Swagger命名。

 

注意:以下使用Swagger代表2.0,使用OAI代表3.0

 

服务地址

OAI的Server对象将以前凌乱的多个属性组合起来,其中最大的变化是对于url变量的支持,

这里的例子很容易说明。

由于Server对象的url属性可以使用变量,则不再需要Swagger的schemes的描述是否是http,https,ws,wss协议。

 

参数

在Swagger中Operation对象中的parameters属性笼统的将request包含在内,对于multipart/*则支持的并不友好,OAI增加了requestBody属性用于解决body参数的复杂性。

对于原有的consumes、produces属性,则通过Content对象中的Media Type对象名称体现出来,随之OpenAPI对象中的全局consumes、produces属性自然也被移除。

 

安全

Security Scheme对象现在已经从basic,apiKeyoauth2变化为apiKey,http,oauth2,openIdConnect

其中http type属性取代原有的base type属性,与bearerFormat属性配合将支持JWT和自定义的授权方式。

原有Swagger Security Scheme对象的flow、authorizationUrl、tokenUrl、scopes属性重新压缩到OAI的flow属性,4种授权方式将可以共享一个Security Scheme对象。

MSON中文规范介绍

介绍

MSON 的简介在Apiary MSON

 

中文

规范没有正式化,所有中文翻译也就是做成双语的了,官方提供了一个mson-zoo例子,目前并不太全。

 

主体思想

这里是重点,MSON 与 JSON Schema 定位相同,虽然本人没有研究过 JSON Schema ,但是可以肯定是MSON属于模型规范文档。

约定:所谓规范文档,即一手文档,通过文档即可完全描述并表达清楚。很多人认为只有写到 Word 里面的才算规范文档,其实不然,对于描述数据结构、描述模型,使用 Word 文档是可以描述清除,但是与代码结合是很无力的,这时 Word 就属于模型规范文档的衍生文档了。

正是由于模型规范文档针对的是机器而非人类,自然阅读模型规范文档是非常困难的,MSON 在 Markdown 的基础上进行模型描述,本身 Markdown 就已足够贴近人类阅读,自然 MSON 也是很好阅读的。

阅读书写方便带来的就是规范灵活,灵活的同时带来多义性也是有的。

比如:

  • 结构类型可以定义成匿名的成员
  • 类型描述块同时包含 Markdown 列表
  • 类型属性可使用类型分离器代替
  • 类型继承
  • 大量使用简写

 

常见问题

  1. 命名类型与成员类型的类型片段写法不一致,前者使用 ## 二级标题头,后者使用 - 列表,尽量不要在成员类型下再嵌套成员类型。
  2. 对象的类型(类型规范)和对象的属性(类型属性),都放在类型定义的 ( ) 括号中。类型只会有一个(嵌套类型、泛型实现类型仍然是一个类型),属性有n个

    -EnumType: hello (enum[string], default)

    一个字符串枚举类型、默认值为hello的、可以为null、命名为EnumType的成员类型,并且是这是一个无类型片段简写。

  3. 值类型定义(值定义)包含类型定义,斌且仅仅在成员类型中使用

    #EnumType: hello (enum[string], default)

    上面的的错误写法,只因为将成员类型- 换成了命名类型 # 。

  4. 类型属性在命名类型与成员类型中的限制不一样,命名类型不能使用sample default 类型属性

    #EnumType: hello (enum[string], sample)
    #EnumType: hello (enum[string], default)

    上面的写法是错误的。而对于括号的中嵌套类型的简写,也可以使用分离器。

    #EnumType (enum)
    ## Members
    – (string)
    ## Sample
    – hello

    能否写成下面的方式有待确定

    #EnumType (enum)
    – hello (string, sample)

    不过,对于嵌套泛型,就只能写到括号中了

    # One or Many (enum[*T*])

    # One or Many (*S*[*T*, string])
    – (*T*)
    – (array[*T*])

  5. object型命名类型的Sample、Default片断官方文档里面没有给出示例。能否写成下面的方式有待确定。

    #ObjectType (object)
    ## Properties
    – name (string)
    ## Sample
    – name : hello

  6. 类型规范中使用单星号*(通配符类型名)表示任意类型;双星号中间加字符*T*(泛型命名声明)表示可变类型。
  7. 官方文档中仅仅将成员片段(成员类型分组)中的分离器定义为成员类型分离器。这里我们做一个扩展约定将:Items | Members | Properties Validations Sample Default都定义为分离器。一个类型由多个类型片段组成,但是每个片段并不是对应一个分离器:片段没有分离器,片段只有一个分离器,片段有多个分离器。

    # Person (object)
    An additional
    multi-line description

    – here
    – there

    ## Sample

    ## Properties
    – `first_name`
    – `last_name`

    ## Validations

    ## Sample
    Another …

    上面mson文档例子中,依次出现了5个类型片段:描述片段(描述块),样本片段,成员片段(成员类型分组),验证片段,样本片段;4个分离器: Properties Validations Sample Sample

  8. Properties、Members、Items成员类型分离器经常被简写省略,造成整体概念上的混乱

    #ObjectType
    ObjectType have a name prop

    ##Properties
    – name

    省略Properties被简写为

    #ObjectType
    – name

 

优势

  • 书写灵活
  • 支持继承
  • 支持样本值设置
  • 支持混合与互斥

劣势

目前 MSON 没有版本,文档写的还不太详细,例子也不多,至于 MSON 的解析实现只有Snow Crash

 

 

前后分离与API Blueprint

由于API Blueprint的生态问题,并没有在实际项目中使用API Blueprint,相比Swagger使用Json Schema,API Blueprint混合Json Schema和MSON,造成不小的学习困难。

不过系统学习后,发现其优势还是挺多的。相对于Swagger通过例子快速上手,API Blueprint我个人更倾向于系统学习。

API Blueprint规范的翻译已经初步完成API Blueprint中文规范

 

 

简约不简单

对于使用Markdown描述API接口,确是是一个大胆的实践。

Markdown在开源代码使用率非常高,其功能完全应对了描述开源代码。经过简单的学习便可轻松使用。所以很受欢迎。

对于描述接口,其实很早就有专门的文档,比如Web Service的WDSL文档,由于Web Service的复杂性,其文档也继承了Web Service的复杂性。当然,谁也不会去手写WDSL文档,自然对于Web Service只有Code First这样的单一选择了。

由于简约式Web Api的流行,更多人选择像Restful这样的接口,大家都在寻找一种简单书写文档的方法去实现Design First(Document First),进而实现前后端并行实现。API Blueprint就是一个这样的方案。只要你可以看懂Markdown描述的开源代码,你就可以看懂Markdown描述的API接口。

 

 

用彼利己

如果说Restful是对Http协议的致敬,那么API Blueprint则可以说是对Markdown扩展。

Http协议在Web应用中使用率最高,完全利用率却很少;Markdown的使用广泛就如同Http协议一样。

Restful是充分利用Http协议的表现;API Blueprint则让大家看到了Markdown广泛的使用范围。

其共同点都是对已经存在的东西进行改造加强,而不是重新造一个新轮子。

 

 

高处纵览

一张图片即可了解其结构

map1

  • Metadata(元数据)+Name描述文档;
  • Data Structures(数据结构)通过Resource(资源)表现;
  • 多个Resource(资源)可以分为一个组合;
  • Resource(资源)有Attribute(属性),Attribute(属性)引用Data Structures(数据结构);
  • Data Structures(数据结构)引用Resource(资源);
  • Action(操作)就是HTTP事务;
  • HTTP事务包含Request和Response;

 

 

细微神髓

当需要却发现没有,这种遗憾可能就是放弃。API Blueprint设计还是非常的丰富,至于效果如何还需要经过时间的考验。

  • 资源,资源分组,双选择;
  • 资源,操作,请求响应,多级模型表现;
  • 模型继承,数据泛型,样本示例,应有尽有。

 

 

文章参考

[GitHub]api-blueprint

使用 API-Blueprint 编写 API 文档

API Blueprint 指导手册

对 API 文档的幻想

RESTful API设计规范和工具选型

编写易读、可测试、可运行的API文档

API Design And Documentation

使用 API BluePrint 编写 RESTful 接口文档

前后分离与API文档

对于使用HTTP协议进行前后分离的项目,必然会对于URL接口定义一个规范,而接口文档必不可少。

开源的接口文档有很多,每种文档都有自己的生态圈,生态圈之间又有第三方来做关联。

因为本人也是初步涉足这个领域,只接触过一部分,所以就只写些知道的东东,遗漏的日后有时间会慢慢补上

 

 

Swagger(OAI)生态圈

Swagger在16年重新命名为OpenAPI-Specification,并发起OAI提议,目前包括谷歌微软在内的多家公司已经加盟。

  • 规范

OAI3.0文档规范正在制定,现在能接触到的是Swagger 2.0 1.2

文档格式建立在JSON和YAML之上,官方推荐的是YAML格式

  • 工具

Swagger UI

文档查看器,用于查看OAI文档,静态网站可以集成到任意WEB服务器上

可以进行简单的测试

Swagger Editor

文档编辑器,用于编辑OAI文档,WEB在线工具

目前使用Swagger Editor编辑OAI文档显示的预览效果与Swagger UI是不同的。

Swagger Codegen

代码生成器,用于将OAI文档生成接口代码,已经集成到Swagger Editor中

生成的代码有缺失BUG需要再修改

  • 兼容

更多的兼容工具请查看官网

 

Swagger-Server

接口数据模拟器,用于将OAI文档生成为Mock Server,前端数据模拟工具

代码还有BUG,不支持非RESTful风格的接口数据模拟

 

 

API Blueprint生态圈

API Blueprint更多是来自第三方的开源支持。

  • 规范

目前规范是API Blueprint 1A

文档格式建立在MarkdownGitHub Markdown之上

  • 工具

Apiary

文档编辑器,支持API Blueprint,Swagger(测试),WEB在线工具

这个网站还提供测试团队协作的服务,总体来说比较全面

api-blueprint-sublime-plugin
language-api-blueprint
api-blueprint-preview
apiblueprint.vim
linter-api-blueprint

文档编辑器插件,专门针对API Blueprint,本地工具
api-blueprint-preview需要依赖aglio模块

  • 兼容

更多兼容请访问官网

RAML生态圈

待写

 

 

APIMETIC生态圈

待写

 

 

W3C WADL生态圈

待写

 

 

其他

Google Discovery

I/O Docs – Mashery

 

 

生态圈之桥

API Transformer

API文档转换器,支持对流行的API文档互相转换,WEB在线工具

api-spec-converter

API文档转换器,支持对流行的API文档转为OAI2.0文档,NodeJs模块

swagger2blueprint

API文档转换器,支持对OAI2.0文档转为API Blueprint文档,NodeJs模块

Postman

API接口测试工具,提供对OAI WADL RAML文档导入能力,Chrome插件

cURL

URL传输工具,综合性传输数据可进行简单测试,命令行工具

 

 

MOCK与测试

Sandbox

Mock工具,支持Apiary(API Blueprint) OAI RAML WSDL文档导入,WEB在线工具

接口自动生成,但是数据需要自己填写

imitator

Mock工具,国人写的一个MockServer,与各个API文档无关,Node模块

 

 

 

 

经验与大坑

Swagger

  • swagger模型不可继承,模型类型有限,类型格式化有限

API blueprint

`array` 或 `enum` _[值定义][]_ “可以”使用`[]`作为 _嵌套类型名列表_ ,隐含指定 _[嵌套成员类型][]_ 的 _类型规范_。

对于array[object]这样的二次嵌套是无意义的,避免这样写,虽然5.3 泛型命名类型中有出现例子。

 

 

参考文章

一起来学REST(11)——REST文档化:WSDL和WADL

swagger editor使用

前后分离与模板

有人因为我把H5+JS的说成静态网页而拍我砖。所以有必要在前后分离时说一下我个人对于静动态页面以及静动态网站的约定。

 

 

静态页面不是静态网站

对于早期的网站,我所接触到最早的网站应该是98 99年,当时的网站已经支持使用JS脚本,只不过并没有凸显多少优势。

按照一些人的理解,静态页面就是不会发生变化的页面,那么使用JS脚本的页面基本上都是动态页面,我唯一现在能找到的符合这种定义的静态页面也就是java doc了。

显然这不是我们想要的定义,对于普遍的理解,静态页面与动态页面的根本区别在于WEB服务器是否参与HTML的生成。一般讲,HTML以自身形态存储在WEB服务器上,而不是以模板方式存储在服务器上,这样的无须WEB服务器对其经行二次改造的页面,一般称之为静态页面。

 

所占角度的不同

所占的角度不同,其定义也不同。视觉上的静动,是直观的体现,但是其隐藏了许多细节,你无法准确描述静动的实现本质;

我们可以称一张图片是一个静态的资源,那么一张动画是否就是动态资源呢?

站在资源的角度,则明朗许多,静态资源和动态资源一目了然。

静动相对用户

我们可以称一个脚本是静态的,因为这个脚本里面的内容是不变的,发送到你的浏览器里这个脚本是10行,发送到我的浏览器里也是10行。同理一个页面,多个用户接收到相同的HTML相同的脚本,最终在在电脑和手机上显示出的效果不同,这个页面很难让人认同它是动态的。

一个动态页面中的数据部分是和用户相关的,每个用户拥有不同的数据,而不同的数据渲染出不同的页面效果。

接口体现资源本质

不管是否流行RESTful,对于WebAPI,URL不能脱离URI,其存在就是为了描述Web中资源。一个URL对应一个资源的时代已经过去,一个URL接口掺杂页面资源和数据资源的时代正在终结。页面与数据分离后,数据被分组、归类,通过URL接口暴露出来;页面被服务器托管,通过URL静态资源映射出来,两者仍然是资源。

 

 

前后分离模板是关键

为什么网页需要模板?其实很简单,数据多了,页面少了。

大量编写HTML用于显示数据是不明智的,数据可以分组归类,那么一类数据只需要一个相同结构的HTML页面就可以显示,重点在于如何将数据写入HTML中。好了,服务器模板诞生了。

在长期的后端占据主导地位的年代,模板逐渐在靠近后端语法,导致很多人只知道模板却不知模板的作用。比如知道ASPX却不知道与HTML的关系。

很多人用模板开发一段时间后已经发现其中的某些问题,比如,我要同时学习模板语法与HTML同时还要将两者关系对应上;对于ASPX我无法通过简单的方法在浏览器中控制某个控件;对于jade我无法直接从其他模板迁移到此模板上…

归根揭底模板只是临时解决方法被长期运用而已。唯一的改变就是将旧的模板增加一些新的功能,换个名字继续让你用而已。

 

设计文件白费功夫

国内普遍使用的Axure原型设计工具,但是设计出的demo基本上对于后面的页面编写没有什么作用,设计完了,也就不在维护了,哪怕设计改动,原型也很少有同步修改的。如果将原型设计的工作定位给产品,让产品狗放弃Axure转用H5做原型开发是不现实的,而前端基于Axure生成的H5做实现还不如从新写H5来的快。所以如果你是大公司有多余的产品人员,可以还继续使用Axure;否则今早放弃Axure直接用H5做原型肯定会提高效率很多。至于未来,Axure也会逐步靠近H5的IDE。所以放弃Axure不是坏事。

HTML任然是模板

如果你知道HTML在浏览器中会加载为DOM对象,那么你应该马上就能认同这种说法。JSP/ASP是HTML模板,HTML是DOM模板。如果是这样,把创造新HTML模板的时间去创造一个DOM模板,岂不更有竞争力。未来的WEB应用仍然会使用状态还原应对崩溃恢复、分布式登陆等,而高效还原DOM数据也将会有新的标准出现。

AngularJs就是一个扩展HTML的前端模板框架。

模板阻碍前后分离

软件研发工作在不断细化,前后分离是大势所趋,但是你直接将后端JSP模板交个前端,那前端是没法做工作的,因为就像前面所说,很多人不认识JSP这个东西。对于前后分离其实在很多项目中都有很好的例子,比如传统CS架构的项目就是前后分离,C与S之间的沟通使用标准的通信协议。协议为异构系统而生,以协议作为分界线是最简单,是时候放弃模板使用静态H5页面了。

性能不是放弃后端模板的理由

多年以来大家虽然深知模板的坏处,却没有人去号召改变,这个可能和国人的本性有些关系。还有就是因为有人说“模板可以显著增加浏览器性能”。互联网早期时代,用户的PC确实性能不高;摩尔定律下的硬件更新速度大于WEB发展速度,当人们已经需要RIA时,HTML还没有反应过来,FLEX,SilverLight进入这个空白期。对于大多用户的浏览器已经能跑动RIA插件时,再说HTML模板性能真的就是老顽固了。

你仍然可以尝试使用淘宝UDE的大前端分离思路,前提是要有足够的前端供你变更人员结构。

参考文章

动态页面,静态页面,伪静态页面的区别

如何来区分静态网页与动态网页