ArkTS 模块化开发：Index.ets 统一导出模式深度解析

一、引言

在 HarmonyOS 多模块工程中，模块间的接口设计直接决定了代码的可维护性和复用效率。ArkTS 语言继承了 TypeScript 的模块系统，并在此基础上提供了 Index.ets 作为模块入口文件——这实际上是门面（Facade）模式在模块化领域的经典应用。

本文以 commonLib 模块为切入点，深入分析 Index.ets 统一导出模式的五种导出语法、模块内部文件组织规范，以及循环依赖的检测与避免策略。

二、理解 Index.ets：模块的"门面"

2.1 什么是"门面"模式？

门面模式的核心思想是：为子系统中的一组接口提供一个统一的、更高层次的接口。在 HarmonyOS 模块工程中，Index.ets 就是这个"门面"——它屏蔽了模块内部的复杂实现细节，对外只暴露约定的公共 API。

当我们在 oh-package.json5 中配置了 "main": "Index.ets" 时，如：

{
  "name": "commonlib",
  "main": "Index.ets"
}

其他模块就可以通过简洁的 import { xxx } from 'commonlib' 来引用该模块的所有公共能力，而不需要关心模块内部的文件结构。

2.2 对比：有门面 vs 无门面

无门面模式——外部使用者需要了解模块内部的文件路径：

// ❌ 糟糕的做法：暴露内部实现细节
import { Logger } from 'commonlib/src/main/ets/utils/Logger';
import { WordCard } from 'commonlib/src/main/ets/models/WordCardModel';
import { RouterModule } from 'commonlib/src/main/ets/utils/RouterModule';

有门面模式——通过 Index.ets 统一导出：

// ✅ 优秀的做法：通过门面统一引用
import { Logger, WordCard, RouterModule, BreakpointModel } from 'commonlib';

后者的优势显而易见：调用方只需知道"从 commonlib 导入什么"，而无需关心"从哪里导入"。

三、五种导出语法详解

commonLib/Index.ets 中使用了五种不同的导出模式，每种都有特定的适用场景。

3.1 具名导出：export { … } from

最常见的模式，从指定路径导出具名的函数、类或常量：

// commonLib/Index.ets
export { Logger } from './src/main/ets/utils/Logger';
export { PreferenceUtil, PreferConstant } from './src/main/ets/utils/PreferenceUtil';
export { BreakpointType, BreakpointModel } from './src/main/ets/models/BreakpointModel';
export { RouterModule, RouterMap } from './src/main/ets/utils/RouterModule';
export { AudioPlayer } from './src/main/ets/utils/AudioPlayer';
export { NewWordManager, NewWordItem } from './src/main/ets/utils/NewWordManager';

适用场景：当源文件有多个导出项，但门面只想暴露其中一部分时。例如 PreferenceUtil.ets 内部可能还导出了 PreferenceHelper，但门面只暴露 PreferenceUtil 和 PreferConstant。

3.2 批量重导出：export * from

将源文件的所有导出项批量重导出：

// commonLib/Index.ets
export * from './src/main/ets/components/CommonHeader';
export * from './src/main/ets/components/TopBar';
export * from './src/main/ets/components/Banner';
export * from './src/main/ets/viewModel/PracticeRecordModel';
export * from './src/main/ets/viewModel/BrowsingHistoryModel';
export * from './src/main/ets/viewModel/OrderInfo';

适用场景：当源文件的所有导出都应该被公开时。尤其适用于 UI 组件文件（如 CommonHeader.ets），这些文件通常包含 @Builder、@ComponentV2 等装饰器的组件定义，所有导出都是公开 API。

3.3 混合导出：具名 + 批量

将多个导出项与批量导出结合在一个 Index.ets 中：

// commonLib/Index.ets — 20+ 条导出的混合使用
export { Logger } from './src/main/ets/utils/Logger';
export { PreferenceUtil, PreferConstant } from './src/main/ets/utils/PreferenceUtil';
export * from './src/main/ets/components/CommonHeader';
export * from './src/main/ets/components/TopBar';
export { WordCard, WordCardDataSource, DEFAULT_WORD_CARDS, WORD_CATEGORIES, WordCategory }
  from './src/main/ets/models/WordCardModel';
export { BreakpointType, BreakpointModel } from './src/main/ets/models/BreakpointModel';
export * from './src/main/ets/viewModel/PracticeRecordModel';

注意：当 export * 批量导出的内容与具名 export { ... } 有名称冲突时，具名导出的优先级更高。批量导出中的重复名称会被静默忽略。

3.4 Feature 模块的 Builder 导出模式

与 commonLib 不同，feature 模块（如 homePage、topicPage）的 Index.ets 主要导出 Builder 函数，供 entry 层的路由表注册使用：

// features/homePage/Index.ets
export { HomePageBuilder } from './src/main/ets/pages/MainPage';
export { FeaturedCoursesBuilder } from './src/main/ets/pages/FeaturedCourses';
export { MaterialDownloadBuilder } from './src/main/ets/pages/MaterialDownload';
export { ChapterPracticeBuilder } from './src/main/ets/pages/ChapterPractice';
export { SearchPageBuilder } from './src/main/ets/pages/SearchIndexPage';
export { SearchInputBuilder } from './src/main/ets/pages/SearchInputPage';
export { SecondListBuilder } from './src/main/ets/pages/SecondListPage';
export { ThirdListBuilder } from './src/main/ets/pages/ThirdListPage';
export { TopicHomePageBuilder } from './src/main/ets/pages/TopicHomePage';

这种模式的命名规范是 XxxBuilder，每个 Builder 是一个 @Builder 函数，被 RouterTable 通过名称反射调用：

// RouterTable.ets — 路由表注册示例
class RouterTable {
  static routerInit() {
    RouterModule.builderMap.set('HomePage', wrapBuilder(HomePageBuilder));
    RouterModule.builderMap.set('FeaturedCourses', wrapBuilder(FeaturedCoursesBuilder));
    // ...
  }
}

3.5 数据 + 类型联合导出

对于带有常量和接口的模型文件，一次性导出所有需要的内容：

// commonLib/Index.ets
export { BaseViewModel } from './src/main/ets/models/BaseViewModel';
export { Sample } from './src/main/ets/models/SampleModel';

// WordCardModel 同时导出了类、数据源、常量数组和接口
export { WordCard, WordCardDataSource, DEFAULT_WORD_CARDS, WORD_CATEGORIES, WordCategory }
  from './src/main/ets/models/WordCardModel';

最佳实践：每个模型文件应该同时导出声明的类、相关联的常量和类型定义。使用者通过一次 import 就能获得该模型相关的所有能力。

四、模块内部文件组织规范

良好的模块内部结构，配合统一的 Index.ets，可以大幅降低认知负担。

4.1 commonLib 模块的文件结构

commons/commonLib/
├── Index.ets                          # 门面：统一导出
├── oh-package.json5                   # 模块配置
└── src/main/ets/
    ├── utils/                         # 工具层
    │   ├── Logger.ets                 # 日志工具
    │   ├── PreferenceUtil.ets         # 持久化存储
    │   ├── AudioPlayer.ets            # 语音播放器
    │   ├── RouterModule.ets           # 路由引擎
    │   ├── NewWordManager.ets         # 生词管理器
    │   ├── BreakpointUtils.ets        # 断点监听工具
    │   └── ContextUtils.ets           # 全局上下文
    ├── models/                        # 数据模型层
    │   ├── WordCardModel.ets          # 单词卡片模型（500词）
    │   ├── BreakpointModel.ets        # 断点模型（@ObservedV2）
    │   ├── BaseViewModel.ets          # ViewModel 基类
    │   └── SampleModel.ets            # 示例模型
    ├── managers/                      # 业务管理
    │   ├── LearningPlanManager.ets    # 学习计划管理
    │   ├── ReminderManager.ets        # 提醒管理
    │   ├── NotificationManager.ets    # 通知管理
    │   ├── DailyChallengeManager.ets  # 每日挑战管理
    │   ├── StatisticsManager.ets      # 统计管理
    │   └── DashboardManager.ets       # 仪表盘管理
    ├── viewModel/                     # ViewModel 层
    │   ├── PracticeRecordModel.ets    # 练习记录
    │   ├── BrowsingHistoryModel.ets   # 浏览历史
    │   └── OrderInfo.ets             # 订单信息
    └── components/                    # UI 组件
        ├── CommonHeader.ets           # 通用头部
        ├── TopBar.ets                 # 顶部导航栏
        └── Banner.ets                 # 横幅广告

4.2 组织原则

1. 按功能分层：utils（工具函数）、models（数据模型）、managers（业务管理）、viewModel（视图模型）、components（UI 组件）
2. 扁平化优于嵌套：目录深度不超过 3 层（src/main/ets/xxx/）
3. 每个文件一个主要导出：每个 .ets 文件只定义一个主要的类或组件，文件名与导出名对应

五、循环依赖检测与避免

5.1 循环依赖的危害

在 ArkTS 中，循环依赖会导致运行时错误——模块初始化时发现依赖的模块还未加载完毕，从而抛出 undefined 或初始化失败。

例如，如果 commonLib 依赖了 answer_questions，而 answer_questions 又依赖了 commonLib：

commonLib → answer_questions → commonLib  // ❌ 循环依赖！

5.2 检测方法

1. 静态分析：使用 ohos-arch-guard 等工具分析模块依赖图

2. 手动追踪：查看每个模块的 oh-package.json5 依赖声明，画出依赖图

entry → homePage, topicPage, minePage, commonLib, login_info, answer_questions, feedback
commonLib → answer_questions

在上面这个依赖图中：entry → commonLib → answer_questions → commonLib？不对，需要检查 answer_questions 是否引入了 commonLib。

5.3 避免策略

策略一：提取公共接口
将接口定义放在独立的接口模块中，避免具体实现之间的相互引用。

策略二：依赖反转
让底层模块定义接口，上层模块实现接口。例如在 commonLib 中定义 IRepository 接口，各个 feature 模块去实现。

策略三：合理下沉
如果 commonLib 确实需要 answer_questions 中的某些类型，考虑将这些类型定义下沉到 commonLib 中。

// 将类型定义移到 commonLib
// commonLib/models/QuestionTypes.ets
export interface QuestionType { ... }

// answer_questions 引用这些类型
import { QuestionType } from 'commonlib';

策略四：延迟导入
在函数内部使用 import() 动态导入，但 ArkTS 对动态导入的支持有限，建议优先使用前三种策略。

5.4 项目中的循环依赖警示

在当前的工程中，commonLib 的 oh-package.json5 声明了：

{
  "name": "commonlib",
  "dependencies": {
    "answer_questions": "file:../../components/answer_questions"
  }
}

这意味着 commonLib 依赖了 answer_questions 组件。这是一个需要注意的设计决策——通常 commons 层应该保持纯洁。如果 answer_questions 也被配置为依赖 commonLib，就会产生循环依赖。建议仔细审查这一依赖关系的必要性。

六、最佳实践总结

1. 一个 Index.ets 一个模块：每个模块有且仅有一个公开的 Index.ets，禁止在模块外直接引用内部文件路径。

2. 命名一致性：导出的 Builder 函数统一命名为 XxxBuilder，工具类导出声明的类名。

3. 控制导出粒度：不要使用 export * from 'some-module' 批量重导出三方模块，只重导出本地文件。

4. 避免"过度门面"：Index.ets 只做导出，不要包含任何业务逻辑代码。导出语句本身已经足够。

5. 文档化导出项：对于复杂模块，可以在 Index.ets 头部添加注释，说明模块提供的主要能力。

/**
 * commonLib — 通用能力模块
 * 
 * 提供以下能力：
 * - Logger: 日志工具
 * - PreferenceUtil: 持久化存储
 * - RouterModule: 声明式路由引擎
 * - AudioPlayer: 语音播报
 * - WordCard/WordCardDataSource: 单词卡片模型
 * - BreakpointModel/BreakpointType: 响应式断点
 * - NewWordManager: 生词管理
 * - 等 20+ 个导出项
 */

七、总结

Index.ets 统一导出模式是 HarmonyOS 多模块工程中最基础也最重要的设计模式。它通过门面模式的思想，将模块内部的复杂实现转化为清晰的公共 API 边界。

在我们 11 模块的工程中，每个模块都有自己的 Index.ets 门面：commonLib 导出工具和模型、feature 模块导出 Builder 函数、components 模块导出业务组件。这种统一的接口设计使得模块间的协作变得简单而可控。

在下一篇《响应式架构：BreakpointModel 与多设备适配方案》中，我们将深入探讨如何利用 @ObservedV2 和 @Trace 装饰器构建响应式的多设备适配方案。