工程结构与依赖库

本页介绍 JL_OTA_Harmony 工程的整体目录结构、模块划分（entry 与 lib_rcsp）、构建配置（hvigor / build-profile）以及依赖库的组织方式，帮助开发者快速理解工程的组成与各模块的职责边界。

Purpose and Scope

本页聚焦于 工程级结构与依赖管理，涵盖：

• HarmonyOS NEXT 工程的标准目录布局（AppScope、entry、lib_rcsp、hvigor 等）
• 根工程构建配置 build-profile.json5 中的模块注册与 SDK 兼容性声明
• 依赖声明方式：oh-package.json5、本地 HAR/AAR 依赖（jl-ota）与测试框架 @ohos/hypium
• 模块间的依赖关系与代码边界

本页不涉及具体的 OTA 升级业务流程、RCSP 协议报文细节或 UI 页面实现——这些属于「OTA 升级流程」「RCSP 协议」等兄弟页面的范围。如需了解升级整体流程，参见 OTA 升级流程相关文档。

Overview

JL_OTA_Harmony 是杰理科技（Jieli-Tech）面向鸿蒙生态推出的 OTA（Over-The-Air，空中升级）参考工程，版本信息为 JL_OTA_Harmony_v1.0.0_sdk_v1.0.1。工程采用 DevEco Studio 标准工程形态（modelVersion: 5.0.0），目标运行环境为 HarmonyOS（compatibleSdkVersion: 5.0.0(12)）。

工程从结构上拆分为两个 HAP/HSP 级模块，遵循「应用壳 + 能力库」的分层设计：

• entry：应用入口模块，承载页面与用户交互，是对外可见的 OTA 演示 App；
• lib_rcsp：RCSP（杰理私有通信协议）能力库模块，封装与设备通信、OTA 数据交互的底层能力，被 entry 依赖复用。

这种拆分的设计意图是：将可复用的协议/升级能力与具体业务页面解耦，使 lib_rcsp 能够在其他鸿蒙应用中被独立复用，同时降低单一模块的编译耦合度。

依赖层面，工程遵循 HarmonyOS 的 oh-package.json5 声明式依赖模型：

• 运行时依赖：通过本地 HAR 文件（jl-ota，即 JL_OTA_1.0.1-release.har）引入 OTA 能力包；
• 开发期依赖：@ohos/hypium（单元测试框架，v1.0.6）仅用于测试代码，不参与发布产物。

Architecture

下图展示工程的整体结构、模块划分与依赖关系：

flowchart TD
    subgraph sg_Project["JL_OTA_Harmony 工程根 (jl_ota_harmony)"]
        subgraph sg_Build["构建配置层"]
            BP["build-profile.json5"]
            OP["oh-package.json5"]
            HV["hvigor/hvigor-config.json5"]
        end

        subgraph sg_AppScope["AppScope"]
            APP["app.json5"]
        end

        subgraph sg_Entry["entry 模块 (应用壳)"]
            E_BP["entry/build-profile.json5"]
            E_OP["entry/oh-package.json5"]
            E_MOD["src/main/module.json5"]
            E_PAGE["src/main/ets 页面代码"]
        end

        subgraph sg_Lib["lib_rcsp 模块 (RCSP 能力库)"]
            L_OP["lib_rcsp/oh-package.json5"]
            L_MOD["lib_rcsp/src/main/module.json5"]
            L_ETS["lib_rcsp/src/main/ets RCSP 代码"]
        end

        subgraph sg_Libs["本地依赖目录"]
            HAR["lib/JL_OTA_1.0.1-release.har"]
        end
    end

    BP -->|"声明 modules: entry, lib_rcsp"| E_BP
    BP --> L_MOD
    E_OP -->|"file:./lib/JL_OTA_1.0.1-release.har"| HAR
    E_PAGE -->|"业务调用"| L_ETS
    L_ETS --> HAR
    HV --> BP

各组成部分说明：

设计意图：将构建配置（hvigor/build-profile）、应用声明（AppScope）与模块实现（entry/lib_rcsp）分层隔离，符合 DevEco Studio 多模块工程的最佳实践；HAR 以本地文件而非远端仓库引入，保证了离线构建的确定性，避免对第三方仓库的运行时网络依赖。

工程目录结构详解

JL_OTA_Harmony 工程根目录位于仓库的 code/app/JL_OTA_Harmony_v1.0.0_sdk_v1.0.1/jl_ota_harmony/jl_ota_harmony/ 下，采用 DevEco Studio 5.0（modelVersion 5.0.0）的标准工程布局：

jl_ota_harmony/
├── AppScope/                      # 应用级作用域配置
│   └── app.json5                  # 应用名称、图标、bundle 信息
├── build-profile.json5            # 根构建配置：产品、模块注册、SDK 版本
├── oh-package.json5               # 根包配置：工程元信息与顶层依赖
├── oh-package-lock.json5          # 依赖锁文件（锁定依赖版本）
├── hvigor/
│   └── hvigor-config.json5        # hvigor 构建引擎版本配置
├── entry/                         # 应用入口模块（可执行 HAP）
│   ├── build-profile.json5        # entry 模块构建配置
│   ├── oh-package.json5           # entry 模块依赖声明（含 jl-ota HAR）
│   └── src/
│       ├── main/
│       │   ├── module.json5       # entry 模块配置：页面、权限、能力
│       │   └── ets/               # ArkTS 页面与业务代码
│       └── ohosTest/
│           └── module.json5       # 测试模块配置
└── lib_rcsp/                      # RCSP 能力库模块（可复用库）
    ├── build-profile.json5        # lib_rcsp 构建配置
    ├── oh-package.json5           # lib_rcsp 依赖声明
    ├── oh-package-lock.json5
    └── src/
        ├── main/
        │   ├── module.json5       # lib_rcsp 模块配置
        │   └── ets/               # RCSP 协议与 OTA 能力实现
        └── ohosTest/
            └── module.json5

根构建配置：build-profile.json5

根 build-profile.json5 是工程的"装配清单"，它决定了哪些目录会被编译、目标 SDK 与运行 OS 是什么。实际源码内容如下：

{
  "app": {
    "signingConfigs": [
    ],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS",
      }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": [
            "default"
          ]
        }
      ]
    },
    {
      "name": "lib_rcsp",
      "srcPath": "./lib_rcsp",
    }
  ]
}

Source: build-profile.json5

要点解读：

• app.products[0]：定义名为 default 的产品，compatibleSdkVersion 为 5.0.0(12)（即 API 12，HarmonyOS NEXT），runtimeOS 为 HarmonyOS。这确定了工程只面向鸿蒙生态，不包含 Android 兼容目标。
• app.signingConfigs 为空数组：签名配置为空，意味着工程默认未绑定正式签名证书，开发者需要在 DevEco Studio 中为 default 产品配置自己的签名（自动签名或手动证书），才能将应用安装到真机。
• modules 数组：显式注册两个模块——entry（./entry）与 lib_rcsp（./lib_rcsp）。其中只有 entry 声明了 targets[0].applyToProducts: ["default"]，即该模块会随 default 产品参与构建；lib_rcsp 作为库模块被隐式编译并被打包进引用它的模块产物中。

根包配置：oh-package.json5

根 oh-package.json5 定义了工程元信息与顶层依赖。实际源码内容如下：

{
  "modelVersion": "5.0.0",
  "license": "",
  "devDependencies": {
    "@ohos/hypium": "1.0.6"
  },
  "author": "",
  "name": "jl_ota_harmony",
  "description": "Please describe the basic information.",
  "main": "",
  "version": "1.0.0",
  "dependencies": {}
}

Source: oh-package.json5

要点解读：

• modelVersion: "5.0.0"：对应 DevEco Studio 5.0 / HarmonyOS SDK 5.0 的包模型版本，决定依赖解析与构建插件的兼容行为。
• devDependencies：仅声明 @ohos/hypium: 1.0.6。hypium 是 OpenHarmony/HarmonyOS 官方单元测试框架，用于 ohosTest 测试代码，不会进入正式发布产物。
• dependencies: {}：根包本身不声明运行时依赖——运行时依赖（如 jl-ota HAR）下沉到具体模块（entry）的 oh-package.json5 中声明。这种"根包只放公共开发依赖、模块包放业务依赖"的约定，可以避免依赖作用域污染。
• 工程名 jl_ota_harmony、版本 1.0.0 与仓库 JL_OTA_Harmony_v1.0.0_sdk_v1.0.1 目录命名一致，SDK 版本 v1.0.1 对应 HAR 包 JL_OTA_1.0.1-release.har。

模块职责划分

entry 模块（应用壳）：entry/src/main/module.json5 声明了入口页面、系统权限等；src/main/ets 中存放 ArkTS 页面，负责 OTA 升级的交互演示。它是产品 default 唯一直接构建的模块，是 OTA 功能的对外呈现层。

lib_rcsp 模块（能力库）：lib_rcsp/src/main/ets 中实现 RCSP 协议栈与设备通信逻辑。作为库模块，它不直接产出 HAP，而是通过 HAR 的形式被 entry 编译进最终应用。将协议层与 UI 层分离，是复用 RCSP 能力的关键设计：任何鸿蒙应用只需依赖 lib_rcsp 即可获得与杰理设备通信的能力。

依赖库组织

本地 HAR 依赖：jl-ota

工程的核心运行时依赖是杰理 OTA 能力 HAR 包 JL_OTA_1.0.1-release.har。README 中给出了接入方式：将 libs/ 目录（仓库随附）下的 HAR 文件复制到工程的 lib 目录，并在模块的 oh-package.json5 中通过 file: 协议声明依赖：

{
  "dependencies": {
    "jl-ota": "file:./lib/JL_OTA_1.0.1-release.har"
  }
}

Source: README.md

设计要点：

• file: 协议：HarmonyOS 的 ohpm 支持通过 file: 前缀引用本地包/HAR，无需发布到 ohpm 中央仓库。这保证了构建的离线可用性与版本确定性——HAR 随仓库分发，不依赖网络。
• 版本对齐：HAR 文件名中的 1.0.1 与仓库目录 sdk_v1.0.1 对应，README 也同时说明需要配套使用对应的 SDK 版本，避免 HAR 与上层代码的 API 不匹配。

测试依赖：@ohos/hypium

@ohos/hypium（v1.0.6）是唯一的开发期依赖，用于 entry/src/ohosTest 与 lib_rcsp/src/ohosTest 目录下的单元测试/集成测试。它支持 describe/it/expect 风格的 BDD 断言，与 HarmonyOS 的测试框架集成，保证工程质量的可验证性。

依赖拓扑

flowchart LR
    subgraph sg_Root["根包 jl_ota_harmony"]
        ROOT["oh-package.json5<br/>devDeps: hypium"]
    end
    subgraph sg_EntryMod["entry 模块"]
        ENTRY["entry/oh-package.json5<br/>deps: jl-ota (file HAR)"]
    end
    subgraph sg_LibMod["lib_rcsp 模块"]
        LIB["lib_rcsp/oh-package.json5"]
    end
    subgraph sg_Ext["外部依赖"]
        HYPIUM["@ohos/hypium 1.0.6"]
        HAR["lib/JL_OTA_1.0.1-release.har"]
    end

    ROOT -->|"devDependencies"| HYPIUM
    ENTRY -->|"file:./lib/..."| HAR
    ENTRY -.->|"编译依赖"| LIB

依赖流向说明：运行时依赖链路为 entry → jl-ota HAR（OTA 核心能力）与 entry → lib_rcsp（RCSP 协议能力）；开发期依赖 hypium 仅服务于测试目标，不进入最终产物。

构建与编译流程

工程从源码到可安装产物的构建流程由 hvigor 驱动，按以下顺序执行：

flowchart TD
    Start([开始构建]) --> A["hvigor 读取<br/>hvigor-config.json5"]
    A --> B["解析根 build-profile.json5<br/>加载 products 与 modules"]
    B --> C["解析 oh-package.json5<br/>执行 ohpm 依赖解析/安装"]
    C --> D{"模块是否在<br/>产品 targets 中?"}
    D -->|"否 (lib_rcsp)"| E["作为库模块编译<br/>产出 HAR"]
    D -->|"是 (entry)"| F["编译 ArkTS 源码<br/>合并 lib_rcsp HAR 与 jl-ota HAR"]
    E --> F
    F --> G["生成 HAP 产物<br/>应用签名 (signingConfigs)"]
    G --> H([安装到真机/模拟器])

各阶段说明：

1. hvigor 初始化：读取 hvigor/hvigor-config.json5 确定构建引擎版本，随后解析根 build-profile.json5。
2. 产品与模块装配：根 build-profile.json5 中 modules 数组注册了 entry 与 lib_rcsp；只有 entry 的 targets[0].applyToProducts 指向 default 产品，因此 default 产品的构建产物由 entry 承载。
3. 依赖解析：ohpm 依据各模块的 oh-package.json5 解析依赖。entry 通过 file: 协议直接引用 lib/JL_OTA_1.0.1-release.har，无远端仓库请求。
4. 模块编译：lib_rcsp 作为库模块先被编译，entry 编译时合并 lib_rcsp 与 jl-ota 的代码/资源，产出最终 HAP。
5. 签名：由于根 signingConfigs 为空，正式构建前必须在 DevEco Studio 中为 default 产品配置签名（自动签名需要登录华为账号）；未签名产物只能用于调试。

配置选项参考

build-profile.json5（根）

oh-package.json5（根）

依赖项汇总

专业注意事项

常见失败模式与边界情况

1. 签名缺失导致安装失败：根 build-profile.json5 的 signingConfigs 为空。未配置签名时，default 产品构建出的 HAP 无法直接安装到真机（DevEco Studio 调试模式除外）。接入新设备前，必须先通过自动签名或手动证书补齐签名配置。

2. HAR 依赖缺失或路径错误：jl-ota 通过 file:./lib/JL_OTA_1.0.1-release.har 相对路径引入。若 lib/ 目录未随仓库同步、或路径被移动，ohpm 解析会失败，entry 模块编译报「模块未找到」。务必保持 lib/ 目录与 oh-package.json5 中声明的相对路径一致。

3. SDK/HAR 版本不匹配：工程声明 compatibleSdkVersion: 5.0.0(12)，仓库目录标注 sdk_v1.0.1。若 IDE 的 HarmonyOS SDK 版本过低或 HAR 被替换为其他版本，可能出现 ArkTS 编译期 API 缺失或运行期行为差异。升级 SDK 时需同步核对 jl-ota HAR 版本。

4. 模块注册遗漏：若新增模块（如新的能力库）只创建了目录与 oh-package.json5，却未在根 build-profile.json5 的 modules 数组中注册，hvigor 不会将其纳入构建，跨模块引用会直接失败。

一致性约束

• 包名与目录名一致性：根 oh-package.json5 的 name: "jl_ota_harmony" 与工程目录同名，避免混淆；变更工程名时需同步更新 oh-package.json5 与 AppScope/app.json5 中的 bundle 信息。
• 依赖锁文件：oh-package-lock.json5（根与 lib_rcsp 各一份）锁定依赖版本，提交时应一并纳入版本控制，保证团队构建可复现。

扩展点

• 新增能力库模块：参照 lib_rcsp 的模式——创建模块目录（含 build-profile.json5、oh-package.json5、src/main/module.json5），在根 build-profile.json5 的 modules 数组中注册，即可被 entry 或其他模块复用。
• 替换 OTA 能力包：jl-ota 以 file: 协议引入，升级 SDK 时只需替换 lib/ 下的 HAR 文件并同步修改 oh-package.json5 中的文件名即可，无需改动业务代码——这是本地 HAR 依赖隔离带来的低耦合优势。
• 测试扩展：ohosTest 目录配合 @ohos/hypium 可扩展模块级单元测试与集成测试，无需引入额外测试框架。

相关链接

• 仓库根目录说明：README.md
• 根构建配置：build-profile.json5
• 根包配置：oh-package.json5
• 应用级配置：AppScope/app.json5
• entry 模块配置：entry/module.json5
• lib_rcsp 模块配置：lib_rcsp/module.json5
• 构建引擎配置：hvigor-config.json5

说明：本页面向工程结构与依赖管理；OTA 升级业务流程、RCSP 协议细节与页面实现请查阅对应的兄弟页面文档。