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:1466519819@qq.com

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

Atiend