借助小程序容器技术，实现APP的热更新和灰度发布
一、背景
作为一个全国性的数字园区的物业APP，希望通过一个小程序灰度发布的形式，来服务全国不同地区的客户，每个地区的用户打开都是本地的一些服务。
每个地区独立运营停车找位、会议室预约、活动报名等小程序，每个地区都会有一些本地特色的服务生态。
传统方案下，APP发版周期通常以周计算，小程序任何改动——修复bug、调整页面——都需要重新打包、提交审核、等待上线。业务无法接受这个等待周期。
这里需要解决两个独立的问题：
- 热更新：小程序出bug或需要紧急变更，能否不重新发APP就修复
- 灰度发布：新版本小程序，能否先让部分用户看到，确认无问题再全量
二、热更新机制：小程序包与APP发版解耦
2.1 链路原理
通过FinClip后台管理小程序的完整生命周期：开发上传→审核→发布→用户打开时SDK自动检测并拉取最新包。整个过程与APP发版完全独立，小程序更新不需要APP重新提交应用市场审核。
具体来说，当用户在APP中打开某小程序时，SDK会向后台发起版本检测请求。如果后台有更新的版本，SDK自动拉取更新包。Android SDK 2.35.1版本开始支持配置离线小程序包路径，打开时优先使用离线包，同时后台更新包仍可正常拉取。
2.2 差量包与全量包
后台会自动计算与用户当前版本的差异包，用户只下载差异部分，而非完整包。差量更新可以显著减少每次热更新的流量消耗。
2.3 更新时机
SDK支持两种更新策略：
冷启动更新：APP启动时检测并下载，用户下次进入看到新版。
热启动更新：小程序在前台时，SDK后台静默下载，用户退出后重新进入时自动切换。
对于停车、预约等高频场景，建议采用静默下载+下次进入切换的策略，避免打断用户正在进行的操作。
三、灰度发布体系：后台配置即可生效
3.1 四种灰度维度
在FinClip后台创建小程序发布时，可以配置灰度规则，支持以下维度：
| 灰度维度 | 说明 |
|---|---|
| 百分比灰度 | 按用户比例下发，10%→30%→50%→全量 |
| 地区灰度 | 按省市下发给指定地区用户 |
| 自定义用户灰度 | 按用户ID列表精确匹配某个用户群 |
注：FinClip灰度发布支持按比例、按城市、按用户群三种维度。"系统版本灰度"属于扩展能力，实际支持情况需以后台可配置选项为准。
3.2 地区灰度直接解决多地区问题
数字园区的核心需求是"不同地区用户看到不同小程序"。这靠后台的地区灰度维度即可实现，APP端不需要任何代码改动。
在后台配置灰度规则时，选择「地区」维度，勾选对应省市，该地区用户打开APP时，SDK向后台发起请求，后台自动返回对应地区的小程序包。基于此，数字园区APP能够实现：不同的用户打开APP，可以看到不同的业务功能——北京用户看到停车v1.2，上海用户看到停车v1.3灰度版，企业用户看到专属功能小程序，普通用户则看到通用版。整个过程APP端不需要任何代码改动。
3.3 上下架组合策略
各地区后台独立管理小程序上下架，这是另一层隔离机制：
A地区后台：上架「停车小程序 v1.2」→ 仅A地区用户可见
B地区后台：上架「停车小程序 v1.3灰度10%」→ B地区首批用户尝鲜
上下架与灰度是两套独立机制，可组合使用也可以单独使用，视管理复杂度决定。
四、GrayVersionHandler：扩展灰度参数
4.1 什么时候需要扩展接口
后台配置能覆盖大多数场景。但当需要按「地区+用户类型」这类组合维度做灰度判断时，后台的单一维度规则就不够了。FinClip SDK暴露了AppletGrayVersionHandler接口，允许APP在启动小程序时注入自定义参数，透传给后台参与灰度匹配。
4.2 Android端代码示例
灰度发布配置参数的注入通过AppletGrayVersionHandler实现。SDK在加载小程序时调用getGrayAppletVersionConfigs(appId)方法，宿主应用在方法中返回自定义参数，SDK将参数透传给后台匹配灰度规则。
/**
* 获取灰度发布配置参数
*
* @param appId 小程序ID
* @return 灰度发布配置参数
*/
fun getGrayAppletVersionConfigs(appId: String): List<GrayAppletVersionConfig>?
FinAppClient.grayVersionHandler = object : AppletGrayVersionHandler() {
override fun getGrayAppletVersionConfigs(appId: String): List<GrayAppletVersionConfig>? {
return null
}
}
4.3 自定义参数注入
当后台灰度规则需要「地区+用户类型」等组合维度时，需要在方法中向后台注入参数。在后台创建灰度规则时定义自定义参数（如region、userType），在APP端getGrayAppletVersionConfigs方法中返回对应key-value，SDK会将其透传给后台，后台按组合条件匹配规则。
具体参数结构请参考后台灰度规则创建页面中的参数说明文档，实际接入时请以后台可配置的自定义参数名为准。
4.4 灰度按设备维度而非用户ID
需要特别说明灰度分组的维度：默认按设备ID划分，同一设备始终命中同一灰度桶，换账号登录不会导致用户看到不同版本。如需按用户ID灰度，需在APP端通过getGrayAppletVersionConfigs方法向后台透传用户ID参数，且在后台创建灰度规则时选择「指定用户发布」。使用自定义API传入用户ID时，默认的规则ID为xUserId。
五、完整工程路径
用户打开APP到看到对应版本小程序的完整链路：
用户打开APP
→ APP读取用户所在地区（GPS定位 / 用户注册信息）
→ 初始化SDK时设置用户ID（需要区分用户维度灰度时）
→ GrayVersionHandler.getGrayAppletVersionConfigs(appId) 注入 region 参数
→ SDK 向后台请求，后台按 region 匹配灰度规则
→ 后台返回对应小程序包（地区版本或灰度版本）
→ 用户看到该地区的小程序
灰度发布与热更新联动：先在部分地区以10%灰度发布新版→观察数据无异常→全量发布→所有地区用户收到新版。整个过程APP无需发版，业务可以随时调整。
六、技术边界
仅后台配置的局限：地区维度和百分比维度可独立使用，但组合维度（如地区+用户类型）需要GrayVersionHandler扩展。
多后台管理成本：各地区后台独立管理小程序上下架，地区越多，维护成本越高。适合3-5个地区的规模，地区过多时需要考虑后台账号体系和权限管理。
灰度百分比不可精确到用户：默认按设备维度，同一设备始终命中同一灰度桶。业务需要精确用户维度灰度时，务必在APP端注入用户ID参数，并在后台配置相应规则。
七、实战Pitfalls
7.1 注入参数值与后台配置不一致
现象：后台配置了region=beijing的灰度规则，但规则始终匹配不上。
原因：APP端注入的参数值与后台配置的参数值存在大小写、空格等差异，如后台写的是Beijing而APP注入的是beijing。
解决：在APP端维护一份地区枚举常量表，所有注入参数统一从枚举取值，禁止硬写字符串。
7.2 多维度灰度规则同时配置导致行为不符合预期
现象：同时配置了地区维度和百分比维度灰度，实际匹配结果与预期不符。
原因：当多维度规则同时存在时，FinClip按精确匹配优先原则——自定义参数匹配优先于地区匹配，地区匹配优先于百分比。建议先单维度测试，再逐步组合。
解决：灰度规则上线前，用测试设备逐个维度验证行为，全部符合预期后再开启组合规则。
7.3 按用户ID灰度但未注入用户ID
现象：后台配置了「指定用户发布」，圈定了用户ID列表，灰度规则却始终不生效。
原因：APP端没有向SDK注入用户ID参数，后台无法匹配到用户。
解决：通过getGrayAppletVersionConfigs方法向后台透传用户ID参数，注入时key为xUserId，value为当前用户ID，即可触发后台按用户ID匹配灰度。默认规则ID为xUserId。
需要的话可以在Gitee中了解一下：Gitee Finclip
