功能包规范

概述

功能包是 HCompass 的核心单元，本文档定义了功能包的目录结构和命名规范。

目录结构

标准的功能包结构：

packages/
└── user/                       # 用户功能包
    ├── navigation/             # 导航构建器
    ├── services/               # 服务
    │   └── UserServiceImpl.ets
    ├── view/                   # 页面
    │   ├── UserProfilePage.ets
    │   └── UserSettingsPage.ets
    ├── viewmodels/             # ViewModel
    │   ├── UserProfileViewModel.ets
    │   └── UserSettingsViewModel.ets
    ├── models/                 # 数据模型（可选）
    │   └── UserModel.ets
    ├── components/             # 组件（可选）
    │   └── UserAvatar.ets
    ├── utils/              # 工具函数（可选）
    │   └── UserUtils.ets
    └── UserModule.ets          # 功能包生命周期

命名规范

文件命名

• View：XxxPage.ets（如 UserProfilePage.ets）
• ViewModel：XxxViewModel.ets（如 UserProfileViewModel.ets）
• Service：XxxService.ets（如 UserService.ets）
• Model：XxxModel.ets（如 UserModel.ets）
• Component：XxxComponent.ets（如 UserAvatar.ets）

类命名

• View：XxxPage
• ViewModel：XxxViewModel
• Service：XxxService
• Model：XxxModel

模块导出

Index.ets

// packages/user/Index.ets
// 导出模块创建函数
export { UserModule, createUserModule } from './src/main/ets/UserModule';

模块定义

// packages/user/UserModule.ets
/**
 * @file 用户模块
 * @description 实现 FeatureModule 接口，提供模块自动注册
 * @author JunBin.Yang
 */

import { Container } from '@core/di';
import { FeatureModule, RouteRegistry, ModuleContext } from '@core/module';
import { NavigationService } from '@core/navigation';
import { IUserInfoRepository, IUserNavSvc, 
  UserRoutes, USER_INFO_REPOSITORY_KEY, 
  USER_NAV_SVC_KEY } from '@shared/contracts';
import { UserInfoRepositoryImpl } from './services/UserInfoRepositoryImpl';
import { profileNavBuilderWrapper } from './navigation/ProfileNav';
import { UserNavSvcImpl } from './services/UserNavSvcImpl';

/**
 * 用户模块
 * 实现 FeatureModule 接口，支持自动注册
 */
export class UserModule implements FeatureModule {
  /**
   * 模块唯一标识
   */
  readonly moduleId: string = 'user';

  /**
   * 模块名称
   */
  readonly moduleName: string = '用户模块';

  /**
   * 模块版本
   */
  readonly version: string = '1.0.0';

  /**
   * 模块依赖
   */
  readonly dependencies: string[] = ['auth'];

  /**
   * 注册 DI 服务
   * @param container DI 容器
   */
  registerServices(container: Container): void {
    // 注册本模块服务
    container.register<IUserNavSvc>(USER_NAV_SVC_KEY, () => new UserNavSvcImpl());
    container.register<IUserInfoRepository>(USER_INFO_REPOSITORY_KEY, () => new UserInfoRepositoryImpl());
  }

  /**
   * 注册路由
   * @param registry 路由注册器
   */
  registerRoutes(registry: RouteRegistry): void {
    // 注册用户页路由
    registry.register(UserRoutes.Profile, profileNavBuilderWrapper);
  }

  /**
   * 注册路由守卫
   * @param navigationService 导航服务
   */
  registerGuards(navigationService: NavigationService): void {
    // 用户模块不需要额外的守卫，依赖 auth 模块的认证守卫
  }

  /**
   * 模块初始化
   * @param context 模块上下文
   */
  async onInit(context: ModuleContext): Promise<void> {
    console.info(`[UserModule] 模块初始化完成: ${this.moduleName} v${this.version}`);
  }

  /**
   * 模块销毁
   */
  onDestroy(): void {
    console.info(`[UserModule] 模块已销毁: ${this.moduleName}`);
  }
}

/**
 * 创建用户模块实例
 */
export function createUserModule(): UserModule {
  return new UserModule();
}

依赖管理

oh-package.json5

{
  "name": "@package/user",
  "version": "1.0.0",
  "description": "用户功能包",
  "main": "Index.ets",
  "author": "",
  "license": "MIT",
  "dependencies": {
    "@ohos/axios": "2.2.7",
    "@core/base": "file:../../core/base",
    "@core/di": "file:../../core/di",
    "@core/module": "file:../../core/module",
    "@core/common": "file:../../core/common",
    "@core/navigation": "file:../../core/navigation",
    "@core/network": "file:../../core/network",
    "@core/util": "file:../../core/util",
    "@core/designsystem": "file:../../core/designsystem",
    "@core/components": "file:../../core/components",
    "@core/ibestui": "file:../../core/ibestui",
    "@shared/state": "file:../../shared/state",
    "@shared/contracts": "file:../../shared/contracts",
    "@shared/types": "file:../../shared/types"
  }
}

最佳实践

1. 保持功能包独立

功能包应该是独立的，不直接依赖其他功能包：

// 推荐：通过契约依赖
import { IAuthService } from "@shared/contracts";

export class UserService {
  private authService: IAuthService;

  constructor() {
    this.authService = container.resolve<IAuthService>("IAuthService");
  }
}

// 不推荐：直接依赖其他功能包
import { AuthService } from "@package/auth";

export class UserService {
  private authService: AuthService;

  constructor() {
    this.authService = new AuthService();
  }
}

2. 合理划分功能包

按业务领域划分功能包：

packages/
├── auth/       # 认证功能包
├── user/       # 用户功能包
├── product/    # 产品功能包
├── order/      # 订单功能包
└── main/       # 主页功能包

3. 使用 MVVM 架构

严格遵循 MVVM 架构：

View (页面)
  ↓ 绑定
ViewModel (视图模型)
  ↓ 调用
Service (服务)
  ↓ 操作
Model (数据模型)

注意事项

1. 命名一致性：遵循命名规范
2. 目录结构：保持目录结构一致
3. 模块导出：正确导出公共 API

下一步

• 创建功能包 - 学习如何创建功能包
• 功能包示例 - 查看功能包示例