1. 兼容性背景

QAP自从发布以后，功能不断的增加，虽然QAP团队在提供新功能时都会向前兼容，但当不可预估的事情发生，需要发布重大变更版本时，考虑到QAP依托的千牛客户端在用户手机上更新有一定的延时性，旧版的千牛客户端对QAP新功能的支持会有一定的受限，所以在使用这些新功能的时候需要额外做兼容处理。

2. 兼容性解决方案

2.1 组件、API版本判断

当开发者使用了千牛在新版本才支持的组件、API的时候，可以查阅相关文档，获取组件文档的支持版本信息，用以下代码判断是否支持运行在用户的手机上。

组件

// 当客户端版本 > 5.10.0 时，展示图表组件
<Page title="Charts">
    QN.app.version.gt('5.10.0') ? 
        <LineChart dragEnabled={true} scaleEnabled={true} smooth={false} id="chart1">
		</LineChart>
    :null
</Page>

API

// 当客户端版本 > 5.8.2 时，通过QAP请求top服务
if (QN.app.version.gt('5.8.2')) {
  QN.top.invoke({
    query: {
        method: 'taobao.user.seller.get', 
        fields: 'nick,sex'                
    },
    success(result) {
        console.log(result);
    },
    error(error) {
        console.log(error);
    },
  });
} else {
  // 如果希望用户在最新版本的客户端上体验您的插件，可以这样子提示
  QN.toast({
    query: {
        text: '当前千牛版本过低，无法使用该功能，请升级到最新千牛版本后重试'
    }
  }).then(result => {
     console.log(result);
  }, error => {
     console.log(error);
  });
}

2.2 离线包版本隔离

当开发者新开发的QAP包在千牛的某些历史版本上存在兼容性问题时，可以采取版本隔离，让最新提交的包只生效在支持的客户端版本上。

如何使用

使用qap-cli工具打包QAP离线包，会自动在qap.json生成当前推荐的最低千牛客户端版本号。

{
  "min_qn_android": "5.8.2",//android最低版本
  "min_qn_ios": "5.8.2",//ios最低版本
}

拿此离线包在千牛应用平台控制台进行发布时，会自动在页面上显示当前离线包支持的最低版本。

QAP将不会向低于该版本号的千牛客户端下发当前版本的离线包，老版本的千牛客户端会继续使用老版本的插件应用。

开发者可以根据API和组件的使用情况手动更改qap.json中的最低版本配置。

2.3 降级处理

千牛在一些非常低的千牛版本上无法使用qap离线包，只能使用以往的web版本，或者当判断开发者提供的qap包存在问题时，千牛会降级使用配置的web版本。除此之外在下列两种情况下，开发者也可以考虑主动通知千牛降级使用配置的web版本
* 千牛历史版本，手机系统历史版本，QAP历史版本存在兼容性问题，不想继续维护
* 开发者版本隔离后不支持的版本考虑使用web版本

如何使用

千牛客户端如果发现需要降级会根据qap包的降级配置去查找降级页面，如果没有任何配置默认会使用插件的callbackUrl地址。
当使用qap-cli工具打包QAP离线包时，会自动生成QAP对应的降级版本。开发者可以将此降级版本发布自己的服务器上生成一个H5回调地址如http://path/to/callback/url/index.html。或者使用之前历史的web版本地址。然后将此地址配置在千牛应用平台控制台还可以可通过千牛应用平台控制台——开发工具——配置管理，设置降级的版本范围

降级配置支持测试、灰度、正式发布。可对指定用户进行降级。

降级配置为JSONArray，每个item为一种降级场景。

key :

qap.config.downgrade

内容：

[
    {
        "downgrade": true,  
    	//可选,客户端版本，未配置表明所有版本降级，该配置的size为2，即最小版本、最大版本
        "clientVersion": [
            "5.5.2",
            "5.6.1"
         ], 
    	//可选，jssdk版本，未配置表明根据QAP默认jssdk兼容逻辑降级，该配置的size为2，即最小版本、最大版本
        "jssdkVersion": [
            "1.0.2",
            "1.0.4"
         ],
        //可选，手机系统版本，未配置表明参照其他降级逻辑降级，该配置的size为2，即最小版本、最大版本
        "sysVersion": [
            "4.4.2",
            "6.0.1"
         ],
         "isQAP":true,
        "callbackUrl": "http://path/to/callback/url/index.html"
    },
    {
        "downgrade": true,
        "clientVersion": [
            "5.6.2",
            "5.8.1"
        ],
        "jssdkVersion": [
            "1.0.4",
            "1.0.10"
        ],
        "sysVersion": [
            "4.4.2",
            "6.0.1"
        ],
        "callbackUrl": "http://path/to/callback/url/index.html"
    }
]

降级配置的sysVersion、jssdkVersion、clientVersion。全部配置表明所有规则命中才降级

3.附录

• QAP使用文档会在组件、API等描述中带上各个功能所支持的最低千牛客户端版本号。
• 离线包发布，可参见插件（离线包）版本管理
• 配置发布，可参见配置管理使用介绍
  

FAQ