Atitit Atitit.软件兼容性原理----------API兼容 Qa7

Atitit Atitit.软件兼容性原理----------API兼容Qa7

1.兼容性的重要性与反面教材1

2.提升兼容性的原则2

2.1.What 与how分离2

2.2.老人老办法,新人新办法,只新增,少修改,莫删除3

2.3.计划赶不上变化,永远api修改也不可能整齐划一,反而带来不兼容的风险3

3.把握API的生命周期andAPI分级3

4.对兼容性保持友好的api设计方法3

4.1.细粒度的方法3

4.2.Ioc容器动态配置3

4.3.把你的method()视为全局global的,确保每一个方法都不重名尽可能。。不要幻想有模块命名空间等,这也是为了方便用户查询。。3

4.4.Api版本管理与 细粒度的方法Api版本管理4

4.5.使用ioc方法。 容器正是个好东西啊4

5.保持api兼容性的新版本升级方法4

5.1.不要重构以前的api内部具体实现,以达到无缝升级的效果4

5.2.不要向已经发布的接口里添加成员;创建新的接口来避免版本问题4

5.3.创建新的api应该使用什么标准???4

5.4.增加功能 增加新api  而不是  修改旧的api5

5.5.修改api (那就是尽可能不要修改api,使用增加来代替)5

5.6.增加参数 (可以通过可变参数json来扩充参数)5

5.7.增加返回值而原来api是void。。可以直接增加返回值,或者返回在某个成员变量上5

5.8.Threadlocal5

5.9.避免极端的意见在设计API的时候,一定要避免任何极端的意见,6

6.如何废弃api (使用depre标识,千万不要删除6

7.我们的app现在使用v1.0版api,如何慢慢切换到2.0呢7

1. 兼容性的重要性与反面教材

Java 与c#的兼容性走很好,win也很关注兼容性...

反面教材啊,也有啊..python3, cocos2d-js v3.x的问题

一旦上述提到的5个API中的任何一个发生变化,可能会给他们带来巨大的代价,用户需要排查所有调用的代码,需要更改一些协议,需要调整所有与之相关的部分,这些工作对他们来说都是额外的,在预期之外的。如果辛辛苦苦完成这些以后,还在测试过程中发现了相关的bug,那对用户的打击就更大了。如果API经常发生变化,用户就会失去对这段程序的信任,他们会更倾向自己获得源代码以后,按照自己的需求进行修改,自行维护一个内部的API比调用一个不断发生变化的外部API要容易接受的多,虽然这样做和我们协同开发、模块化开发的初衷是完全相悖的

保护用户在API上的已有工作用户过去在调用API、基于API开发所做的工作,这样才能给用户带来价值的同时,不破坏他们过去的劳动成果

2. 提升兼容性的原则

2.1. What 与how分离

例如,ui ,使用dsl  html5 css来定义ui ,不要使用native winform式的3gl语言

后端, 数据操作使用linq,sql  ,不要自己写一瓦代码,麻烦的.

 别的例如游戏,使用接口模式..定义一些api当dsl ,,使用实现来不同的实现..

例如cocos的定义场景,很麻烦的

// add bg

// var size = cc.director.getWinSize();

     this.bgSprite = new cc.Sprite(res.BackGround_png);

     this.bgSprite.attr({

         x: size.width / 2,

         y: size.height / 2,

     });

     this.addChild(this.bgSprite, 0);

使用dsl  html5 走容易的,还有标准的dw ide支持..可视化的ui设计.很方便的实现后端重构,不影响用户..

<div style=background:url(xxxxx.jpg); x:0; y:0>  </div>

后端解析这个html dsl 定义,生成canvas对象走ok...

2.2. 老人老办法,新人新办法,只新增,少修改,莫删除

2.3. 计划赶不上变化,永远api修改也不可能整齐划一,反而带来不兼容的风险

3. 把握API的生命周期andAPI分级

· 为API分级:内部使用;二次开发使用;开发或试用中;稳定;弃用API。避免API被滥用的同时,我们可以通过调整API的级别,来扩大其影响力,也能更优雅的结束一个API的生命周期。

4. 对兼容性保持友好的api设计方法

4.1. 细粒度的方法

方法api功能越细,越任意单独升级方法版本

4.2. Ioc容器动态配置

兼容性的神器。。

4.3. 把你的method()视为全局global的,确保每一个方法都不重名尽可能。。不要幻想有模块命名空间等,这也是为了方便用户查询。。

一般使用事件做uuid后缀,基本可以确保不同。

4.4. Api版本管理与 细粒度的方法Api版本管理

可以直接在方法签名增加  xxx_v2()这样的实现版本方法即可。

粗粒度的api版本管理使用ioc组合不同的细粒度api

4.5. 使用ioc方法。 容器正是个好东西啊

5. 保持api兼容性的新版本升级方法

5.1. 不要重构以前的api内部具体实现,以达到无缝升级的效果

除非绝对必要,不要重构以前的api具体实现,而是新增一个。。。重构以前的api难免增加bug,带来不稳定。。 当然api接口的话,可以保留。。

就像java,很多升级都是重构以前的实现,可以带来更高的性能等,但风险较大,对能力要求较高。。。普通公司,还是新增为主。。这样新版本app可以使用新api,就版本app任然使用旧api即可。。

接口函数一旦发布就不能改了,要保持兼容性,拼写错误也不能改了,所以要仔细检查拼写,否则会被同行嘲笑很多年。著名悲剧:unix 的 creat

5.2. 不要向已经发布的接口里添加成员;创建新的接口来避免版本问题

5.3. 创建新的api应该使用什么标准???

简单的,使用世界流行的,标准化的标准走ok..

例如ui方面,使用h5标准,不足了补充使用wpf,,优点是资料多啊,你都可以不需要写api文档了,直接使用这个标准的资料走ok,资料足够..

后端语言api 了???使用流行的java ,js  ,可以补充c#风格拉..  C++ ,obj-c不推荐..

5.4. 增加功能 增加新api  而不是  修改旧的api

最好是增加新的api。。这样不用调整老的api..添加测试工作...

当然一些很小的的调整可以直接调整老的api

一些必须修改老api的,可以变成api0模式,在新的api里面调用即可。修改bug模式。。

新api的命名可以采用xxxV2的模式这样就可以兼容老api。。

5.5. 修改api (那就是尽可能不要修改api,使用增加来代替)

5.6. 增加参数 (可以通过可变参数json来扩充参数)

增加参数也可以通过threadlocal方式来实现,这样就不用改动原来的方法签名

5.7. 增加返回值而原来api是void。。可以直接增加返回值,或者返回在某个成员变量上

5.8. Threadlocal

它还有一些类似的方式用来使用,就是在框架级别有很多动态调用,调用过程中需要满足一些协议,虽然协议我们会尽量的通用,而很多扩展的参数在定义协 议时是不容易考虑完全的以及版本也是随时在升级的,但是在框架扩展时也需要满足接口的通用性和向下兼容,而一些扩展的内容我们就需要 ThreadLocal来做方便简单的支持。

简单来说,ThreadLocal是将一些复杂的系统扩展变成了简单定义,使得相关参数牵连的部分变得非常容易,以下是我们例子说明:

5.9. 避免极端的意见在设计API的时候,一定要避免任何极端的意见,

尤其是以下几点:必须漂亮(API一定要漂亮吗?前文已经说过了) API必须被正确地使用(用户很难理解如何正确的使用API,API的设计者要充分考虑API被误用的情况:如果一个API可能会被误用,那么它一定会被误用) 必须简单(我们总会面临复杂的需求,能两者兼顾的API是更好的API) 必须高性能(性能可以通过其他手段优化,不应该影响API的设计) 必须绝对兼容(尽管本文一直提到如何保证兼容,但是我们仍然要意识到,一些极少情况下会遇到的不兼容是可以容忍的) 一些具体的实施方案在一个API不可避免要消亡或者改变的时候,我们应该接受并且面对这个事实,下面列举了几种保证兼容性的前提下,对API进行调整的办法:将API标记为弃用,重新建立一个新的API。如果一个API不可避免要被消亡,这是唯一的办法。 为其添加额外的参数或者参数选项来实现功能添加 将现有API拆成两部分,提供一个精简的核心API,过去的API通过封装核心API上实现。这通常用于解决用户需要一个代码精简的版本时。

6. 如何废弃api (使用depre标识,千万不要删除

在一个API不可避免要消亡或者改变的时候,我们应该接受并且面对这个事实,下面列举了几种保证兼容性的前提下,对API进行调整的办法:

· 将API标记为弃用,重新建立一个新的API。如果一个API不可避免要被消亡,这是唯一的办法。

· 为其添加额外的参数或者参数选项来实现功能添加

· 将现有API拆成两部分,提供一个精简的核心API,过去的API通过封装核心API上实现。这通常用于解决用户需要一个代码精简的版本时。

· 在现有的API基础上进行封装,提供一个功能更丰富的包或者类

7. 我们的app现在使用v1.0版api,如何慢慢切换到2.0呢

每一个api下面有许多方法。。比如m1 m2

使用ioc方法。 先搞个api2.0,默认加载全部1.0的方法。。然后针对需要新加或者修改的方法,做2.0版本,然后在ioc里面配置,让api2.0使用那几个新版本方法。其他的方法任然可以使用就版本,即是可以任意组合细粒度的方法啦。。

Ref参考资料

如何做到API兼容 - 百度技术博客- 51CTO技术博客.html

如何保持API的兼容-永远即等待的专栏-博客频道- CSDN.NET.html

atitit 软件兼容性原理与实践v6  qa3.docx

作者:: 绰号:老哇的爪子 ( 全名::Attilax Akbar Al Rapanui 阿提拉克斯 阿克巴 阿尔 拉帕努伊 ) 

汉字名:艾提拉(艾龙),   EMAIL:[email protected]

转载请注明来源: http://www.cnblogs.com/attilax/

Atiend

相关推荐