鸿蒙掌上驾考宝典应用开发43：工程化实践——hvigor 构建与模块化配置

麦田ya

13人浏览 · 2026-08-18 09:45:04

麦田ya · 2026-08-18 09:45:04 发布

第43篇：工程化实践——hvigor 构建与模块化配置

在这里插入图片描述

一、引言

在大型项目开发中，工程化水平直接决定了团队的开发效率和代码质量。DriverLicenseExam 项目采用了鸿蒙推荐的 hvigor 构建系统，结合多模块架构，实现了高效的工程化管理。本文将深入解析项目的构建配置、依赖管理、代码质量保障等工程化实践。

二、hvigor 构建系统概述

2.1 hvigor 简介

hvigor 是鸿蒙生态的构建工具，类似于 Android 的 Gradle。它负责：

项目构建与编译
依赖管理
签名与打包
多模块并行构建

2.2 构建配置层次

项目的构建配置分为三个层次：

工程级 build-profile.json5    ← 全局配置
  ├── 签名配置
  ├── 产品配置（Flavor）
  └── 模块注册
      │
      ├── 模块级 build-profile.json5  ← 模块构建配置
      │   ├── apiType
      │   ├── buildOption
      │   └── targets
      │
      └── oh-package.json5  ← 依赖声明
          ├── 本地 HAR 依赖
          └── 远程依赖

三、工程级构建配置

3.1 build-profile.json5

项目根目录的 build-profile.json5 是整个工程的构建入口：

// build-profile.json5
{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "material": {
          "certPath": "***.cer",
          "keyStorePath": "***.p12",
          "keyStorePassword": "***",
          "keyAlias": "***",
          "keyPassword": "***"
        }
      }
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS"
      }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./products/entry"
    }
  ]
}

关键字段解析：

字段	说明	作用
signingConfigs	签名配置	调试/发布签名证书
products.name	产品名称	可用于多 Flavor 构建
compatibleSdkVersion	兼容 SDK 版本	控制最低支持版本
modules	模块列表	注册所有子模块

3.2 多产品构建

如果应用需要区分免费版和付费版，可以配置多个产品：

{
  "products": [
    { "name": "free", "signingConfig": "debug" },
    { "name": "paid", "signingConfig": "release" }
  ]
}

但目前项目只配置了一个 default 产品，保持了简洁性。

四、模块级构建配置

4.1 构建选项

每个模块（entry 和各个 HAR）都有独立的 build-profile.json5：

// products/entry/build-profile.json5
{
  "apiType": "stageMode",
  "buildOption": {
    "arkOptions": {
      "compileArkTS": true
    }
  },
  "targets": [
    {
      "name": "default",
      "applyToProducts": ["default"]
    }
  ]
}

关键字段：

apiType：stageMode（Stage 模型）或 featureMode（FA 模型）
compileArkTS：是否启用 ArkTS 编译器
targets：构建目标，可以针对不同产品定制

4.2 HAR 模块的构建配置

// commons/commonLib/build-profile.json5
{
  "apiType": "stageMode",
  "buildOption": {
    "arkOptions": {
      "compileArkTS": true
    }
  }
}

HAR 模块的构建配置比 entry 模块简单，因为它不需要 targets 和签名配置。

五、依赖管理

5.1 oh-package.json5 详解

oh-package.json5 是鸿蒙的包管理配置文件，类似于 Node.js 的 package.json：

// products/entry/oh-package.json5
{
  "name": "entry",
  "version": "1.0.0",
  "dependencies": {
    "exam": "file:../../components/exam",
    "aggregated_ads": "file:../../components/aggregated_ads",
    "aggregated_share": "file:../../components/aggregated_share",
    "app_setting": "file:../../components/app_setting",
    "check_app_update": "file:../../components/check_app_update",
    "collect_personal_info": "file:../../components/collect_personal_info",
    "feedback": "file:../../components/feedback",
    "membership": "file:../../components/membership",
    "module_city_select": "file:../../components/module_city_select",
    "search": "file:../../components/search",
    "guide": "file:../../components/guide",
    "@ohos_agcit/driver_license_exam_commonlib": "file:../../commons/commonLib",
    "@ohos_agcit/driver_license_exam_datasource": "file:../../commons/datasource",
    "@ohos_agcit/driver_license_exam_network": "file:../../commons/network"
  }
}

5.2 依赖类型

项目中使用的依赖有两种形式：

1. 本地 HAR 依赖——使用 file: 协议

"exam": "file:../../components/exam"

这种依赖方式直接将本地模块链接到当前项目，被依赖模块的任何修改都会实时反映到主项目中，非常适合组件化开发。

2. 命名空间隔离

"@ohos_agcit/driver_license_exam_commonlib": "file:../../commons/commonLib"

使用 @ohos_agcit/ 前缀进行命名空间隔离，避免不同 HAR 之间的名称冲突。这是一个推荐的最佳实践。

5.3 HAR 模块自身的配置

// commons/commonLib/oh-package.json5
{
  "name": "@ohos_agcit/driver_license_exam_commonlib",
  "version": "1.0.0",
  "description": "公共工具模块",
  "main": "Index.ets",
  "license": "Apache-2.0",
  "dependencies": {}
}

HAR 自身的配置需要指定：

name：包名，主模块通过这个名字引用它
main：入口文件，指定模块的导出入口
dependencies：HAR 自身的依赖（如果为空的 {} 则表示没有额外依赖）

六、模块导出管理

6.1 Index.ets——模块的对外接口

每个 HAR 通过 Index.ets 文件控制对外暴露的内容：

// commons/commonLib/Index.ets
export { CommonConstants } from './src/main/ets/constants/CommonContants';
export { CommonEnums } from './src/main/ets/constants/CommonEnums';
export { Logger } from './src/main/ets/utils/Logger';
export { PermissionUtil } from './src/main/ets/utils/PermissionUtil';
export { AccountUtil } from './src/main/ets/utils/AccountUtil';
export { PreferencesUtil } from './src/main/ets/utils/PreferencesUtil';
export { RouterModule } from './src/main/ets/utils/RouterModule';
export { CommonModel } from './src/main/ets/model/CommonModel';
export { FormatUtil } from './src/main/ets/utils/FormatUtil';
export { StringUtil } from './src/main/ets/utils/StringUtil';
export { PushUtils } from './src/main/ets/push/PushUtils';
export { showToast, PromptActionClass } from './src/main/ets/utils/PromptActionClass';

导出管理的原则：

最小暴露：只导出其他模块需要使用的类和方法
内部隐藏：模块内部使用的工具类、常量不应导出
统一入口：所有导出集中在 Index.ets 中

七、代码质量保障

7.1 代码检查配置

项目使用 code-linter.json5 配置代码检查规则：

// code-linter.json5
{
  "rules": {
    "arkts-identifiers": {
      "option": {
        "camelCase": true
      }
    }
  }
}

7.2 混淆配置

HAR 模块的 obfuscation-rules.txt 用于配置代码混淆规则：

// commons/commonLib/obfuscation-rules.txt
# 保留导出 API 不被混淆
-keep class com.example.commonLib.** { *; }

混淆可以增加逆向工程的难度，保护应用的安全性。

7.3 消费者规则

// commons/commonLib/consumer-rules.txt
# 消费者规则，确保 HAR 使用者的构建正确

consumer-rules.txt 定义了当其他模块引用此 HAR 时，应该应用的规则。

八、工程化最佳实践

8.1 模块划分原则

层级	目录	职责	依赖原则
公共层	commons/	工具类、数据源、网络	不依赖其他模块
组件层	components/	业务组件	只依赖 commons
产品层	products/	应用入口	依赖所有组件

8.2 版本管理

{
  "name": "@ohos_agcit/driver_license_exam_commonlib",
  "version": "1.0.0"
}

所有 HAR 使用独立的版本号管理，当接口发生变更时更新版本号，主模块根据版本号决定是否升级依赖。

8.3 构建优化

{
  "buildOption": {
    "arkOptions": {
      "compileArkTS": true
    }
  }
}

确保所有模块都启用 ArkTS 编译，这是鸿蒙推荐的现代化编译方式，性能优于传统 JS 编译。

九、总结

DriverLicenseExam 项目的工程化实践展示了鸿蒙多模块应用的完整构建体系：

hvigor 构建：分层的构建配置，支持多产品构建
依赖管理：file: 协议管理本地 HAR 依赖，命名空间隔离
模块导出：Index.ets 统一管理导出，最小暴露原则
代码质量：静态检查 + 混淆 + 消费者规则

这种工程化架构不仅确保了当前项目的可维护性，也为团队协作和持续集成奠定了坚实基础。

关键源码文件：

build-profile.json5 — 工程级构建配置
products/entry/build-profile.json5 — entry 模块构建配置
products/entry/oh-package.json5 — 依赖声明
commons/commonLib/Index.ets — 导出管理
code-linter.json5 — 代码检查
commons/commonLib/obfuscation-rules.txt — 混淆规则

人工智能6S服务平台

作为“人工智能6S店”的官方数字引擎，为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐

HarmonyOS 鸿蒙 Lab 调参台模式 —— 把「写完组件」和「验收完组件」之间的距离变成工程方法

人工智能6S服务平台

鸿蒙实战:快递包裹管理——双表设计、状态机与物流时间线(上)

人工智能6S服务平台

鸿蒙实战：快递包裹管理——状态筛选、详情抽屉与物流时间线(中)

人工智能6S服务平台

所有评论(0)

查看更多评论

麦田ya

@2301_80466357

已为社区贡献50条内容

鸿蒙掌上驾考宝典应用开发43：工程化实践——hvigor 构建与模块化配置

麦田ya

第43篇：工程化实践——hvigor 构建与模块化配置

一、引言

二、hvigor 构建系统概述

2.1 hvigor 简介

2.2 构建配置层次

三、工程级构建配置

3.1 build-profile.json5

3.2 多产品构建

四、模块级构建配置

4.1 构建选项

4.2 HAR 模块的构建配置

五、依赖管理

5.1 oh-package.json5 详解

5.2 依赖类型

5.3 HAR 模块自身的配置

六、模块导出管理

6.1 Index.ets——模块的对外接口

七、代码质量保障

7.1 代码检查配置

7.2 混淆配置

7.3 消费者规则

八、工程化最佳实践

8.1 模块划分原则

8.2 版本管理

8.3 构建优化

九、总结

所有评论(0)

温馨提示：您尚未绑定手机号

麦田ya