不同包类型的源码混淆建议

不同包类型的用途和构建流程存在差异，对不同包类型使用混淆时，开发者需要注意不同事项。本文针对HAP、HAR和HSP三种包类型，分别提供混淆建议，帮助开发者高效使用混淆。简要对应关系如下：HAP为应用安装与运行的功能模块，适用于应用端功能开发与发布；HAR为静态共享包，适用于组件化、能力沉淀与多模块/多工程复用；HSP为应用内动态共享包，适用于同一应用内多模块在运行时共享代码与资源。

为了对混淆在不同包类型下的行为有更清晰的理解，建议开发者在对不同包类型进行配置前，充分了解混淆原理及开启源码混淆步骤，并优先阅读Stage模型应用程序包结构（了解不同包类型之间的差异点）。

HAP包混淆建议

开启混淆规则。建议开启推荐的四项规则，其它选项按需添加。
HAP包的开发者需要重点知悉混淆规则的合并策略，确认清楚了解所有潜在影响本模块编译时混淆规则的情况。
在此基础上，还需了解哪种依赖包内的代码会跟随本模块一起参与编译混淆，因为这会影响混淆新生成的名称和部分全局生效（如属性名称）的白名单，从而影响到本模块最终的混淆效果。具体而言：
- 当依赖本地HAR包时，其代码会跟随本模块一起混淆，混淆前后的名称会体现在本模块的编译中间产物obfuscation/nameCache.json文件中。
- 当依赖发布态源码HAR包时，安装在工程级oh_modules目录下的代码会跟随本模块一起混淆，混淆前后的名称也会体现在本模块的编译中间产物obfuscation/nameCache.json文件中。
- 当依赖发布态字节码HAR包或HSP包时，参与编译的是其中的二进制字节码和声明文件，由于ArkGuard工具只支持源码级别的混淆，不支持对二进制字节码进行混淆，且为了保证声明文件中的接口与二进制中的实现的一致性，不会对这部分代码进行混淆。但是，若三方库未正确提供接口的声明或者未在consumer-rules中配置白名单，在HAP中使用这些三方库接口的地方可能会被混淆，此时HAP包开发者可以自行配置，来保证运行时的正确性。
为保证与发布态三方库交互使用的正确性，ArkGuard会自动将工程级oh_modules目录下的远程HAR包的导出名称及其相关属性添加到不混淆名单中。由于开发者可以引用依赖模块中的任意路径下的文件，因此这种导出名称的收集范围并不局限于入口文件如Index.ets，而是工程级oh_modules中的所有文件中的导出名称。

对于本地源码HAR包和本地HSP包，ArkGuard不会自动将其模块源码目录下各 .ets、.ts 源文件中的export导出名称收集到不混淆名单中。此类依赖属于工程内本地模块（非发布态、未安装至工程级 oh_modules），不参与与远程发布包相同的跨模块依赖解析及export自动收集流程，因此需由开发者按需配置白名单或借助混淆助手生成保留规则。

下表总结了常见依赖包的编译混淆情况：

展开

依赖模块	实际参与编译的文件	是否跟随本模块参与混淆	是否会传递保留配置给本模块	是否收集导出名称到不混淆名单中
本地源码HAR包	模块在本地的源码目录	是	是	否
发布态源码HAR包	工程级的oh_modules下的模块目录	是	是	是
发布态字节码HAR包	二进制字节码和声明文件	否	是	是
本地源码HSP包	不参与本模块编译	否	是	否
集成态HSP包	二进制字节码和声明文件	否	是	是

请先阅读ArkGuard混淆保留选项文档，了解在哪些场景下需要为各选项手动配置白名单。然后，将配置好的白名单添加到obfuscation-rules.txt文件中。
构建应用，验证HAP包功能。若功能异常，需排查白名单是否遗漏。
应用功能正常，即可发布应用包。

HAR包混淆建议

HAR包通用建议

HAR包的开发者需充分了解混淆配置文件以及混淆规则的合并策略，以及在被HAP包使用时的HAP包混淆建议中的注意事项，确保被应用依赖时本模块所有功能正常。
由于HAR包会影响使用它的主模块的混淆流程，无论HAR包是否开启混淆，都需配置 consumer-rules.txt，用于声明需传递给依赖方、并最终写入发布 obfuscation.txt 的规则。可写入 obfuscation.txt 的混淆选项与保留选项范围、合并方式见混淆规则合并策略，以确保主模块在开启混淆时，HAR包的功能保持正常。
由于consumer配置的传递性，HAR包开发者不应在其中配置开启混淆的能力，而应仅配置保留白名单的规则。为减少对依赖方的影响，建议仅使用-keep-global-name和-keep-property-name两种白名单配置。

本地源码HAR包

作为一个未发布的静态包，本地源码HAR包不会独立进行编译混淆，而是会跟随依赖它的主模块（如HAP）一同进行编译混淆，开发者需参阅HAP包混淆建议了解相关行为。

由于本地源码HAR包会随着主模块一同进行混淆，多个HAP或HSP依赖相同本地源码HAR时，本地源码HAR在不同模块中的混淆结果可能不同。当开启useNormalizedOHMUrl（即在工程级build-profile.json5文件中，将strictMode属性的useNormalizedOHMUrl字段设置为true）时，运行时只会加载一份HAR，导致HAP和HSP无法找到对应的HAR，从而在调用HAR的方法时出现找不到的问题。

解决方案：

使用混淆助手配置保留选项，选择HAR对外暴露的接口场景，并将生成的白名单添加到HAR的consumer-rules.txt文件中。
将本地源码HAR改造为字节码HAR，单独编译生成对应的HAR包，然后依赖此HAR包。

发布态源码HAR包

开启混淆规则。建议开启推荐的四项混淆规则，其它选项按需添加。
阅读ArkGuard混淆保留选项文档，了解在哪些场景下需要为各选项手动配置白名单。然后，根据这些场景完成白名单的配置，并将其添加到HAR对应的白名单文件中。
- obfuscation-rules.txt中配置HAR包对外导出接口及其相关属性名称、此次构建过程不能被混淆的名称等。
- consumer-rules.txt配置不能被二次混淆的接口、属性等名称。
HAR包功能验证。需注意，在构建本模块HAR时会进行一次混淆，当发布后的HAR包被使用方依赖时，如果使用方开启混淆，则本HAR包发布后的代码还会跟随使用方被二次混淆，因此需要充分验证使用方开启混淆时HAR包功能是否正常。
发布HAR包。

说明

当被其他模块依赖时，有以下两点需要注意：

ArkGuard会在使用方（如HAP）混淆时收集本发布态HAR包的export导出名称及其相关属性等名称到不混淆名单中。
ArkGuard会在使用方（如HAP）混淆时收集本发布态HAR包的obfuscation.txt文件中的白名单，但不会继续收集本HAR包依赖的HAR包（四方库）中的obfuscation.txt文件的白名单（这是由于在构建三方库时，已收集过四方库的名单）。因此，若发布态HAR包依赖其他HAR包，应锁定其版本号，避免采用动态版本依赖机制。 否则当四方库升级后，若白名单发生变更，则不会在HAP中生效，易引起稳定性问题。

发布态字节码HAR包

字节码HAR开启混淆后，无需在consumer-rules.txt中配置白名单，其余适配流程与发布态源码HAR包保持一致。这是因为ArkGuard是源码混淆工具，在发布构建字节码HAR包时只对本模块混淆一次。当其他依赖方引入该HAR包并开启混淆时，ArkGuard不会对其进行二次混淆。

HSP包源码混淆

HSP包通用建议

HSP包的开发者需充分了解混淆配置文件以及混淆规则的合并策略，以及在被HAP包使用时的HAP包混淆建议中的注意事项，确保被应用依赖时本模块所有功能正常。
由于HSP包是独立构建，并且只会构建一次，因此要重点关注模块内部的混淆效果，确保其他模块正常调用接口即可。
由于consumer配置的传递性，HSP包开发者不应在其中配置开启混淆的能力，而应仅配置保留白名单的规则。为了减少对依赖方的影响，建议仅使用-keep-global-name和-keep-property-name两种白名单配置。

本地源码HSP包

本地源码HSP包需明确对外提供的接口及其属性，并将这些名称配置到obfuscation-rules.txt和consumer-rules.txt中。
对于模块内部混淆效果，开发者可以参阅HAP包混淆建议中的所有建议。
功能验证时，应同时构建主模块和HSP包，验证HSP包的接口功能。

集成态HSP包

集成态HSP包要明确对外提供哪些接口及其相关属性，并将这些名称配置到obfuscation-rules.txt中。consumer-rules.txt文件中无需配置，因为编译产物中的tgz压缩包中包含har与hsp两个子压缩包，har包中的声明文件内定义的对外导出接口及其属性会被自动收集到白名单中。
对于集成态HSP包的内部混淆效果，开发者可以参阅HAP包混淆建议中的所有建议。
集成态HSP包在发布后会被各方依赖，需要充分验证使用方开启混淆时HSP包接口可以被正常调用。

说明

HSP生成obfuscation.txt的规则仅来源于当前模块的consumer-rules.txt文件。不包括依赖模块的consumer-rules.txt文件或obfuscation.txt文件。

开发者可以参阅HAP包混淆建议中的所有建议，确保集成态HSP包的内部混淆效果。集成态HSP包发布后需验证使用方开启混淆时接口可以被正常调用。