HarmonyOS掌上记账APP开发实践第15篇：ArkTS 类型系统深度解析 — 从接口到联合类型的灵活运用

ArkTS 类型系统深度解析 --- 从接口到联合类型的灵活运用

概述

ArkTS 是 TypeScript 的超集，继承了其丰富的类型系统能力，包括接口（interface）、类型别名（type）、联合类型、泛型等。在 MoneyTrack 项目中，类型系统不仅被用于定义数据结构，还被用于构建灵活的 API 约定和参数规范。良好的类型设计可以显著降低运行时错误，提升代码的可维护性和可读性。本文从实际代码出发，深入解析 ArkTS 类型系统的各种用法。

在大型项目中，强类型系统的价值尤为突出。它可以作为实时文档，让开发者在不阅读实现代码的情况下理解数据的形状；可以在编译阶段捕获类型不匹配的错误，避免将问题带入生产环境；还能提供精准的代码补全和重构支持，提升团队协作效率。ArkTS 继承自 TypeScript 的静态类型系统，为 HarmonyOS 应用开发提供了坚实的类型安全保障。

核心知识点

1. 接口（interface）与类型别名（type）

接口是 ArkTS 中最常用的类型声明方式，用于定义数据结构的形状：

export interface AssetRecordItem {
  assetId: number;
  name: string;
  icon: ResourceStr;
  type: AssetType;
  subType: number;
  category: AssetCategory;
  amount: number;
  note?: string;          // 可选属性
  isCustom?: boolean;
  ownerId?: number;
}

interface 支持可选属性（?）、只读属性（readonly）和继承（extends）。type 别名则更适合定义联合类型或复杂类型别名：

export type NavRouterInfo = {
  url: RouterMap | DialogMap;
  mode?: NavDestinationMode;
  param?: ESObject;
  onPop?: Callback<PopInfo>;
};

2. readonly 只读属性

readonly 关键字用于标记接口中的属性为只读，一旦对象被创建，这些属性就不能被重新赋值。这在定义 DTO（数据传输对象）和配置对象时尤为有用：

export interface UserProfile {
  readonly id: number;           // 用户 ID 不可变
  readonly createdAt: string;    // 创建时间不可变
  name: string;                  // 用户名可修改
  avatar?: ResourceStr;
}

// 使用场景：确保从服务端获取的数据不会被意外篡改
const profile: UserProfile = await fetchUserProfile();
// profile.id = 100;  // ❌ 编译错误：无法分配到 'id'，因为它是只读属性

只读属性在以下场景中非常实用：

• 实体标识符：数据库主键、UUID 等不允许修改的字段
• 时间戳：创建时间、日志时间等记录型数据
• 配置常量：应用初始化后不应变更的配置项

3. 接口继承 extends 的链式使用

接口可以通过 extends 实现继承，支持多层链式继承，从而构建层次化的类型体系：

// 基础接口
export interface BaseEntity {
  readonly id: number;
  createdAt: string;
}

// 单层继承
export interface AssetEntity extends BaseEntity {
  name: string;
  type: AssetType;
  amount: number;
}

// 链式多层继承
export interface BudgetEntity extends BaseEntity {
  budgetAmount: number;
  spentAmount: number;
}

export interface MonthBudget extends BudgetEntity {
  month: string;                 // 账期月份
  rolloverFromPrev: boolean;     // 是否从上月结转
}

这种链式继承模式在 MoneyTrack 中被广泛使用，例如 AssetEntity 继承 BaseEntity 获得通用字段，又可以被更具体的类型继承，形成清晰的类型层级，既减少了重复定义，又保证了字段的一致性。

4. interface vs type 对比

在实际开发中，interface 和 type 经常被混用，但两者各有侧重。下表从六个维度对比二者的差异：

对比维度	interface	type
声明合并	支持（同名自动合并）	不支持（同名报错）
继承/扩展	支持 extends 继承	支持通过 & 交叉类型扩展
联合类型	不支持直接定义	支持 (type A = B | C)
元组类型	不支持	支持 (type Tuple = string, number)
映射类型	不支持	支持 (type Readonly = { readonly K in keyof T: TK })
性能与推荐	优先用于对象类型定义	优先用于联合/工具类型

最佳实践 ：在 MoneyTrack 中，定义 API 响应体、数据库实体等对象结构时优先使用 interface，以便利用声明合并和更清晰的继承语义；而在需要联合类型、工具类型或元组时使用 type。

5. 枚举 enum 与联合类型的互转

ArkTS 中，枚举和联合类型可以互相转换，以适应不同的使用场景：

// 枚举定义（带显式值）
export enum BillType {
  EXPENSE = 'expense',
  INCOME = 'income',
  TRANSFER = 'transfer',
}

// 联合类型（轻量替代方案）
export type BillTypeUnion = 'expense' | 'income' | 'transfer';

// 枚举 → 联合类型（利用 keyof 提取所有枚举值）
export type BillTypeFromEnum = `${BillType}`;  // 'expense' | 'income' | 'transfer'

// 联合类型 → 枚举（手动映射）
export function toBillType(value: string): BillType {
  const map: Record<string, BillType> = {
    'expense': BillType.EXPENSE,
    'income': BillType.INCOME,
    'transfer': BillType.TRANSFER,
  };
  return map[value] ?? BillType.EXPENSE;
}

选择建议 ：当需要遍历所有可能取值、或需要与后端约定的固定值列表对应时，使用 enum；当只是临时约束某个变量的取值范围、或取值数量较少时，使用联合类型更为轻便。

6. 类型断言（as 关键字）

类型断言用于告诉编译器"我知道这个值的类型是什么"，在跨模块传递或反序列化场景中很常见：

// 从通用类型断言为具体类型
const rawData: ESObject = await api.fetchData();
const userData = rawData as UserProfile;

// 在联合类型中缩小范围
function handleBill(type: BillTypeUnion) {
  if (type === 'expense') {
    (type as string).toUpperCase();  // 断言为 string 调用字符串方法
  }
}

// 注意：类型断言不会进行运行时检查，如果类型不匹配会导致运行时错误

7. 类型守卫（typeof、instanceof）

类型守卫是运行时检查类型并在作用域内缩小类型范围的技术：

// typeof 守卫（处理原始类型）
function formatValue(value: string | number): string {
  if (typeof value === 'number') {
    return value.toFixed(2);       // 此处 value 被收窄为 number
  }
  return value.trim();             // 此处 value 被收窄为 string
}

// instanceof 守卫（处理类实例）
class ApiError extends Error { code: number = 500; }
class NetworkError extends Error { retryable: boolean = true; }

function handleError(error: ApiError | NetworkError) {
  if (error instanceof ApiError) {
    console.error(`API 错误 (${error.code})`);  // 可访问 code 属性
  } else {
    console.error(`网络错误，可重试: ${error.retryable}`);
  }
}

类型守卫让 TypeScript 的静态类型检查与 JavaScript 的运行时语义完美结合，是编写类型安全代码的重要工具。

8. 泛型约束

ArkTS 支持泛型，可以构建类型安全的可复用接口。commonlib 中的 DialogInfo 是泛型的典型应用：

export interface DialogInfo<T = Object | undefined> {
  name?: DialogMap;
  param?: T;
  onPop?: Callback<PopInfo>;
}

当调用弹窗时，可以指定具体的参数类型：

const result = await RouterModule.push<ConfirmParam>({
  url: DialogMap.COMMON_CONFIRM,
  param: { message: '确认删除？' },
});

9. 联合类型与 ESObject

联合类型允许一个值具有多种可能的类型：

export interface NavRouterInfo {
  url: RouterMap | DialogMap;
  param?: ESObject;
}

ESObject 是 ArkTS 特有的类型，表示任何 ArkTS 对象类型，通常用于跨模块传递不确定类型的参数。

10. 枚举的灵活运用

asset_base 中定义的 AssetFilterState 类型展示了类型别名与 Set 等集合类型的结合：

export interface AssetFilterState {
  selectedIds: Set<number>;
  isAllSelected: boolean;
}

项目案例

d:\HarmonyOS\WorkSpace\MoneyTrack1.0.3\commons\commonlib\src\main\ets\utils\router\Types.ets 中定义了 NavRouterInfo 和 DialogInfo<T> 泛型接口。d:\HarmonyOS\WorkSpace\MoneyTrack1.0.3\components\asset_base\src\main\ets\commons\Types.ets 中定义了 AssetFilterState 等丰富的类型。

最佳实践

1. API 参数类型安全 ：所有 API 调用都应明确参数和返回值的类型，避免使用 any 或裸 ESObject。定义专门的 Request 和 Response 接口，让编译器帮助检查参数是否正确。
2. DTO 类型定义规范 ：数据传输对象建议使用 interface 定义，字段名与后端 JSON 字段一一对应，只读字段（如 id、createdAt）使用 readonly 标记，防止业务层意外修改。
3. 类型复用优先 ：遇到相似的结构时，优先通过 extends 继承或泛型复用已有类型，避免重复定义导致不一致。
4. 合理选择 enum 与 union ：固定且有限的值集合优先用联合类型（更轻量），带显式值映射或需要遍历的场景用 enum。

总结

ArkTS 的类型系统为 HarmonyOS 应用开发提供了强大的静态类型保障。从基础的 interface 和 type，到进阶的 readonly、extends 链式继承、泛型约束、枚举互转、类型断言和类型守卫，这些特性共同构成了一个完整的类型安全体系。在实际项目中，合理运用这些类型特性，不仅能显著减少运行时 Bug，还能提升代码的可读性和团队协作效率。掌握类型系统的核心概念，是写出高质量 ArkTS 代码的关键一步。

参考文档

• ArkTS 类型系统指南
• 接口与类的最佳实践
• 泛型在 UI 框架中的应用