Stage 工程落地清单：从 Demo 到可维护 HarmonyOS 应用

前两篇我们已经把 Stage 工程目录、首页加载、资源管理和页面跳转讲清楚了。从这一篇开始，重点放到 Stage 模型本身：哪些代码应该放在 AbilityStage，哪些代码应该放在 UIAbility，哪些场景应该使用 ExtensionAbility，后台任务又应该怎样设计。

本文的目标很明确：让读者看完后能把概念落到工程里，而不是只记住几个类名。

在这里插入图片描述

1. 本章先解决什么问题

学完 Stage 模型后，真正落地项目要解决目录、职责、服务、排错和发布前检查。本文给出一套可执行清单。

如果你正在写 HarmonyOS 应用，可以先带着三个问题读本文：

  1. 这段代码应该放在入口、页面、服务层还是扩展能力里？
  2. 出问题时应该先查配置、生命周期、页面路由还是后台任务？
  3. 这个能力是否真的需要后台运行，还是可以交给前台页面或系统调度？

补充流程图：

理解：本章先解决什么问题

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

export interface 本章先解决什么问题StageNode {
  name: string;
  owner: 'AbilityStage' | 'UIAbility' | 'ExtensionAbility' | 'Page' | 'Service';
  responsibility: string;
}

export const 本章先解决什么问题Node: 本章先解决什么问题StageNode = {
  name: '本章先解决什么问题',
  owner: 'Service',
  responsibility: '把本小节的概念落到可复用工程代码中'
};

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把小节概念转成一个职责节点。写 Stage 工程时，先明确 owner，再决定代码放在哪个目录，能减少职责混乱。

2. 为什么需要工程清单

Demo 能跑不代表项目可维护。真实项目会持续增加页面、服务、资源、权限和后台场景，没有清单很容易越写越乱。

补充流程图：

理解：为什么需要工程清单

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

export interface 为什么需要工程清单StageNode {
  name: string;
  owner: 'AbilityStage' | 'UIAbility' | 'ExtensionAbility' | 'Page' | 'Service';
  responsibility: string;
}

export const 为什么需要工程清单Node: 为什么需要工程清单StageNode = {
  name: '为什么需要工程清单',
  owner: 'Service',
  responsibility: '把本小节的概念落到可复用工程代码中'
};

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把小节概念转成一个职责节点。写 Stage 工程时，先明确 owner，再决定代码放在哪个目录，能减少职责混乱。

3. 目录结构先稳定

页面放 pages，组件放 components，服务放 services，模型放 models，工具放 utils。结构稳定后，新功能才不会随手乱放。

补充流程图：

理解：目录结构先稳定

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

import { common } from '@kit.AbilityKit';

export class 目录结构先稳定ContextHelper {
  static getWorkPath(context: common.UIAbilityContext): string {
    return `${context.filesDir}/目录结构先稳定.json`;
  }

  static getCachePath(context: common.UIAbilityContext): string {
    return `${context.cacheDir}/目录结构先稳定.cache`;
  }
}

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把 Context 相关目录访问封装成工具方法。页面只拿结果，不直接到处拼路径，可以降低路径写错和目录混用的风险。

4. 入口边界要守住

AbilityStage 做模块初始化，UIAbility 做界面入口，ExtensionAbility 做系统扩展，ArkUI 页面做展示和交互。

补充流程图：

理解：入口边界要守住

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

export interface 入口边界要守住StageNode {
  name: string;
  owner: 'AbilityStage' | 'UIAbility' | 'ExtensionAbility' | 'Page' | 'Service';
  responsibility: string;
}

export const 入口边界要守住Node: 入口边界要守住StageNode = {
  name: '入口边界要守住',
  owner: 'Service',
  responsibility: '把本小节的概念落到可复用工程代码中'
};

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把小节概念转成一个职责节点。写 Stage 工程时，先明确 owner，再决定代码放在哪个目录，能减少职责混乱。

5. 服务层承担业务复用

网络、缓存、任务、配置、日志都应封装成服务，不要散落在页面事件里。

补充流程图：

理解：服务层承担业务复用

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

interface ExtensionRequest {
  type: 'service' | 'form' | 'share';
  payload: Record<string, string>;
}

export class 服务层承担业务复用ExtensionRouter {
  static route(request: ExtensionRequest): string {
    if (request.type === 'service') {
      return 'handle service request';
    }
    if (request.type === 'form') {
      return 'update form content';
    }
    return 'handle share content';
  }
}

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把不同扩展入口先统一成请求对象，再按 type 分发。这样可以避免把服务、卡片、分享逻辑全部写在一个生命周期回调里。

6. 排错要有固定路径

启动问题查 module.json5 和 EntryAbility，页面问题查 router 和 main_pages，后台问题查任务类型和系统限制。

补充流程图：

理解：排错要有固定路径

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

export interface 排错要有固定路径StageNode {
  name: string;
  owner: 'AbilityStage' | 'UIAbility' | 'ExtensionAbility' | 'Page' | 'Service';
  responsibility: string;
}

export const 排错要有固定路径Node: 排错要有固定路径StageNode = {
  name: '排错要有固定路径',
  owner: 'Service',
  responsibility: '把本小节的概念落到可复用工程代码中'
};

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把小节概念转成一个职责节点。写 Stage 工程时，先明确 owner，再决定代码放在哪个目录，能减少职责混乱。

7. 工程结构建议

建议把 Stage 相关代码按职责分层，不要把所有逻辑写在一个文件里。

entry/src/main/ets
├── entryability
├── entryabilitystage
├── extensionability
├── pages
├── components
├── services
├── models
└── utils

目录解释：

  1. entryability 放 UIAbility 入口。
  2. entryabilitystage 放模块级初始化。
  3. extensionability 放服务、卡片、分享等扩展能力。
  4. pages 放 ArkUI 页面。
  5. services 放可复用业务服务。

8. 从 Demo 到项目时怎么拆

官方示例通常为了让读者快速跑通，会把代码写得比较集中。真实项目不能一直停留在 Demo 写法，否则页面一多就会出现三个问题：入口文件越来越大、页面事件越来越重、后台和前台逻辑互相影响。

更推荐的拆法是：

  1. AbilityStage 只处理模块级初始化，例如日志、配置、轻量服务注册。
  2. UIAbility 只处理界面入口，例如生命周期、窗口创建、首页加载、Want 参数接收。
  3. ExtensionAbility 只处理系统扩展入口，例如服务、卡片、分享等非普通页面场景。
  4. pages 只写页面状态和交互，不直接堆复杂业务。
  5. services 承担可复用业务，例如任务调度、缓存、配置读取、数据请求。

一个判断标准很实用：如果这段代码离开当前页面后仍然有价值，就不要写死在页面里；如果这段代码只和启动入口有关，就不要放进组件里；如果这段代码需要系统以扩展方式调用，就不要强行放进 UIAbility。

补充流程图：

理解：从 Demo 到项目时怎么拆

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

export interface 从_Demo_到项目时怎么拆StageNode {
  name: string;
  owner: 'AbilityStage' | 'UIAbility' | 'ExtensionAbility' | 'Page' | 'Service';
  responsibility: string;
}

export const 从_Demo_到项目时怎么拆Node: 从_Demo_到项目时怎么拆StageNode = {
  name: '从 Demo 到项目时怎么拆',
  owner: 'Service',
  responsibility: '把本小节的概念落到可复用工程代码中'
};

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把小节概念转成一个职责节点。写 Stage 工程时，先明确 owner，再决定代码放在哪个目录，能减少职责混乱。

9. 实战代码

推荐目录结构

entry/src/main/ets
├── entryability
│   └── EntryAbility.ets
├── entryabilitystage
│   └── EntryAbilityStage.ets
├── pages
│   ├── Index.ets
│   └── Detail.ets
├── components
│   └── FeatureCard.ets
├── services
│   ├── AppConfigService.ets
│   └── TaskService.ets
├── models
│   └── CourseItem.ets
└── utils
    └── LogUtil.ets

代码解释：

  1. 这段代码对应本节的最小可运行思路。
  2. 重点不是复制粘贴，而是理解它放在 Stage 工程中的位置。
  3. 目录本身就是架构约束。越早稳定目录，后期越容易协作。

简单日志工具

import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0x0000;

export class LogUtil {
  static info(tag: string, message: string): void {
    hilog.info(DOMAIN, tag, '%{public}s', message);
  }

  static error(tag: string, message: string): void {
    hilog.error(DOMAIN, tag, '%{public}s', message);
  }
}

代码解释：

  1. 这段代码对应本节的最小可运行思路。
  2. 重点不是复制粘贴，而是理解它放在 Stage 工程中的位置。
  3. 统一日志入口后，调试和线上排查都会更方便。

10. 实战案例：做一个学习任务入口

下面用一个小案例把本章主题落到工程里。假设应用首页有一个“开始学习”按钮，点击后进入某个学习任务。页面只负责触发动作，任务参数和任务状态交给服务层维护。

export interface StudyTask {
  id: string;
  title: string;
  source: string;
  createdAt: number;
}

export class StudyTaskService {
  private static currentTask?: StudyTask;

  static create(title: string, source: string): StudyTask {
    const task: StudyTask = {
      id: `${Date.now()}`,
      title,
      source,
      createdAt: Date.now()
    };
    StudyTaskService.currentTask = task;
    return task;
  }

  static getCurrent(): StudyTask | undefined {
    return StudyTaskService.currentTask;
  }
}

代码解释：

  1. 页面不直接拼业务对象，而是调用服务层创建任务。
  2. StudyTask 明确了任务字段，后续传参、缓存、日志都会更清楚。
  3. 服务层可以继续扩展成持久化版本，不影响页面结构。

页面使用方式如下：

@Entry
@Component
struct Index {
  @State latestTitle: string = '暂无任务';

  build() {
    Column({ space: 16 }) {
      Text('Stage 学习任务')
        .fontSize(28)
        .fontWeight(FontWeight.Bold)

      Text(this.latestTitle)
        .fontSize(16)
        .fontColor('#5A6B7B')

      Button('开始学习')
        .height(48)
        .onClick(() => {
          const task = StudyTaskService.create('Stage 模型实战', 'home');
          this.latestTitle = task.title;
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

这段页面代码只做三件事：显示标题、响应点击、更新 UI。真正的任务对象由服务层创建，这就是从 Demo 走向工程化的第一步。

11. 常见问题

11.1 代码写了但没有生效

先检查配置文件是否声明了对应入口，再检查路径大小写是否一致。Stage 工程里很多问题不是代码逻辑错，而是配置没有把类和系统入口连接起来。

11.2 页面和 Ability 职责混在一起

页面负责展示和交互，Ability 负责入口和生命周期。业务逻辑如果多个页面都要用，应该沉到 services 层。

11.3 后台能力被系统限制

后台任务不能按桌面端思路设计。要先判断任务是否必须立即执行、用户是否能感知、是否可以延迟，再选择对应方案。

11.4 生命周期日志看不懂

建议给每个入口统一 tag，例如 EntryAbility、AbilityStage、TaskService。调试时按 tag 过滤日志，先看入口是否执行，再看页面是否加载，最后看业务服务是否被调用。

11.5 页面能打开但状态不对

优先检查状态是否应该放在页面中。如果状态需要跨页面共享，就放进服务层或持久化存储；如果状态只影响当前页面，再使用 @State 管理。

补充流程图：

理解：常见问题

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

export interface 常见问题StageNode {
  name: string;
  owner: 'AbilityStage' | 'UIAbility' | 'ExtensionAbility' | 'Page' | 'Service';
  responsibility: string;
}

export const 常见问题Node: 常见问题StageNode = {
  name: '常见问题',
  owner: 'Service',
  responsibility: '把本小节的概念落到可复用工程代码中'
};

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把小节概念转成一个职责节点。写 Stage 工程时，先明确 owner，再决定代码放在哪个目录，能减少职责混乱。

12. 运行验证清单

  1. 修改 module.json5 后重新构建安装。
  2. 给关键生命周期加 hilog。
  3. 页面路径统一使用 pages/页面名，不要写 .ets 后缀。
  4. 新增页面后同步更新 main_pages.json。
  5. 后台任务要记录任务状态，避免中断后无法恢复。
  6. 把可复用逻辑放进 services，不要散落在页面事件里。

补充流程图：

理解：运行验证清单

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

export interface 运行验证清单StageNode {
  name: string;
  owner: 'AbilityStage' | 'UIAbility' | 'ExtensionAbility' | 'Page' | 'Service';
  responsibility: string;
}

export const 运行验证清单Node: 运行验证清单StageNode = {
  name: '运行验证清单',
  owner: 'Service',
  responsibility: '把本小节的概念落到可复用工程代码中'
};

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把小节概念转成一个职责节点。写 Stage 工程时，先明确 owner，再决定代码放在哪个目录，能减少职责混乱。

13. 读者练习

建议你按下面步骤自己做一遍：

  1. 在现有 Stage 工程里新建一个 services 目录。
  2. 把页面里的任务创建逻辑移动到 StudyTaskService。
  3. 在 Ability 生命周期里加入 hilog。
  4. 新增一个页面，验证页面跳转和服务层状态是否正常。
  5. 把可复用文字移动到 string.json。
  6. 把可复用颜色移动到 color.json。
  7. 重新运行应用，确认入口、页面、服务层职责清晰。

如果这 7 步都能跑通，说明你已经不是只会改默认模板，而是开始按工程方式组织 Stage 应用了。

补充流程图：

理解：读者练习

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

export interface 读者练习StageNode {
  name: string;
  owner: 'AbilityStage' | 'UIAbility' | 'ExtensionAbility' | 'Page' | 'Service';
  responsibility: string;
}

export const 读者练习Node: 读者练习StageNode = {
  name: '读者练习',
  owner: 'Service',
  responsibility: '把本小节的概念落到可复用工程代码中'
};

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把小节概念转成一个职责节点。写 Stage 工程时，先明确 owner，再决定代码放在哪个目录，能减少职责混乱。

14. 本章总结

学完 Stage 模型后，真正落地项目要解决目录、职责、服务、排错和发布前检查。本文给出一套可执行清单。 真正写项目时，不要先问“这个 API 怎么调”，而要先问“这个能力应该属于哪一层”。职责边界清楚，Stage 工程才会越写越稳。

参考资料

  1. 华为开发者文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/stage-model-development-overview
  2. 华为开发者文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-background-tasks-1
  3. 华为开发者文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/start-with-ets-stage
    补充流程图：

理解：本章总结

确定代码位置

编写最小示例

运行验证

沉淀到工程结构

补充代码：

export interface 本章总结StageNode {
  name: string;
  owner: 'AbilityStage' | 'UIAbility' | 'ExtensionAbility' | 'Page' | 'Service';
  responsibility: string;
}

export const 本章总结Node: 本章总结StageNode = {
  name: '本章总结',
  owner: 'Service',
  responsibility: '把本小节的概念落到可复用工程代码中'
};

代码解释：

  1. 流程图先把本小节从概念、代码位置、实现、验证串起来，读者不会只看到一段抽象描述。
  2. 示例代码给出一个可以迁移到 Stage 工程中的最小写法。
  3. 这段代码把小节概念转成一个职责节点。写 Stage 工程时，先明确 owner，再决定代码放在哪个目录，能减少职责混乱。
# harmonyos # pytorch # 深度学习 # 华为
Logo
HarmonyOS开发者社区

讨论HarmonyOS开发技术，专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐

cover

鸿蒙原生 ArkTS 布局方式之手势组合：GestureGroup 的并行/串行/互斥实战

avatar HarmonyOS开发者社区
cover

鸿蒙原生 ArkTS 布局方式之拖拽手势实现 DragToSort 排序实战

avatar HarmonyOS开发者社区
cover

鸿蒙原生 ArkTS 布局方式之缩放手势实现 PinchToZoom 实战

avatar HarmonyOS开发者社区