一、前言

在鸿蒙商用项目、政企软件开发规范中，有一条强制编码准则：项目严禁出现魔法数字、硬编码字符串。所有业务状态、类型标识、接口常量、状态字典，必须通过枚举统一管理。

枚举是 ArkTS 最基础、最重要的规范化语法。绝大多数新手项目代码混乱、状态难以维护、多人协作冲突，根源都是：不会规范使用枚举、分不清静态枚举与动态枚举的业务边界。

很多开发者只懂基础静态枚举，不知道 ArkTS 支持动态可计算枚举，导致：

• 固定业务状态乱写硬编码，可读性极差

• 接口地址无法统一管理，迭代维护成本极高

• 动态配置场景无法复用常量，代码冗余

• 状态匹配异常、类型不严谨，隐性Bug频发

本文带你从零吃透鸿蒙枚举体系，包含：静态枚举、动态枚举、业务场景选型、完整代码示例、企业规范、高频踩坑总结，可直接用于项目整改、面试背诵、团队规范落地。

二、为什么项目必须用枚举？（不用枚举的真实危害）

1. 反面垃圾代码（项目高频乱象）

日常开发中，很多人习惯直接写数字、字符串判断业务状态：

if (status === 1) {
  console.log("待审核")
} else if (status === 2) {
  console.log("审核通过")
} else if (status === 3) {
  console.log("审核驳回")
}

这种写法存在四大致命问题：

• 可读性差：1、2、3 魔法数字，新人完全看不懂业务含义

• 维护成本高：状态变更需要全局检索修改，极易漏改

• 无类型校验：传错数字、传空值，编译不报错，运行崩溃

• 无法统一管控：无注释、无统一来源，多人开发标准混乱

2. 枚举的核心价值

枚举的本质：给固定业务值赋予语义、类型约束、统一管理能力。

• 语义清晰，代码自解释

• 全局统一常量，一处修改全局生效

• TS强类型约束，杜绝非法参数

• 适配政企编码规范，提升项目可维护性

三、静态枚举（企业项目首选）

1. 概念说明

静态枚举是 ArkTS 默认枚举形态，编译阶段直接确定固定值，运行时不可修改、不参与计算，性能最优、稳定性最强。

适用于：所有固定不变的业务状态。

2. 标准业务代码示例

新建全局枚举文件 common/enum/business_enum.ets

/**
 * 订单状态枚举
 * 静态枚举：固定业务状态、编译期定值
 */
export enum OrderStatus {
  PENDING = 1,    // 待支付
  PAID = 2,       // 已支付
  DELIVERED = 3,  // 已发货
  FINISHED = 4,   // 已完成
  CANCEL = 5      // 已取消
}

/**
 * 审核状态枚举
 */
export enum AuditStatus {
  WAIT = 0,    // 待审核
  PASS = 1,    // 审核通过
  REJECT = 2   // 审核驳回
}

3. 页面业务调用

import { OrderStatus } from '../common/enum/business_enum'

// 根据状态返回文本
function getOrderStatusText(status: OrderStatus): string {
  switch (status) {
    case OrderStatus.PENDING:
      return "待支付"
    case OrderStatus.PAID:
      return "已支付"
    case OrderStatus.DELIVERED:
      return "已发货"
    case OrderStatus.FINISHED:
      return "已完成"
    case OrderStatus.CANCEL:
      return "已取消"
    default:
      return "未知状态"
  }
}

4. 静态枚举核心特点

• 编译期确定值，运行零开销，性能最高

• 严格 TS 类型校验，业务严谨

• 不支持表达式、运算、动态拼接

• 适合所有固定字典、状态、类型

四、动态枚举（进阶业务专属）

1. 概念说明

很多开发者不知道：ArkTS 枚举支持动态表达式赋值。

动态枚举可以在枚举内部进行：字符串拼接、数学运算、函数取值、变量赋值，在运行阶段动态计算枚举值。

适用于：接口地址、环境配置、动态阈值、基于基础常量二次计算的场景。

2. 场景一：接口地址统一管理（最常用）

// 全局基础域名
const BASE_URL = "https://api.dev.harmonyos.com"

/**
 * 动态枚举：接口地址统一管理
 */
export enum ApiEnum {
  LOGIN_URL = BASE_URL + "/user/login",
  USER_INFO_URL = BASE_URL + "/user/getInfo",
  ORDER_LIST_URL = BASE_URL + "/order/getList"
}

3. 场景二：数值运算枚举

export enum TimeOutEnum {
  BASE_TIME = 1000,
  SHORT_TIME = BASE_TIME * 2,
  LONG_TIME = BASE_TIME * 5
}

4. 场景三：函数返回值赋值

function getAppVersion(): number {
  return 105
}

export enum AppConfigEnum {
  VERSION_CODE = getAppVersion(),
  MAX_RETRY_COUNT = VERSION_CODE + 5
}

5. 动态枚举核心特点

• 运行时动态求值，支持运算、拼接、函数取值

• 灵活性极高，适合多环境、动态配置业务

• 性能略低于静态枚举，业务层完全可忽略

五、静态枚举 VS 动态枚举 官方选型标准

对比维度	静态枚举	动态枚举
求值时机	编译期固定	运行时动态计算
性能	最优	良好
能力限制	仅固定值，不支持运算	支持拼接、运算、函数
适用场景	业务状态、字典、类型标识	接口地址、环境配置、动态阈值
项目推荐度	首选、优先使用	按需使用，不可滥用

六、企业项目枚举开发规范（可直接落地）

1. 强制使用静态枚举的场景

• 订单、支付、审核、账号状态

• 权限、角色、设备类型

• 弹窗类型、页面类型、操作类型

• 固定字典、状态码、业务标识

2. 允许使用动态枚举的场景

• 全局接口路径统一拼接

• 测试/生产多环境地址配置

• 基于基础常量二次计算的阈值

3. 禁止写法（项目红线）

• 禁止业务逻辑直接写魔法数字、硬编码字符串

• 禁止动态枚举滥用，所有常量全部动态计算

• 禁止枚举参数写 number 类型，丢失类型校验

• 禁止全局枚举散落页面，必须统一抽离公共目录

七、高频踩坑总结

坑点1：枚举传参不写枚举类型

错误写法：丢失类型约束，毫无意义

function setStatus(status: number)

正确写法：

function setStatus(status: OrderStatus)

坑点2：动态枚举滥用导致调试困难

动态枚举值运行时才可确定，过多使用会导致代码可读性下降、问题难以定位。固定业务一律静态枚举。

坑点3：前后端枚举值不统一

前端枚举私自定义值，和后端返回码不一致，导致状态匹配失效。必须前后端统一状态码文档。

八、面试高频问答

Q1：鸿蒙静态枚举和动态枚举的区别？

静态枚举在编译期确定固定值，性能高、稳定性强，适合所有固定业务状态；动态枚举支持字符串拼接、运算、函数取值，运行时动态计算，适合接口地址、多环境配置场景。项目开发固定业务优先静态枚举，动态配置按需使用动态枚举。

Q2：项目为什么要统一使用枚举，禁止魔法数字？

魔法数字可读性差、维护成本高、无类型校验，容易产生隐性Bug；枚举语义清晰、全局统一、支持TS强类型约束，便于多人协作与长期迭代，符合鸿蒙政企项目编码规范。

九、全文总结

枚举是鸿蒙项目规范化的基石。合理区分静态枚举与动态枚举的使用场景，能从根源解决代码混乱、状态不可控、迭代难维护的问题。