鸿蒙多目标产物构建

0 阅读11分钟

分为两部分

多目标产物构建

文档中心

手动签名:

文档中心

HUAWEI Developer

文档中心

鸿蒙的三层结构

按照鸿蒙的三层结构分为 common 层 ,feature 层,product 层;三层的依赖关系为 product->feature->common; 每层之间可以相互依赖;但是对于每层之间不能逆向依赖;

HarmonyOS官方文档把三层架构拆成三个明确的逻辑层次:公共能力层、基础特性层和产品定制层。开发者可以根据实际应用的复杂度,在三层的基础上在各层内部进行二次分层。

  • 公共能力层(commons):是整个架构中最底层的基石层,沉淀了所有跨业务复用的基础能力,如工具类库、通用UI组件、网络请求封装等。公共能力层可以编译成一个或多个HAR包或HSP包,只能被products层和features层依赖,绝对不能反向依赖。
  • 基础特性层(features):这一层封装了应用中相对独立的功能模块,如首页、个人中心、购物车等业务特性。每个feature应该具备高内聚、低耦合的特点,方便单独开发、测试和复用到不同设备的产品中。
  • 产品定制层(products):这一层负责针对不同设备形态进行功能和特性集成,各个子目录各自编译为一个Entry类型的HAP包,作为应用的入口模块。

分层依赖关系—绝对不能搞反三层架构的精髓在于依赖是单向的,绝对不能存在反向依赖。

依赖规则:|

  • 公共能力层(commons)不依赖任何层,独立存在
  • 基础特性层(features)可以横向调用及依赖公共能力层
  • 产品定制层(products)可以依赖公共能力层和基础特性层,但不能反向依赖features层,products层之间不允许横向调用

针对如何选择使用 har还是 hsp

image.png HAR与HSP的选择决策参考:

  • 被一个模块独占的工具类或UI组件—HAR
  • 被多个模块共享的公共库 一根据库体积决定,小的用HAR,大的用HSP
  • 需要单独部署的动态功能模块 —Feature HAP
  • 需要在多个设备形态间共用同一套代码 —Entry共包方案(HAP)
  • 设备间差异化较大 一 分包方案(为不同设备规划独立的Entry HAP包)

包类型划分流程图解:参照官方文档”包类型划分参考流程”—一先判断模块是否需要单独部署,若需要则选Feature HAP;若不需要,进一步判断是否被多个模块共享;若是且体积较大或需运行时加载,选HSP,否则选HAR。整个决策链条清晰简单。

多目标产物构建

    多目标产物在HarmonyOS系统中的应用主要体现在软件开发与分发方面,特别是针对不同用户群体、不同业务场景的需求进行定制化开发。多目标产物为开发者提供了更加灵活和高效的开发方式,使得应用能够更好地适应市场需求和变化。通过定制化开发,还可以更好地满足用户的个性化需求,提升用户体验。

基本概念

  • target:对应HAR、HSP、HAP的多目标产物。工程内的每一个模块可以定义多个target,每个Target对应一个定制的HAP、HAR包,通过配置可以实现一个模块构建出不同的HAP、HAR包。
  • product:对应App的多目标产物。一个HarmonyOS工程的构建产物为App包,一个工程可以定义多个product,每个product对应一个定制化应用包,通过配置可以实现一个工程构建出多个不同的应用包。

target支持以下维度的差异化定制:

  • 包名:不同target可以有不同的HAP包名
  • 设备类型 (deviceType):手机、平板、车机等
  • 源码集(source):哪些代码文件参与编译
  • 资源文件(resource):图片、布局、字符串等
  • buildOption配置:C++ SO依赖、混淆配置、ABI类型等

product(应用级发布单元)

    product是定义在整个工程级别的build-profile.json5中的配置单元。每个product对应一个完整的、可直接上架的App包。

可以把它理解为一张* ”超级套餐“* 。一个product可以引用多个模块的target,最终打包成一个完整的App包。比如定义一个 PhoneApp product,让它去打包所有模块里标记为 phone 的target,最终生成一个完整的、可上架的App。

搭建多目标产物构建:

第一步:

首先在创建多个 target; 在需要支持多个 target的module 中;找到 module文件下 -> Build-profile.json5文件 -找到 targets 数组 进行如下配置:

 "targets": [
    {
      "name": "default",//模块级 targets.name ↔ 工程级 modules.targets.name:这两个必须同名一一对应(都是 default/pad),工程级那个是对模块级那个的"引用+绑定"。
      "runtimeOS": "HarmonyOS",
      "source": {
        "sourceRoots": [
          './src/phone_page'
        ]
      },
      "config": {
        "buildOption": {
          "arkOptions": {
            "buildProfileFields": {
              'BASE_URL': "p.wo.home"
            }
          }
        }
      }
    },
    {
      "name": 'pad',
      'runtimeOS': "HarmonyOS",
      "source": {
        "sourceRoots": [
          "./src/pad_page"
        ],
        "abilities": [//这个地方是针对不同的包进行图标的单独配置
          {
            "name": "EntryAbility",
            "icon": "$media:startIcon",     // 构建 official target 时替换
            "label": "$string:app_name_pad",
            "launchType": "singleton"
          }
        ]
      },
      'resource': {
        "directories": [
          "./src/main/pad/resources",
          './src/main/resources'
        ]
      },
      "config": {
        "buildOption": {
          "arkOptions": {
            "buildProfileFields": {//这个的目的是配置执行的常量值,上面的路径是写死的
              'BASE_URL': "p.wo.home"
            }
          },
          "nativeLib": {//这个是针对 nativeLib 的配置
//            "filter": {//目的就是在 pad 包下,过滤掉该 so库
//              "excludes": [
//                "../libs/arm64-v8a/libentry.so"
//              ]
//            }
          }
        }
      },
    }

 ]

在配置module - targets时需要注意点如下:

1.模块级 targets.name ↔ 工程级 modules.targets.name:这两个必须同名一一对应(都是 default/pad),工程级那个是对模块级那个的"引用+绑定"。如果不一致就无法找到对应的 target;

2.如果在存在多个 target 同时 不同的 target 的资源路径不一致;那么就需要配置资源路径;同时注意 资源路径 以及文件名要一致,否则在切换product 时将无法获取对应资源;代码如下:

  phone:的路径配置
  "source": {
        "sourceRoots": [
          './src/phone_page'
        ]
      }

  pad 的路径配置
   "source": {
        "sourceRoots": [
          "./src/pad_page"
        ]
  }

image.png

image.png

注意:

1.pad_page和 phone_page 文件下的子文件夹,文件要完全一致;否则无法找到资源;

2.在引用资源时对应的import 路径要注意;不要选择指定的 target 路径下的资源;否则资源无法更换;选择路径如下:

import { getVersion } from 'phone/ets/pages/Version';//这个地方phone 对应目录名

如果针对资源配置代码如下:

pad的配置
'resource': {
        "directories": [
          "./src/main/pad/resources",//注意:第一个写的是新的配置路径
          './src/main/resources'//这里是原始的配置
        ]
      }
phone 的配置:如果使用默认的资源就无需配置

对应的文件目录:

image.png

注意:创建的target 的资源路径下的文件要和默认的文件保持完全一致;例如 string -name要一致;否则无法找到对应的资源;

第二步:

创建 product 以及配置对应的module-targets;

创建不同的 product,在工程目录下 build-profile.json5文件下进行配置;代码如下

"products": [
      {
        "name": "default",
        //工程级 modules.targets.applyToProducts ↔ products.name:这里填的必须是 product 名;和targets 中的 name 没有必要关联
        "signingConfig": "phone",
        "targetSdkVersion": "6.1.1(24)",
        "compatibleSdkVersion": "6.1.1(24)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        },
        "label": "$string:app_name",
        "bundleName": "com.verify.phone",
        "icon": "$media:startIcon",
        "bundleType": "app",
      },
      {
        "name": "pad",
        //构建一个pad的工程
        "signingConfig": "pad",
        "targetSdkVersion": "6.1.1(24)",
        "compatibleSdkVersion": "6.1.1(24)",
        "runtimeOS": "HarmonyOS",
        "buildOption": {
          "strictMode": {
            "caseSensitiveCheck": true,
            "useNormalizedOHMUrl": true
          }
        },
        "label": "$string:app_name_pad",
        "bundleName": "com.verify.pad",
        //bundleName 是应用的包名(Bundle 名称),用于标识应用的唯一性,相当于应用在系统中的"身份证号"
        "icon": "$media:startIcon",
        "bundleType": "app"
      }
]

创建和 module-targets 对应的 target

 "modules": [
    {
      "name": "phone",
      "srcPath": "./product/phone",
      "targets": [
        {
          "name": "default",
          "applyToProducts": [
            "default",
            'phone_release'
            //这个地方一定要和上方 products 中配置的工程名一致,否则找不到对应的工程
          ]
        },
        {
          //这个地方的配置,就是可以切换调用的资源数据。例如切换为 pad 那么就会读取 pad 资源信息;
          //todo 注意:使用三层架构时;针对依赖的目录,例如 下面的 login;在 target中也需要配置该配置
          "name": "pad",
          "applyToProducts": [
            "pad",
            "phone_release"
            //这个是对应上方 products 中配置的工程名
          ],
        },
      ]
    },
    {
      "name": "login",
      "srcPath": "./feature/login",
      "targets": [
        {
          "name": "default",
          "applyToProducts": [
            "default",
            'phone_release'
          ]
        },
        {
          //这个地方的配置,就是可以切换调用的资源数据。例如切换为 pad 那么就会读取 pad 资源信息;
          "name": "pad",
          "applyToProducts": [
            "pad",
            'pad_release'
            //这个是对应上方 products 中配置的工程名
          ],
        }
      ]
    }
 ]

这个地方需要注意;

1.存在 entry 库和多个module 库;如果module 库也需要根据不同的 product 切换不同的资源路径;那么module 库首先也需要在 module ->build-profile.json5文件 -> targets 下配置 targets(1);然后在工程目录中 在module->targets 中,按照(1)的 targets 的name 创建 target,并指定 product :

   "applyToProducts": [
            "pad",
            'pad_release'
            //这个是对应上方 products 中配置的工程名
          ]

2.项目一般在 debug 和 release 版本的应用资源一致;因此在applyToProducts 中,添加了 pad,pad_release两个产品;如果debug 和 release 的资源使用也不同;那么就需要单独配置如下;

//首先在项目 module - build-profile.json5下配置 targets
  {
      "name": 'pad-release',
      'runtimeOS': "HarmonyOS",
      'resource': {
        "directories": [
          "./src/main/pad_release_resource/resources",//优先级高
          './src/main/resources'
        ]
      }
    }

//然后再 工程目录 build-profile.json5下配置 targets
{
          "name": "pad-release",
          "applyToProducts": [
            "phone_release"
            //这个是对应上方 products 中配置的工程名
          ],
        }

3.针对创建 har 和hsp 的区别:

如果是 hsp 包,在项目级 build-profile.json5中配置多个 target ,并在工程目录中针对多个 target 指定 product ,那么在切换 product 时,module 会默认切换到对应的 target;同时不可以更改其他target:

image.png

如果是 har 包,在同样配置后;如果切换产品后;虽然 target 也会跟谁切换;但是还可以切换构建目标;但是切换后也无法进行更换 使用资源;原因在下方注意问题点中:

image.png

4.注意:在不同的 product 配置中,需要配置不同 bundleName ;这样就相当于生成多个 hap 包;类似于 Android 安装时检测 packageName 一样;同样还包含如下:

   "label": "$string:app_name_pad",
    "bundleName": "com.verify.pad",
     //bundleName 是应用的包名(Bundle 名称),用于标识应用的唯一性,相当于应用在系统中的"身份证号"
    "icon": "$media:startIcon",
    "bundleType": "app"

第三步:

配置签名:针对不同的product 可以选择不同的签名;或者针对debug 和release 也可以切换不同的签名;

一般用于自动生成;点击如下图片进行配置

image.png

然后就可以工程目录build-profile - signingConfigs中生成对的签名;然后再 products中,不同的 product 根据条件设置不同的签名即可;

 "signingConfig": "pad",

注意问题点:

1.问题:product 固定后,切换 target 还更改资源吗?

        一旦 product 固定,target 就唯一确定了,没有"再切 target"这个自由度。你真正能切的只有 product(和 buildMode)。切 product → 对应 target 自动生效 → 资源随之改变。

image.png

不能"固定 product 再切 target"——target 由 product 经 applyToProducts 唯一决定,你能切的只有 product。 target 的作用:定义"模块在某 product 下的整套编译方案"(资源、源码、常量、so、混淆、产物名),是实现"一套代码 → 多产物差异"的模块级载体。 想换资源:切 product(default→pad),并 Clean 重编,HAR 的 pad target 就会自动带上 pad_resource。

2.问题:在工程目录 build-profiler 下 module - target -applyToProducts 添加多个产品;在选择一个产品是然后切换 target 为啥也不能更换资源

applyToProducts 的正确语义是:

✅ 一个 target 可以服务多个 product(多个 product 共享同一套编译方案/资源)——这是"添加多个产品"的合法用途。

❌ 一个 product 绝对不能被多个 target 同时声明——这会造成归属冲突,构建系统无法确定用哪个 target。

为什么资源换不过来 因为冲突导致 pad 产品的 target 归属是不确定的。hvigor 在多个 target 都匹配同一个 product 时,通常会命中数组里第一个声明的 target——也就是 default target。 而 common_util 的 default target 在模块级 build-profile 里是这样的:

什么时候才在 applyToProducts 里放多个产品

    只有当你希望多个产品共用完全相同的模块编译结果时才这么做。比如你后面加的 release 产品,如果 pad 和 pad_release 想用同一套资源,可以:

{ "name": "pad", "applyToProducts": ["pad", "pad_release"] }

3.问题:如果想要根据不同的 product 设置不同的启动图标,可以在 entry- >build-profile.json5 ->targets 中添加如下配置 -abilities:

 {
      "name": 'pad_release',
      'runtimeOS': "HarmonyOS",
      "source": {
        "sourceRoots": [
          "./src/pad_page"
        ],
        "abilities": [//这个地方是针对不同的包进行图标的单独配置
          {
            "name": "EntryAbility",
            "icon": "$media:startIcon",     // 构建 official target 时替换
            "label": "$string:app_name_pad",
            "launchType": "singleton"
          }
        ]
      },
      'resource': {
        "directories": [
          "./src/main/pad/resources",
          './src/main/resources'
        ]
      },
      "config": {
        "buildOption": {
          "arkOptions": {
            "buildProfileFields": {//这个的目的是配置执行的常量值,上面的路径是写死的
              'BASE_URL': "p.wo.home"
            }
          },
          "nativeLib": {//这个是针对 nativeLib 的配置
            //            "filter": {//目的就是在 pad 包下,过滤掉该 so库
            //              "excludes": [
            //                "../libs/arm64-v8a/libentry.so"
            //              ]
            //            }
          }
        }
      },
    },