一、引言：规范编码的核心价值

在HarmonyOS开发中，ArkTS作为主流开发语言，其编码规范直接影响项目的可维护性、可读性和团队协作效率。新手常因不熟悉规范导致代码冗余、Bug频发，资深开发者也需统一规范以降低协作成本。本文结合华为官方规范及实战经验，拆解ArkTS核心编码规范，通过正反例对比+实战优化案例，帮助开发者快速掌握规范编码技巧。

二、核心编码规范拆解与实战

2.1 命名规范：见名知义，层次分明

命名是代码的“第一注释”，需遵循“语义化、无歧义、符合格式”三大原则，不同元素的命名规则各有侧重：

• 类/组件名：采用大驼峰命名法，完整表达功能，避免缩写。如“BankAccountManager”而非“bankaccmgr”，组件名需添加明确后缀，如“BalanceDisplayComponent”。
• 变量/函数名：变量用小驼峰，函数名以动词开头（如get、set、load）。作用域越大，命名越详细：成员变量命名需完整（如userAccountSecurityInfo），小函数局部变量可简化（如info）。
• 常量名：全大写+下划线分隔，明确语义，杜绝“魔鬼数字/字符串”。
• 正反例对比：

// 不规范：魔鬼数字+无意义命名
if (status == 1) {
  showMsg("success");
}

// 规范：常量替代+语义化命名
const TRANSACTION_SUCCESS = 1;
const MSG_SUCCESS = "交易成功";
if (transactionStatus == TRANSACTION_SUCCESS) {
  showMessage(MSG_SUCCESS);
}

2.2 代码格式与复用规范

格式统一是协作基础，复用设计是高效开发核心，重点关注三点：

1. 基础格式：使用IDE格式化工具（Ctrl+Alt+L），除build()方法外，每行代码必须以分号结尾；缩进用2个空格，避免Tab；多个变量定义不写在一行。
2. 重复代码复用：同一逻辑复制3次以上必须提取为共用组件或函数。如多页面重复的余额显示逻辑，可封装为通用组件。
3. 复用实战案例：

// 规范：提取共用BalanceDisplay组件
@Component
struct BalanceDisplay {
  @Prop label: string;
  @Prop balance: number;
  @Prop textSize: number;
  @Prop textColor: string;

  build() {
    Text(`${this.label}: ${formatCurrency(this.balance)}`)
      .fontSize(this.textSize)
      .textColor(this.textColor);
  }
}

// 调用示例
BalanceDisplay({
  label: "可用余额",
  balance: userAccount.balance,
  textSize: 18,
  textColor: "#007DFF"
});

2.3 类型标注与异常处理规范

ArkTS支持类型推断，但函数参数、返回值及重要变量必须显式标注类型，提升可读性；异常处理需用try-catch捕获，结合Hilog打印规范日志，便于问题排查。

// 规范：显式类型标注+异常处理
async loadUserFinancialData(userId: string): Promise<FinancialRecord[]> {
  try {
    const response = await fetchUserRecords(userId);
    if (!response.success) {
      hilog.error(0x0001, "UserService", "获取财务数据失败：%{public}s", response.msg);
      throw new Error("数据获取失败");
    }
    return response.data;
  } catch (e) {
    hilog.error(0x0001, "UserService", "异常：%{public}s", e.message);
    return [];
  }
}

三、实战优化：从“能用”到“优质”的改造案例

以一个简单的用户余额展示页面为例，对比改造前后的代码，直观体现规范价值：

// 改造前：不规范代码（重复+无意义命名+魔鬼数字）
@Entry
@Component
struct BalancePage {
  @State a: number = 10000; // 无意义命名
  build() {
    Column() {
      // 重复逻辑
      Text("账户余额: " + this.a)
        .fontSize(16).textColor("#333")
      Text("可用余额: " + this.a)
        .fontSize(18).textColor("#007DFF")
      if (this.a > 5000) { // 魔鬼数字
        Text("可申请大额转账")
      }
    }
  }
}

// 改造后：规范代码（复用+语义化+常量替代）
const MIN_LARGE_TRANSFER = 5000;
@Entry
@Component
struct BalancePage {
  @State userBalance: number = 10000; // 语义化命名

  build() {
    Column() {
      // 复用组件
      BalanceDisplay({label: "账户余额", balance: this.userBalance, textSize: 16, textColor: "#333"});
      BalanceDisplay({label: "可用余额", balance: this.userBalance, textSize: 18, textColor: "#007DFF"});
      // 常量替代魔鬼数字
      if (this.userBalance > MIN_LARGE_TRANSFER) {
        Text("可申请大额转账")
      }
    }
  }
}

四、总结：规范编码的落地建议

1. 新手入门：先熟记命名、格式规范，用IDE格式化工具辅助检查；2. 团队协作：制定统一的规范文档，定期代码审查；3. 持续优化：老项目迭代时同步修正不规范代码，新增代码严格遵守规范。遵循规范不仅能提升代码质量，更能降低维护成本，为后续分布式开发、多端部署打下基础。